@tolt/tracking

@tolt/tracking injects tolt.js for you and gives you typed access to the referral and the signup call. Same script, same cookies, no <script> tag to manage.

tolt.js useTolt()signup(id) Tolt

Returned by useTolt()

hookReact

dataToltData | null

readytrue

signup(identifier) => …

Inside data

ToltDataref=sam

click_id

partner_id

program_id

customer_id

Install

npm install @tolt/tracking

You need your public key from Dashboard → Settings → Integrations. React is an optional peer dependency (17+).

Use it

React
Next.js
Vanilla

Render ToltTracking once near the root. It renders nothing.

app.tsx

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

export function App() {
  return (
    <>
      <ToltTracking publicKey="YOUR_PUBLIC_KEY" />
      <Routes />
    </>
  );
}

Then bind the signup once your own signup succeeds:

track-signup.ts

import { init, signup } from "@tolt/tracking";

// init() resolves once tolt.js has loaded (a no-op after the
// first call). signup() then waits for the recorded click and
// resolves without a customer_id when the visitor wasn't referred.
export async function trackSignup(userId: string) {
  await init({ publicKey: "YOUR_PUBLIC_KEY" });
  const result = await signup(userId);
  if (result?.customer_id) {
    // store result.customer_id (cus_...) on your user
  }
}

If the page navigates away right after signup, bind on the next page instead, or from your server with POST /v2/customers.

The components use hooks, so wrap them in a client component and render it from your root layout.

components/tolt.tsx

"use client";

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

app/layout.tsx

import { ToltTracking } from "@/components/tolt";

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body>
        <ToltTracking
          publicKey={process.env.NEXT_PUBLIC_TOLT_PUBLIC_KEY!}
        />
        {children}
      </body>
    </html>
  );
}

Then call trackSignup() from a client component, as in the React tab.

import { init, signup } from "@tolt/tracking";

await init({ publicKey: "YOUR_PUBLIC_KEY" });

// After your own signup succeeds. Resolves without a
// customer_id when the visitor wasn't referred.
const result = await signup("jane@example.com");
// cus_...
if (result?.customer_id) console.log(result.customer_id);

API

Vanilla (`@tolt/tracking`)

Function	Returns
`init({ publicKey, scriptUrl? })`	`Promise<void>`	Injects the script once and resolves when it has loaded. The click may still be in flight. A no-op on the server.
`getData()`	`ToltData \| null`	The current referral, or `null` if this visit wasn’t referred or the click isn’t recorded yet.
`isReferred()`	`boolean`	Whether a referral is recorded. Can be `false` for a moment on the landing page.
`signup(identifier)`	`Promise<ToltSignupResult \| undefined>`	Waits for the click, then binds the visitor as a customer. Check `result?.customer_id`: it’s missing when the visitor wasn’t referred, on a repeat signup, or on a network error. Rejects if the script hasn’t loaded yet.

scriptUrl defaults to https://cdn.tolt.io/v2/tolt.js. ToltData has the fields described on the tolt.js page.

React (`@tolt/tracking/react`)

Export
`<ToltTracking publicKey scriptUrl? />`	Loads the script on mount and renders nothing. Load errors are logged to the console.
`useTolt()`	Returns `{ data, ready, signup }`. `data` is the current `ToltData` or `null`, `ready` turns `true` once tolt.js has loaded, and `signup(identifier)` binds the customer and refreshes `data`.

Unlike window.tolt.signup(), the package’s signup() rejects when tolt.js isn’t loaded yet. Gate on ready from useTolt(), or await init() first.

Overview

Server SDKs

Browser

Partner experiences

Tooling and AI

Install

Use it

API

Vanilla (`@tolt/tracking`)

React (`@tolt/tracking/react`)

​Install

​Use it

​API

​Vanilla (@tolt/tracking)

​React (@tolt/tracking/react)

Install

Use it

API

Vanilla (`@tolt/tracking`)

React (`@tolt/tracking/react`)