Install tolt.js

Add this to the <head> of every page, on your marketing site and your app.

<script
  async
  src="https://cdn.tolt.io/v2/tolt.js"
  data-tolt="YOUR_PUBLIC_KEY"
></script>

Find YOUR_PUBLIC_KEY in Dashboard → Settings → Integrations. It is safe in the browser and is not your API key.

acme.com/?ref=sam tolt.jsclick Tolt

In the browser

cookies.acme.com

tolt_referral8537db0b…

tolt_data

expires30d

In Tolt

click8537db0b…

partner_idpart_8fKq…

program_idprg_YxLm…

page/?ref=sam

The cookie lasts your program’s cookie duration (30 days by default).

Add it to your framework

HTML
Next.js
React
Vue / Nuxt
No-code

Paste the tag inside <head> on every page, or in your shared layout template.

index.html

<head>
  <script
    async
    src="https://cdn.tolt.io/v2/tolt.js"
    data-tolt="YOUR_PUBLIC_KEY"
  ></script>
</head>

Load it once in the root layout with next/script.

app/layout.tsx

import Script from "next/script";

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body>
        {children}
        <Script
          src="https://cdn.tolt.io/v2/tolt.js"
          data-tolt="YOUR_PUBLIC_KEY"
          strategy="afterInteractive"
        />
      </body>
    </html>
  );
}

Prefer a typed hook for signups? Use @tolt/tracking and render <ToltTracking publicKey="YOUR_PUBLIC_KEY" /> in a client component instead.

For Vite or Create React App, install @tolt/tracking and render the component once near the root.

npm install @tolt/tracking

src/App.tsx

import { ToltTracking } from "@tolt/tracking/react";

export default function App() {
  return (
    <>
      <ToltTracking publicKey="YOUR_PUBLIC_KEY" />
      {/* your routes */}
    </>
  );
}

In Nuxt, add the script to the app head. In a plain Vue (Vite) app, paste the tag into index.html.

nuxt.config.ts

export default defineNuxtConfig({
  app: {
    head: {
      script: [
        {
          src: "https://cdn.tolt.io/v2/tolt.js",
          async: true,
          "data-tolt": "YOUR_PUBLIC_KEY",
        },
      ],
    },
  },
});

Paste the script tag into your site-wide head code.

Platform	Where to paste
Webflow	Site settings → Custom code → Head code
Framer	Site settings → General → Custom code (end of `<head>`)
WordPress	A header-scripts plugin, or your theme’s `header.php` before `</head>`

Publish the site after saving. Custom code usually only runs on the published domain, not in the editor preview.

Check that it works

Open a partner link

Visit your site through any partner’s link, for example https://acme.com/?ref=sam.

Read the tracking data

Open the browser console and run:

await tolt.ready();
// {
//   click_id: "8537db0b-efeb-416c-ae68-07e6e2863a33",
//   partner_id: "part_8fKq2LmZx7RtYw3nVbHc5dPj",
//   program_id: "prg_YxLm9KfZ3nPb8HcV4dQ7wRt2",
//   cookie_duration: 30,
//   customer_id: null,
// }

null means this visit has no referral. tolt.getTracking() returns the same data without waiting.

Find the cookie

In DevTools → Application → Cookies you should see tolt_referral and tolt_data. The click also shows up in your dashboard.

Edge cases

Marketing site and app on different subdomains

tolt.js writes its cookies on your root domain (.acme.com) automatically, so a click on acme.com is still there when the visitor signs up on app.acme.com. Install the script on both. To force a specific domain, add data-cookie-domain=".acme.com" to the tag. Cookies can’t be shared across different root domains.

Single-page apps that strip ?ref from the URL

tolt.js reads the URL once, when it loads. If your router rewrites the URL first, the referral is lost. Load the script in the initial HTML (or as early as possible) so it runs before any client-side redirect.

Which URL parameters are tracked

tolt.js looks for the first of these in the query string (or hash): tolt, ref, aff, via, lmref, fpr, tap_s, afmc, f2f-ref, join, ali. Your program’s links use the parameter you chose in program settings.

Get started

Track conversions

Integrations

Concepts

Run your program

Guides

Add it to your framework

Check that it works

Edge cases

​Add it to your framework

​Check that it works

​Edge cases

Add it to your framework

Check that it works

Edge cases