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

# First-party analytics

> Serve Sapt analytics from your own domain — more accurate data, harder to block, and a visitor ID you can join to your CRM.

Sapt analytics runs **first-party**: the tracking script and the data it sends are served from a subdomain of *your* site instead of a shared third-party domain. You point one DNS record at Sapt, drop in one script tag, and your pageviews and events start flowing — measured more accurately, owned by you.

Once events are flowing, the rest of this section covers what you do with them: resolve [visitors to real people](/docs/mintlify/analytics/visitors), read [first-touch attribution](/docs/mintlify/analytics/attribution), and push [conversions back to ad platforms](/docs/mintlify/analytics/conversions) server-side.

## Why first-party

Most analytics load from a shared vendor domain. Browsers and blockers treat that as third-party, so a large share of traffic never gets counted. Serving from your own domain changes that.

| Benefit                          | What it means for you                                                                                                        |
| -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| **Harder to block**              | The script loads from your subdomain, not a known analytics host, so blocklists that target vendor domains don't match.      |
| **Survives tracking protection** | The visitor cookie is a real first-party cookie, so Safari ITP and Firefox ETP keep it far longer than a third-party one.    |
| **More accurate numbers**        | Fewer dropped requests means your traffic, sources, and conversions reflect reality.                                         |
| **You own the connection**       | Data flows over your domain. You can read the visitor ID from your own page code and join it to your CRM.                    |
| **Cookieless-friendly**          | One first-party cookie with no personal data, and no third-party tracker — so it doesn't trigger a cookie banner on its own. |

<Note>
  First-party makes analytics *harder* to block, not unblockable. DNS-level blockers and strict anti-CNAME modes can still opt out — which is the privacy-respecting outcome.
</Note>

## How it works

You add one **CNAME** record so a short subdomain of your site (for example `m.yourdomain.com`) resolves to Sapt's ingest. Sapt issues the TLS certificate for it automatically. From then on:

1. The browser loads the tracking script from your subdomain.
2. The script sends each event back to that **same subdomain** — so the whole exchange is first-party.
3. Sapt enriches each event (source, campaign, location, device) on the server and shows it in your analytics dashboard.

## Set it up

### 1. Get your tracking subdomain

In the Sapt dashboard, open **Analytics → Tracking** and enter your site's root domain (e.g. `yourdomain.com`). Sapt picks a short, neutral subdomain for you and shows the exact DNS records to add.

### 2. Add the DNS records

Add both records the dashboard shows you, at your DNS provider:

```txt theme={null}
Type:   CNAME
Name:   m.yourdomain.com        ← the subdomain Sapt assigned you
Value:  ingest.sapt.ai

Type:   TXT
Name:   (shown in the dashboard)
Value:  (shown in the dashboard)
```

The **CNAME** routes your subdomain to Sapt. The **TXT** record lets Sapt issue an SSL certificate for it. Both come straight from the setup screen — copy them exactly.

<Warning>
  Use the values shown in your dashboard. The subdomain is chosen per site, and the TXT value is one-time — don't reuse one from another site or from this page.
</Warning>

### 3. Wait for it to go live

DNS changes take anywhere from a few minutes to a few hours. The Tracking page shows the status and a **Check status** button. Once it reads **Active**, your certificate is issued and you're ready for the script.

### 4. Add the tracking script

Paste the snippet from the dashboard into your site's `<head>` (it includes your assigned host and Project ID):

```html theme={null}
<script
  src="https://m.yourdomain.com/v1/track.js"
  data-project="YOUR_PROJECT_ID"
  defer
></script>
```

That's it. The script auto-detects single-page-app route changes, so one tag covers most sites. Visit a page and you'll see it appear in your analytics dashboard within a few seconds.

## Track custom events

Once the script is loaded it exposes a small global API for events that matter to your business:

```js theme={null}
// A custom event, with optional properties
window.sapt.track('signup', { plan: 'pro' });

// Attach known traits to the current visitor
window.sapt.identify({ email: 'jane@acme.com' });

// Read the first-party visitor ID (e.g. to send to your own backend)
const visitorId = window.sapt.getVisitorId();
```

`getVisitorId()` returns the value of the first-party `_sapt_vid` cookie — a random ID with no personal data. Sending it to your backend lets you stitch anonymous visits to CRM records later.

Calling `identify()` (or a tracked form submit) is also what moves a visitor from **anonymous** to **identified** — see [Visitors & identity resolution](/docs/mintlify/analytics/visitors).

### Captured automatically

You don't need to instrument these — the script records them out of the box:

| Event                         | When it fires                                             |
| ----------------------------- | --------------------------------------------------------- |
| `pageview`                    | Page load and every SPA route change                      |
| `outbound_click`              | A click on a link to another domain                       |
| `phone_click` / `email_click` | A click on a `tel:` or `mailto:` link                     |
| `file_download`               | A click on a document or archive link (PDF, DOCX, ZIP, …) |
| `form_submit`                 | A form is submitted                                       |
| `scroll_depth`                | The visitor passes 25 / 50 / 75 / 100% of the page        |
| `engagement`                  | Active, visible time on the page                          |

## Hand it to your coding agent

Let an AI coding assistant do the install. The button below copies a ready-made prompt that points your assistant at this page and keeps the setup clean — just fill in your tracking host and Project ID from the dashboard.

```text Setup prompt theme={null}
Install Sapt first-party analytics on this website.

Add exactly this tag to the site's <head>, on every page, and change nothing else:
<script src="https://m.yourdomain.com/v1/track.js" data-project="YOUR_PROJECT_ID" defer></script>
Replace m.yourdomain.com with the tracking host shown in my Sapt dashboard and YOUR_PROJECT_ID with my Project ID.

Rules:
- Do NOT add Google Analytics, Plausible, Segment, or any other analytics library.
- Do NOT self-host, rename, or proxy the script — load it from that exact URL.
- For a single-page app, no extra setup is needed: the script tracks route changes automatically. Just ensure the tag is present on first load.
- For custom business events, call window.sapt.track('event_name', { ...props }) at the relevant moment (e.g. a successful signup or purchase).

After installing, load a page and confirm a request to /v1/event succeeds in the browser's network tab.
```

## Privacy notes

* One first-party cookie, `_sapt_vid`, holds a random ID — no names, emails, or cross-site identifiers.
* Geo and device details are derived on Sapt's server from the request; nothing extra is collected in the browser.
* Because there's no third-party tracker, the script alone doesn't require a consent banner — but follow the rules for your own region and any other tools on your site.

## Keep going

<CardGroup cols={2}>
  <Card title="Visitors & identity" href="/docs/mintlify/analytics/visitors" description="See who's on your site and turn identified visitors into CRM contacts." />

  <Card title="Attribution analytics" href="/docs/mintlify/analytics/attribution" description="First-touch acquisition, UTM breakdowns, and the conversion funnel." />

  <Card title="Server-side conversions" href="/docs/mintlify/analytics/conversions" description="Push leads and purchases back to Meta and Google server-side." />

  <Card title="Attribution MCP" href="/docs/mintlify/analytics/attribution-mcp" description="Query who's been on your site — and act on it — from an AI agent." />
</CardGroup>