Install the snippet

Referly’s client-side tracking is a single script tag. Once it’s on your site, every visitor who arrives from an affiliate link is recognised, recorded as a click, and remembered in their browser for the length of your cookie window — so that when they sign up or buy later, the right affiliate gets credit. This page covers where to get the snippet, where to put it, what it does once it loads, and how to prove it’s working.

Get your snippet

The snippet is generated for you with your program ID already filled in. In your Referly dashboard, open your program, go to the campaign settings, and copy the block under Insert this line of code in your website’s head tag. It looks like this:

Standard install

<script
  src="https://referly.so/affiliate-tracker.js"
  data-affiliate
  data-program-id="YOUR_PROGRAM_ID"
  async>
</script>

Three parts matter, and all three are required:

src

string

required

https://referly.so/affiliate-tracker.js. If your program is run through an agency white-label account, the dashboard gives you https://cdn.jsdelivr.net/npm/affiliate-tracker/dist/affiliate-tracker.js instead. Use whichever URL your dashboard shows — the script only recognises itself when loaded from a known origin.

data-affiliate

attribute

required

A valueless marker attribute. The tracker finds its own tag with script[data-affiliate], so if you drop this attribute the script loads and then does nothing at all. This is the single most common installation mistake.

data-program-id

string

required

Your program’s ID. Without it the tracker exits immediately.

async is recommended but optional. The tracker never blocks rendering and does its work after the page is parsed.

Passing the program ID in the URL instead

If your host strips unknown data- attributes from script tags, you can pass the program ID as a query parameter on the script URL:

<script src="https://referly.so/affiliate-tracker.js?programId=YOUR_PROGRAM_ID" async></script>

This is a fallback. Prefer the data- attributes when you have the choice.

Where to put it

Put the snippet in the head of every page on your site, not just your checkout or your homepage. Affiliates link to whatever page they want — a blog post, a pricing page, a landing page, a comparison article. If the tracker isn’t on the page the visitor lands on, no click is recorded and there is nothing to attribute the eventual sale to. Site-wide installation is the only configuration that reliably works.

Your site must be served over HTTPS. Referly writes its cookies with SameSite=None; Secure, which browsers reject on plain HTTP. On an insecure origin the script runs, calls the API, and then silently fails to persist anything.

Install by stack

<!doctype html>
<html>
  <head>
    <meta charset="utf-8" />
    <script
      src="https://referly.so/affiliate-tracker.js"
      data-affiliate
      data-program-id="YOUR_PROGRAM_ID"
      async>
    </script>
  </head>
  <body>
    ...
  </body>
</html>

// app/layout.tsx
import Script from "next/script";

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>
        {children}
        <Script
          src="https://referly.so/affiliate-tracker.js"
          data-affiliate=""
          data-program-id="YOUR_PROGRAM_ID"
          strategy="afterInteractive"
        />
      </body>
    </html>
  );
}

// pages/_document.tsx
import { Html, Head, Main, NextScript } from "next/document";

export default function Document() {
  return (
    <Html lang="en">
      <Head>
        <script
          src="https://referly.so/affiliate-tracker.js"
          data-affiliate=""
          data-program-id="YOUR_PROGRAM_ID"
          async
        />
      </Head>
      <body>
        <Main />
        <NextScript />
      </body>
    </Html>
  );
}

<script>
  var pushLap = document.createElement('script');
  pushLap.src = "https://referly.so/affiliate-tracker.js";
  pushLap.setAttribute('data-affiliate', '');
  pushLap.setAttribute('data-program-id', 'YOUR_PROGRAM_ID');
  document.head.appendChild(pushLap);
</script>

add_action('wp_head', function () {
  ?>
  <script
    src="https://referly.so/affiliate-tracker.js"
    data-affiliate
    data-program-id="YOUR_PROGRAM_ID"
    async>
  </script>
  <?php
});

For Google Tag Manager, use a Custom HTML tag on the All Pages trigger. A tag that only fires on your thank-you page is worse than no tag at all, because the click was never recorded on the landing page. For WordPress, a header-scripts plugin or your theme’s “custom code” box works just as well as functions.php. See the WordPress guide for the options.

What happens when the script loads

Understanding the sequence makes debugging much faster. On page load the tracker:

Loads the public-suffix helper it uses to work out your registrable domain, so cookies can be set on .your-domain.com and shared across subdomains.
Tests whether cookies are writable. If they aren’t, it falls back to localStorage for the whole session. See cookies and storage.
Checks for a cross-domain handoff on the incoming URL and restores attribution from it if present.
Reads your program ID off the script tag. No ID, no tracking.
Checks whether the URL carries any recognised referral parameter, and whether attribution already exists in storage. If neither is true it stops here — no network requests are made for ordinary visitors.
Fetches your program’s configuration to learn your URL parameter, your cookie duration, your approved cross-domain list, and whether debug mode is on.
Records the click against the affiliate and stores the result.
Sets window.affiliateRef and window.affiliateId, then fires the readiness events.

That step 5 short-circuit is deliberate: visitors who did not arrive from an affiliate link cost you nothing and trigger no requests.

Globals and events it exposes

Once the tracker has resolved, these are available on window:

Global	What it holds
`window.affiliateRef`	The affiliate’s referral code, or `null`
`window.affiliateId`	The click ID for this visit, or `null`
`window.createPushLapEmail`	Record a referred customer from a sign-up
`window.createPushLapSale`	Record a sale from the browser
`window.pushLapTrackAddToCart`	Record an add-to-cart event

And two events fire on window:

Event	Fires when
`affiliate_id_ready`	Attribution was resolved. `event.detail` carries `ref` and `clickId`
`affiliate_referral_ready`	The tracker has finished, whether or not attribution was found

Always wait for one of these before reading the globals or calling the functions — the tracker resolves asynchronously, so code that runs on DOMContentLoaded will usually run too early:

window.addEventListener("affiliate_referral_ready", () => {
  if (window.affiliateRef) {
    console.log("Referred by", window.affiliateRef, "click", window.affiliateId);
  }
});

Full details are in the JavaScript API reference.

Verify the installation

Visit your site with a referral parameter

Take a real affiliate link from your dashboard, or append your program’s parameter yourself, and open it in a fresh browser profile: https://your-domain.com/?ref=TESTCODE.

Check the globals

Open the browser console and run window.affiliateRef and window.affiliateId. The first should return the referral code; the second a numeric click ID as a string. If affiliateId still equals the referral code, the click request has not completed or failed.

Check storage

In Application → Cookies, look for two entries named after your program ID: one ending _affiliate_ref holding the code, one ending _affiliate_referral holding the click ID. If cookies were unavailable these appear under Local Storage instead.

Check the dashboard

Reload your program’s analytics. The click should appear against that affiliate within a few seconds.

Navigate away and back

Open your site again with no parameters. window.affiliateRef should still return the code — that’s the cookie window doing its job. See attribution and the cookie window.

If any step fails, turn on debug mode and read the console log — it narrates every decision the tracker makes.

Content Security Policy

If you run a CSP, the tracker needs three allowances. Note that the script is served from the apex domain while the API lives on www:

script-src  https://referly.so https://cdn.jsdelivr.net;
connect-src https://www.referly.so;

cdn.jsdelivr.net is required for the domain-parsing helper the tracker loads at startup. Blocking it degrades cookie scoping on subdomains.

Common mistakes

The data-affiliate attribute was dropped

Minifiers, tag managers, and some CMS “insert script” fields strip valueless attributes. The tracker locates itself with script[data-affiliate], so without it nothing happens and there is no error. In frameworks that require a value, write data-affiliate="".

Installed only on the checkout or thank-you page

Attribution is created on the landing page, not the converting page. If the snippet isn’t on the page the affiliate linked to, the visit is never attributed.

Serving the site over HTTP

Referly’s cookies are Secure. On HTTP they are silently discarded and attribution never survives a page navigation. This most often bites on local development against http://localhost.

Reading window.affiliateRef too early

The tracker resolves after one or two network round trips. Code in an inline script, or on DOMContentLoaded, runs first and sees null. Listen for affiliate_referral_ready instead.

Expecting it to re-run on client-side navigation

Two copies of the snippet on one page

Installing through both your theme and a tag manager loads the tracker twice. Remove one; duplicate clicks are the usual symptom.

Using a parameter your program doesn't use

The tracker only honours the referral parameter configured for your program. Testing with ?ref= when your program is set to ?via= produces nothing. See URL parameters.

URL parameters

Which parameters the tracker recognises and how to change yours.

Cookies and storage

What gets written to the browser, and the localStorage fallback.

Attribution and the cookie window

How Referly decides which affiliate gets credit.

Debug mode

Turn on console logging to troubleshoot an install.

JavaScript API

Record sign-ups, sales, and cart events from the browser.

Server-side tracking

Report conversions from your backend instead.

Getting started

Tracking

Server-side tracking

API

Webhooks

Integrations

Reference

Install the snippet

Get your snippet

Passing the program ID in the URL instead

Where to put it

Install by stack

What happens when the script loads

Globals and events it exposes

Verify the installation

Content Security Policy

Common mistakes

URL parameters

Cookies and storage

Attribution and the cookie window

Debug mode

JavaScript API

Server-side tracking

​Get your snippet

​Passing the program ID in the URL instead

​Where to put it

​Install by stack

​What happens when the script loads

​Globals and events it exposes

​Verify the installation

​Content Security Policy

​Common mistakes

​Related

URL parameters

Cookies and storage

Attribution and the cookie window

Debug mode

JavaScript API

Server-side tracking

Get your snippet

Passing the program ID in the URL instead

Where to put it

Install by stack

What happens when the script loads

Globals and events it exposes

Verify the installation

Content Security Policy

Common mistakes

Related