Tracking script

The tracking script runs on your marketing site and app. It gives every visitor a stable anonymous id, captures the referral code and click id from the landing URL, and tells Referalli about the visit. At signup you read that context back and pass it to your server.

Install

Add one script tag to every page, replacing tk_... with your org's tracking token from GET /v1/org:

<script src="https://referalli.com/t/tk_.../aff.js" async></script>

The script is generated for your token and cached for five minutes. An unknown token returns 404.

What it does on each page load

1. Reads the referral code from the first of the via, ref or aff query parameters, and the click id from ref_click_id.

2. Loads any context saved from an earlier visit, then saves the merged result under the key referally_ctx in localStorage and in a first-party cookie (SameSite=Lax, plus Secure on https). The context lasts as long as your longest active program's cookieWindowDays (60 days by default, 400 at most).

3. Keeps the existing anonymous id, or creates one like a_k3j9x0q7….

4. Sends POST /t/{trackingToken}/visit with anonId, code, clickId and the page URL, to the origin the script was loaded from.

A new via or ref_click_id replaces the saved one (last touch), unless every active program uses first_click: then the first referral is kept until it expires. Otherwise the saved values carry over between visits.

Referral parameters

The script reads the referral code from the first of via, ref and aff it finds, in that order, then from any extra parameters your org adds.

This order is the contract. Anything else that reads a referral code from a URL (your server, or an auth platform that captures it at sign-up) must use the same order, or a URL carrying two different codes credits one partner in the browser and another at sign-up. GET /v1/org/referral-params returns it exactly: builtIn (["via", "ref", "aff"]) first, then your org's params. Add the parameter a previous tool used (for example fpr for FirstPromoter or ps_partner_key for PartnerStack) so links partners already shared keep crediting them. An import from another tool (see the migration guides under Guides) adds its tool's parameter for you.

curl -X PUT $BASE/v1/org/referral-params \
  -H "Authorization: Bearer $KEY" -H "content-type: application/json" \
  -d '{"params": ["fpr"]}'
# { "builtIn": ["via", "ref", "aff"], "params": ["fpr"] }

Names are lowercase letters, digits and _, up to 10 of them. GET /v1/org/referral-params returns the list; owners and admins can change it.

Consent and script options

Set these attributes on the script tag:

<script src="https://referalli.com/t/tk_.../aff.js"
        data-persist="referral-only" data-cookie-days="30" async></script>

The context is a tracking cookie, so in many places it needs consent. You can load the script only after the visitor opts in, or load it in referral-only mode and call aff.forget() if they decline. aff.forget() deletes the cookie and the localStorage entry and stops the script sending anything else on that page.

Links without a redirect

Partners can link straight to your site with ?via=code instead of the /go link. When the visit call carries a code but no clickId, Referalli finds the link with that code and records the click at that point. Clicks recorded this way are not fraud-scored.

The window.aff API

Once loaded, the script defines window.aff:

Pass the context to your server at signup

The script does not create referrals. Your server does that by calling POST /v1/referrals/associate with its API key. Send the context along with your signup form:

<form id="signup" method="post" action="/signup">
  <input name="email" type="email" required />
  <input name="referally_anon_id" type="hidden" />
  <input name="referally_click_id" type="hidden" />
  <button>Create account</button>
</form>
<script>
  document.getElementById('signup').addEventListener('submit', function (e) {
    if (!window.aff) return;
    var ref = window.aff.getReferral();
    e.target.referally_anon_id.value = ref.anonId;
    e.target.referally_click_id.value = ref.clickId || '';
  });
</script>

Then, on your server, call associate with anonId and referralToken set from those fields.

Identify known visitors

Call identify when a visitor gives you something that identifies them, for example a newsletter signup before they create an account:

async function sha256Hex(text) {
  const bytes = new TextEncoder().encode(text);
  const digest = await crypto.subtle.digest('SHA-256', bytes);
  return [...new Uint8Array(digest)].map((b) => b.toString(16).padStart(2, '0')).join('');
}

const emailHash = await sha256Hex(email.trim().toLowerCase());
window.aff.identify({ emailHash });

emailHash is the lowercase hex SHA-256 of the lowercased email. Recording it gives attribution a fallback: a later associate call that sends the same emailHash can be matched to this visitor's earlier clicks even when the cookie is gone (see Attribution for the exact rule). identify never creates a referral by itself.

Public tracking endpoints

The script calls these endpoints. You can call them directly from a browser or app, for example from a native client.

All are public and authenticated only by the tracking token. They record facts; none creates a referral or a commission.