Browser script
Capture referral codes when visitors land on your site.
The browser script reads the ref parameter from share links, stores it in a first-party cookie, and gives it back to you at signup. It's 3 KB and has no dependencies.
Install
Add this to every page, before the closing </body> tag.
<script
src="https://cdn.referralapi.example/v1/referral.js"
data-publishable-key="pk_test_9Fh2..."
defer
></script>Read the code at signup
import { getReferralCode } from '@referral-api/browser';
async function onSubmit(form: FormData) {
const referralCode = getReferralCode();
await fetch('/api/signup', {
method: 'POST',
body: JSON.stringify({
email: form.get('email'),
referralCode,
}),
});
}Your server then forwards referralCode with the signup event.
Where files go
A typical Next.js setup looks like this:
layout.tsx
referral.ts
route.ts
.env.local
package.json
Cookie details
| Setting | Value |
|---|---|
| Name | rapi_ref |
| Lifetime | Your program's attribution window, 60 days by default |
| Scope | First-party, your domain only |
| Consent category | Functional |
If you use a consent banner, call initReferral() only after the visitor allows functional cookies.
How is this guide?