> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tolt.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Install tolt.js

> One script tag records every partner click and remembers it in a first-party cookie.

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

```html theme={"system"}
<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.

&#x20;acme.com/?ref=sam

&#x20;tolt.js
click
&#x20;Tolt

In the browser

**cookies**.acme.comtolt\_referral8537db0b…tolt\_data\{…}expires30d

In Tolt

**click**8537db0b…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**

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

```html index.html theme={"system"}
<head>
  <script
    async
    src="https://cdn.tolt.io/v2/tolt.js"
    data-tolt="YOUR_PUBLIC_KEY"
  ></script>
</head>
```

**Next.js**

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

```tsx app/layout.tsx theme={"system"}
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`](/sdks/tracking) and render `<ToltTracking publicKey="YOUR_PUBLIC_KEY" />` in a client component instead.

**React**

For Vite or Create React App, install [`@tolt/tracking`](/sdks/tracking) and render the component once near the root.

```bash theme={"system"}
npm install @tolt/tracking
```

```tsx src/App.tsx theme={"system"}
import { ToltTracking } from "@tolt/tracking/react";

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

**Vue / Nuxt**

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

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

**No-code**

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

**1. Open a partner link**

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

**2. Read the tracking data**

Open the browser console and run:

```js theme={"system"}
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.

**3. 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.