# Tracker configuration (https://talivia.com/docs/tracker-configuration)



The tracker reads configuration from `data-*` attributes on the script tag. For a normal Talivia Cloud installation, copy the complete snippet from **Settings -> Tracking** and leave its generated attributes unchanged.

```html
<script
  defer
  src="https://talivia.com/script.js"
  data-website-id="YOUR_WEBSITE_ID"
  data-domain="example.com"
  data-auto-track="true"
></script>
```

Only `data-website-id` is required for tracking one hostname. Talivia Cloud normally generates `data-domain` too, which is safe to keep and allows the same anonymous identity to continue across subdomains.

## Domain attributes [#domain-attributes]

These similarly named attributes solve different problems:

| Attribute                   | Use it for                                                                                                                     |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `data-domain`               | Set the cookie scope. Use one root such as `example.com` when the same visitor moves between `example.com` and its subdomains. |
| `data-domains`              | Restrict the hostnames where this script is allowed to collect. It does not share identity.                                    |
| `data-cross-domain-domains` | Continue a journey between unrelated roots such as `example.com` and `example.net` with a signed linker.                       |

For a website that only runs on one hostname, no manual domain configuration is required. For subdomains, follow [Subdomain tracking](https://talivia.com/docs/subdomain-tracking). For unrelated roots, use [Cross-domain tracking](https://talivia.com/docs/cross-domain-tracking).

## Available attributes [#available-attributes]

| Attribute                   | Description                                                                                                                               |
| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `data-website-id`           | Required website id.                                                                                                                      |
| `data-host-url`             | Override the collection endpoint origin for self-hosting or a custom reverse proxy. Do not set it on a normal Talivia Cloud installation. |
| `data-domain`               | Optional cookie domain shared by the website and its subdomains. Talivia Cloud generates it from the configured website domain.           |
| `data-auto-track`           | Set to `false` to disable the first automatic page view.                                                                                  |
| `data-domains`              | Optional comma-separated hostname allowlist. Subdomains do not need to be listed for shared identity.                                     |
| `data-cross-domain-domains` | Comma-separated root domains allowed to receive a signed Talivia linker.                                                                  |
| `data-do-not-track`         | Set to `true` to respect browser Do Not Track.                                                                                            |
| `data-exclude-search`       | Set to `true` to remove query strings before sending URLs.                                                                                |
| `data-exclude-hash`         | Set to `true` to remove hash fragments before sending URLs.                                                                               |
| `data-tag`                  | Attach a tag to every event from this script.                                                                                             |
| `data-before-send`          | Name of a global function that can edit or cancel payloads.                                                                               |
| `data-fetch-credentials`    | Fetch credentials mode. Defaults to `omit`.                                                                                               |
| `data-performance`          | Set to `true` to collect Web Vitals.                                                                                                      |

## beforeSend [#beforesend]

```html
<script>
  window.taliviaBeforeSend = (type, payload) => {
    if (payload.url?.includes('/internal-preview')) return null;

    return payload;
  };
</script>

<script
  defer
  src="https://talivia.com/script.js"
  data-website-id="YOUR_WEBSITE_ID"
  data-before-send="taliviaBeforeSend"
></script>
```

Return `null` or `undefined` to cancel the event.

## Domain allowlist [#domain-allowlist]

This is an optional restriction, not a requirement for subdomain tracking.

```html
<script
  defer
  src="https://talivia.com/script.js"
  data-website-id="YOUR_WEBSITE_ID"
  data-domains="example.com"
></script>
```

One root entry covers that domain and its subdomains. This is useful when the same layout can render on staging, preview, and production domains.

## Collection host [#collection-host]

The script automatically sends data to Talivia Cloud. `data-host-url` exists for self-hosted installations and custom reverse proxies where the browser must send collection requests to another origin. It is not an additional URL for your tracked website and should be omitted from normal Cloud snippets.

## Identity storage [#identity-storage]

Talivia stores its anonymous visitor and rolling session identifiers in first-party cookies.

## Visitor and session lifetime [#visitor-and-session-lifetime]

* The anonymous visitor cookie lasts for 365 days.
* The session cookie lasts for 30 minutes and refreshes whenever the tracker sends activity.
* Closing a tab does not split an active session. All tabs and configured subdomains reuse the same rolling session.

When multiple subdomains must share identity, use the root registrable domain for `data-domain`, such as `example.com`, not `app.example.com`. Copy the generated snippet from **Settings -> Tracking** and review [Subdomain tracking](https://talivia.com/docs/subdomain-tracking) before changing the value manually.

## Sensitive query parameters [#sensitive-query-parameters]

Talivia removes OAuth credentials, signed cross-domain tokens, and checkout session ids from stored URL queries. Payment return detection still runs before sanitization, so Stripe and other checkout attribution continues to work without displaying secrets in analytics.