# Installation
Clicktag is one async `latest.js` tag, about 4 KB compressed, with no npm package, for plain HTML, React with Vite or the Next.js App Router. It tracks single-page app navigation through `pushState` and `popstate` and takes its settings from `data-` attributes or `window.tt_settings`.
## Script placement
Load `latest.js` once in your root document. Do not mount duplicate script tags across child views. For a new site, copy the tag from Site settings > Installation, step 1: keep both `data-hostname` and `data-verify`. In the examples below, replace `YOUR_SITE_VERIFY_TOKEN` with that site’s `verify_token`, not your account access token.
### Plain HTML
Place the script in your shared template header or footer:
```html
My App
```
### React and Vite
Add the script directly inside `index.html` at the project root:
```html
Vite App
```
### Next.js (App Router)
Place a raw `
```
## Manual pageview tracking
If you prefer manual control over pageviews, disable automatic collection with `data-auto-collect="false"`. When disabled, trigger pageviews using `window.tt_pageview(path, metadata)`.
Calls recording an identical consecutive path are automatically suppressed. Verify that the script has loaded before calling `window.tt_pageview`:
```html
```
## Script configuration options
Configure behavior by setting data attributes on the `
```
The default globals are `tt_settings`, `tt_event`, `tt_metadata`, and manual-mode `tt_pageview`; the default loaded guard is `tt_tt_loaded`. An occupied event function without a preload queue is not overwritten; the script warns while pageviews continue. For most settings, `window.tt_settings` overrides the equivalent attribute; `data-auto-collect="false"`, `data-retention="false"` and `data-strict-utm="true"` still take effect. Avoid conflicting configurations and set them before `latest.js` executes. Clicktag does not host the optional [automatic-events companion scripts](/docs/events#automated-event-scripts).
## Privacy and Do Not Track
By default, `navigator.doNotTrack === "1"` stops normal collection after the script loads: no pageviews or events are sent, and the script does not install `tt_event` or `tt_pageview`. Separately, the collector drops pageviews, events and engagement updates whose request carries a `DNT: 1` or `X-Do-Not-Track: 1` header. `data-collect-dnt` only skips the check in the script, which never sends the collector's `collect-dnt` override, so those requests are still dropped. Keep this default to respect the visitor's setting.
## Content Security Policy (CSP)
Clicktag sends pageviews, events and the `/r` returning-visitor request as `new Image()` requests. `/append` engagement updates use `navigator.sendBeacon` when the visitor leaves the page; after a single-page navigation, or when `sendBeacon` is unavailable or refuses the data, they go as an image request to `simple.gif` instead. Tags served from `clicktag.io` or `clicktag.app` send beacons to `clicktag.io`. Existing tags served from `totallytics.com` or `totallytics.app` keep sending to `totallytics.com`.
If your site serves a Content Security Policy header, merge our hosts into your existing directives. Do not overwrite your wider security rules:
```text
script-src 'self' https://clicktag.io;
img-src 'self' https://clicktag.io;
connect-src 'self' https://clicktag.io;
```
Self-hosted copies of `latest.js` downloaded before 25 September 2026 still beacon to `https://analytics.bitgate.dev`; keep that host in `img-src` and `connect-src` as well, or download the current script.
The `script-src` entry must match the host in your snippet. New installations use `https://clicktag.io`; a tag loaded from `https://clicktag.app` needs that host in `script-src` instead. Legacy Totallytics tags still need their existing script host in `script-src` and `https://totallytics.com` in `img-src` and `connect-src`. A self-hosted copy of `latest.js` needs only `'self'`, but automatic verification and the setup check only recognize tags loaded from Clicktag hosts, so verify such a site by [DNS or file](/docs/sites#verify-ownership). If your policy defines `script-src-elem`, allow the tag host there as well. Inline settings, event queues, and `onload` examples also need your existing inline-code policy; prefer external app code or your framework's nonce/hash mechanism rather than adding `unsafe-inline`.
Site settings > Installation, step 3, **Run setup check** fetches your homepage and checks its `Content-Security-Policy` response header against the detected tag host and beacon endpoints. Nonce/hash policies need a browser check. It does not read `` or report-only policies, and it cannot see tags injected by client-side code; with no tag in the served HTML, it checks the script host `clicktag.io`.
## Testing on localhost
By default, `latest.js` extracts `location.host` when `data-hostname` is omitted. On local development environments, this results in values like `localhost:3000`.
The script has no localhost exclusion and also sends from local development. A local hostname such as `localhost:3000` cannot be registered, so the collector ignores it; an explicit production `data-hostname` records local test traffic against your live site. To verify integrations, test on an explicit staging or production domain that matches a registered hostname. Do not direct localhost test traffic to your production hostname.
Next, explore [Custom Events](/docs/events) or review the [Troubleshooting Guide](/docs/troubleshooting).