---
id: "brand/tracking/click-tracking"
type: "doc"
url: "https://affitor.com/docs/brand/tracking/click-tracking"
kind: "guide"
updated: "2026-11-07"
---
# Click Tracking

> Install the Affitor tracker with the npm SDK or a script tag to record affiliate visits, then check clicks and cookies before tracking signups and sales.

Click tracking is the first step in every Affitor integration. It detects affiliate visits, creates the click/customer relationship, and stores the browser identifier used by later signup and sale attribution.

---

## What It Does

When someone lands on your site through an affiliate link such as:

```text
https://yoursite.com?via=PARTNER123
https://yoursite.com?aff=PARTNER123
```

the tracker:

1. detects the `?via=` or `?aff=` parameter (which one your links use is the **Partner link parameter** on **Tracking**; the tracker reads both, and `aff` wins when a URL has both)
2. sends click data to Affitor
3. creates or updates the tracked customer relationship
4. stores `affitor_click_id` in a first-party cookie
5. makes later signup and sale attribution possible

That cookie value is later reused as:
- `click_id` in API payloads
- `affitor_click_id` in Stripe metadata

---

## Choose Your Installation Method

| Method | Best for | Benefits |
|--------|----------|----------|
| **npm SDK** | React, Next.js, JS/TS apps | Promise-based loading, TypeScript support |
| **Script tag** | Static HTML, CMS sites, no-build installs | Copy-paste setup, no build step required |

---

## npm SDK

Install the tracker package:

```bash
npm install @affitor/sdk
```

### React / Next.js

:::warning

**Next.js 13+ App Router:** `layout.tsx` is a Server Component by default. `@affitor/sdk` uses browser APIs and cannot run in a Server Component. Wrap your app in `AffitorProvider` from a client component and render it once in your layout.

:::

```tsx
// app/providers.tsx — client component
'use client';
import { AffitorProvider } from '@affitor/sdk/react';

export function Providers({ children }: { children: React.ReactNode }) {
  return <AffitorProvider programId="YOUR_PROGRAM_ID">{children}</AffitorProvider>;
}
// wrap {children} with <Providers> once in app/layout.tsx
```

Child components read the loaded tracker with `useAffitor()` from `@affitor/sdk/react`. It returns `null` while the tracker is loading and during server rendering.

### Any JS / TS app

```ts
import { loadAffitor } from '@affitor/sdk';

const affitor = await loadAffitor('YOUR_PROGRAM_ID');
```

`loadAffitor()` loads the tracker script once and resolves to the tracker instance (the same object as `window.affitor`). It resolves to `null` during server rendering.

### Astro

Astro isn't React, so the React `<AffitorProvider>` shown above doesn't apply. Load the tracker from a client `<script>` in your shared layout:

```astro
---
// src/layouts/Layout.astro
---
<head>
  <!-- ... -->
  <script>
    import { loadAffitor } from '@affitor/sdk';
    loadAffitor('YOUR_PROGRAM_ID');
  </script>
</head>
```

Prefer a no-build install? Drop the [Script Tag](#script-tag) into the same `<head>` with Astro's `is:inline` directive, so Astro leaves the external script untouched:

```astro
<script
  is:inline
  src="https://api.affitor.com/js/affitor-tracker.js"
  data-affitor-program-id="YOUR_PROGRAM_ID">
</script>
```

Track referred signups the same way — call `signup()` from a client `<script>` after the user authenticates. See [Lead Tracking (Signup)](/docs/brand/tracking/lead-tracking-signup/).

### Useful options

| Option | Type | Description |
|--------|------|-------------|
| `programId` | `string \| number` | required program ID |
| `debug` | `boolean` | For testing only: console logs, and `signup()` sends a test event instead of a lead (no real lead is recorded). Turn it off before production |
| `env` | `'production' \| 'uat' \| 'local'` | environment preset |
| `scriptUrl` | `string` | custom script URL override |

---

## Script Tag

```html
<script
  src="https://api.affitor.com/js/affitor-tracker.js"
  data-affitor-program-id="YOUR_PROGRAM_ID"
  data-affitor-debug="false">
</script>
```

### Required attributes

| Attribute | Required | Description |
|-----------|----------|-------------|
| `src` | Yes | tracker script URL |
| `data-affitor-program-id` | Yes | your Affitor program ID |
| `data-affitor-debug` | No | `true` only while testing: `signup()` then sends a test event instead of a lead. Remove it before production |

---

## How Affiliate Links Work

The tracker reads `aff` first, then `via` when `aff` is absent. Use the saved referral URL so a page's unrelated campaign parameters are not mistaken for the partner code:

```text
https://yoursite.com?aff=PARTNER123
https://yoursite.com/pricing?via=PARTNER123
```

When a valid partner code is present and the tracker runs, it records the click and creates the customer relationship used by signup and sale attribution.

### Track every allowed destination

If partners can create page links, install the tracker on each destination allowed in [Partner links](/docs/brand/partner-links), including any separately configured subdomain or port. Allowing a domain and acknowledging ownership does not install or verify its tracker.

A recent-click status only describes observed activity in a recent sample. It does not prove every page is tracked or that signup and sale tracking work. A short homepage redirect such as `/r/CODE` also does not enable short page links by itself; Affitor does not yet verify a handler for short page links, so page links use the query format.

---

## Verifying Installation

### Enable debug mode

**SDK:**

```ts
import { loadAffitor } from '@affitor/sdk';
const affitor = await loadAffitor('YOUR_PROGRAM_ID', { debug: true });
```

With React, pass `debug` to the provider: `<AffitorProvider programId="YOUR_PROGRAM_ID" debug>`.

**Script tag:**

```html
<script
  src="https://api.affitor.com/js/affitor-tracker.js"
  data-affitor-program-id="YOUR_PROGRAM_ID"
  data-affitor-debug="true">
</script>
```

### What to verify

Open your browser console and network tab, then confirm:
- The tracker loads without errors
- Cookies can be written and read
- Affitor debug messages appear in the console
- Click or test-click activity appears in the dashboard or test-event tooling

:::caution

Debug mode helps with test verification, but a real affiliate landing flow using a real `?via=` or `?aff=` value still creates real attribution data. Do not mix synthetic tests and production affiliate links.

:::

---

## Common Issues

### No click data appears

Check:
- The tracker script loaded successfully
- The page was visited through a saved link with a valid `?aff=` or `?via=` parameter
- Your program ID is correct
- CSP rules or browser extensions are not blocking the script

### Cookies are missing

Check:
- The site is served over HTTPS in production
- Browser privacy tools are not blocking cookies
- The affiliate landing page executed the tracker before the visitor continued

### Later signup/sale tracking fails

This usually means one of the following:
- Click tracking did not run before the signup or sale event
- The browser session lost `affitor_click_id` between landing and conversion
- Signup/payment identifiers do not consistently match your internal customer ID

---

## Next Steps

Once click tracking is working, continue with:

- [Lead Tracking](/docs/brand/tracking/lead-tracking-signup/)
- [Payment Tracking](/docs/brand/tracking/payment-tracking-stripe/)
- [Testing Integration](/docs/brand/tracking/testing-integration/)
