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

# Tracking ID

> What is ta_tid, how it is generated, and how to retrieve it in your application

The **Tracking ID** (`ta_tid`) is the core identifier that links a click on a Taapit deeplink to a future conversion (lead or sale).

## Prerequisites

For conversion tracking to work, you only need two things:

<Steps>
  <Step title="Create a Taapit deeplink">
    In your Taapit dashboard, create a deeplink pointing to your website or landing page (e.g. `taap.it/my-campaign` → `https://yoursite.com/landing`).

    Make sure **Conversion Tracking** is enabled on the link.
  </Step>

  <Step title="Install the Taapit SDK on your site">
    Add either the **script tag** or the **NPM package** to your website or app. This is what reads the `ta_tid` from the URL and stores it in a cookie automatically.

    **Option A — Script tag** (simplest, no build step):

    ```html theme={null}
    <script src="https://taap.it/api/sdk" data-publishable-key="pk_..."></script>
    ```

    **Option B — NPM package** (React / Next.js / Vue...):

    ```bash theme={null}
    npm install taapit-sdk
    ```

    That's it. Once the SDK is on your site and the user arrives via a Taapit link, the `ta_tid` is captured and persisted automatically — no extra code needed for that part.
  </Step>
</Steps>

<Info>
  The `ta_tid` is **only generated when a user clicks a Taapit deeplink**. If a user navigates directly to your site, there is no tracking ID and no conversion will be attributed.
</Info>

***

## What is it?

When a user clicks a Taapit deeplink (e.g. `taap.it/abc`), our system generates a unique `ta_tid` and appends it to the destination URL:

```
https://yoursite.com/landing?ta_tid=rLnWe1uz9t282v7g
```

This ID is then used to attribute any subsequent lead or sale event back to the original click — along with all its metadata: UTM parameters, geolocation, device type, link ID, and workspace.

## How is it generated?

The tracking ID is a **24-character hexadecimal string** generated server-side using Node.js cryptography:

```ts theme={null}
const trackingId = crypto.randomBytes(12).toString("hex");
// Example: "rLnWe1uz9t282v7g4a3b1c2d"
```

It contains **no personal information** — it is purely random and cannot be reverse-engineered.

## How is it persisted?

Once the user lands on your site, the Taapit SDK automatically:

1. Reads the `ta_tid` from the URL query parameter
2. Stores it in a **first-party cookie** on your domain

```
Cookie name:   ta_tid
Duration:      365 days
Scope:         Root domain (e.g. .yoursite.com)
```

Because it is a first-party cookie set on your own domain, it is **not blocked by browsers** or privacy extensions.

## How to retrieve it

### From the Taapit SDK (recommended)

If you use the Taapit script or NPM package, the SDK handles everything automatically. You can access the tracking ID via:

```js theme={null}
// Vanilla JS / Script tag
const trackingId = window.taapit?.getTrackingId();
```

```ts theme={null}
// NPM package — browser
import { getTrackingId } from "taapit-sdk/browser";

const trackingId = getTrackingId();
```

### From the cookie manually

If you are not using the SDK, you can read the cookie directly:

```js theme={null}
function getTrackingId() {
  const match = document.cookie.match(/(?:^|;\s*)ta_tid=([^;]+)/);
  return match ? match[1] : null;
}
```

### From the URL parameter (on page load)

```js theme={null}
const params = new URLSearchParams(window.location.search);
const trackingId = params.get("ta_tid");
```

<Info>
  If both the URL parameter and the cookie are present, the URL parameter takes
  precedence and overwrites the cookie — ensuring the most recent click is always
  attributed.
</Info>

## Passing it to your backend

Once retrieved client-side, pass the `ta_tid` to your backend when a conversion occurs (e.g. on form submit or checkout):

```ts theme={null}
// Example: send ta_tid alongside a signup form
await fetch("/api/signup", {
  method: "POST",
  body: JSON.stringify({
    email: userEmail,
    trackingId: getTrackingId(), // from SDK or cookie
  }),
});
```

Your backend then forwards it to Taapit when calling `/api/events/lead` or `/api/events/sale`.

## Properties

| Property            | Value                                    |
| ------------------- | ---------------------------------------- |
| **Parameter name**  | `ta_tid`                                 |
| **Cookie name**     | `ta_tid`                                 |
| **Format**          | Hexadecimal string, 24 characters        |
| **Generated by**    | `crypto.randomBytes(12).toString("hex")` |
| **Cookie duration** | 365 days                                 |
| **Contains PII**    | No                                       |
| **First-party**     | Yes — set on your domain                 |

## Next Steps

<CardGroup cols={2}>
  <Card title="Track Leads" icon="user-plus" href="/conversions/manual/client-side">
    Use the ta\_tid to track lead conversions.
  </Card>

  <Card title="Track Sales" icon="credit-card" href="/conversions/manual/server-side">
    Use the ta\_tid to track sale conversions server-side.
  </Card>
</CardGroup>