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

# Configure the tinyanalytics Tracking Script

> Control what the tinyanalytics script tracks with data-* attributes: SPA routing, auto-capture, Web Vitals, path masking, query strings, and per-page tags.

You configure the tinyanalytics tracking script with `data-*` attributes on the script tag. Every option has a sensible default, so the basic snippet works on its own — you only add attributes to change behavior. Configuration is set in the HTML itself, so to change an option you update the snippet and re-deploy.

```html theme={null}
<script defer src="https://dash.tinyanalytics.io/script.js"
  data-site-id="123"
  data-web-vitals
  data-mask-paths='["/orders/*"]'></script>
```

<Tip>
  You don't have to write these by hand. In **Settings → Tracking**, the snippet builder lets you toggle options and copies the updated tag for you. Only non-default options are added, so your snippet stays as short as possible.
</Tip>

## Which `data-*` attributes can I set?

Set any of the attributes below on the tracking script tag. Each one has a default, so you only add the ones whose behavior you want to change.

<Info>
  **Boolean rule:** if an attribute is absent, its default applies. The literal value `"false"` turns it off. Any other present value turns it on.
</Info>

| Attribute               | Default            | What it does                                                                                                           |
| ----------------------- | ------------------ | ---------------------------------------------------------------------------------------------------------------------- |
| `data-site-id`          | *(required)*       | Your site's numeric ID. Without a valid ID, the script does nothing.                                                   |
| `data-api-host`         | derived from `src` | Where events are sent. Defaults to the script's own origin.                                                            |
| `data-namespace`        | `tinyanalytics`    | The global variable name (`window.tinyanalytics`) and the opt-out key prefix.                                          |
| `data-auto-pageview`    | `true`             | Send a pageview automatically when the page loads.                                                                     |
| `data-track-spa`        | `true`             | Track client-side route changes in single-page apps.                                                                   |
| `data-debounce`         | `500`              | Milliseconds to wait before recording an SPA pageview, so a burst of route changes counts once. `0` fires immediately. |
| `data-track-outbound`   | `true`             | Record clicks on links to other domains.                                                                               |
| `data-track-downloads`  | `true`             | Record clicks on links to downloadable files.                                                                          |
| `data-track-clicks`     | `true`             | Record button clicks.                                                                                                  |
| `data-track-copy`       | `true`             | Record when visitors copy text.                                                                                        |
| `data-track-forms`      | `true`             | Record form submissions and input changes (shape only — never values).                                                 |
| `data-track-query`      | `true`             | Include the URL query string on events.                                                                                |
| `data-track-errors`     | `false`            | Capture JavaScript errors as `error` events.                                                                           |
| `data-web-vitals`       | `false`            | Collect Core Web Vitals and send one performance event per page load.                                                  |
| `data-track-engagement` | `true`             | Collect scroll depth and engaged time per page visit.                                                                  |
| `data-skip-paths`       | `[]`               | JSON array of path patterns to **not** track.                                                                          |
| `data-mask-paths`       | `[]`               | JSON array of path patterns to report as the pattern instead of the real path.                                         |
| `data-tag`              | *(none)*           | A label stamped on every event sent from this page.                                                                    |

## Track single-page apps

SPA route tracking is **on by default** (`data-track-spa`). When your app changes routes on the client — as React, Vue, Svelte, and similar frameworks do — tinyanalytics records each route change as a new pageview. You don't need to configure anything for most single-page apps. Set `data-track-spa="false"` only if you want to record pageviews manually instead.

### Why one navigation counts as one pageview

Many SPA routers fire **several history events for a single navigation** (a `pushState` followed by a `replaceState`, plus one on hydration). Left unguarded, that inflates pageviews and collapses bounce rate. tinyanalytics prevents it two ways:

* **Debounce (`data-debounce`, default 500 ms).** A burst of route changes within the window collapses into **one** pageview, sent after the burst so it carries the final URL. Lower it for snappier per-route tracking, or set `data-debounce="0"` to fire on every route change immediately.
* **Same-URL skip.** A route change that leaves the URL unchanged records nothing, so a hydration re-render never becomes a phantom second pageview.

A debounced pageview can be missed if the tab closes inside the window; the initial page-load pageview is never debounced.

## Turn auto-capture on or off

tinyanalytics captures outbound links, downloads, button clicks, copies, form submissions, and engagement by default. To disable one, set its attribute to `"false"`:

```html theme={null}
<script defer src="https://dash.tinyanalytics.io/script.js"
  data-site-id="123"
  data-track-copy="false"
  data-track-forms="false"></script>
```

Form capture records only the shape of a submission — the form's name, action, and field count. It never captures what a visitor typed, and it skips hidden, password, disabled, and read-only fields.

## Collect Core Web Vitals

Web Vitals collection is off by default because it loads a small extra chunk of code only when needed. Turn it on with `data-web-vitals`:

```html theme={null}
<script defer src="https://dash.tinyanalytics.io/script.js"
  data-site-id="123"
  data-web-vitals></script>
```

tinyanalytics then sends one performance event per page load with LCP, CLS, INP, FCP, and TTFB, which power the **Performance** report.

## Capture JavaScript errors

Error capture is also off by default. Turn it on with `data-track-errors`:

```html theme={null}
<script defer src="https://dash.tinyanalytics.io/script.js"
  data-site-id="123"
  data-track-errors></script>
```

tinyanalytics then records uncaught exceptions and unhandled promise rejections as `error` events, grouped by message in the **Errors** report. Benign `ResizeObserver` warnings and cross-origin third-party script errors are filtered out automatically. See [error tracking](/docs/javascript-error-tracking) for the report and the manual `trackError()` call.

## Hide sensitive paths with skip and mask

If your URLs contain personal or sensitive data — an order number, a token, an email — use path patterns to keep it out of your reports:

* **Skip** drops the event entirely. Use `data-skip-paths`.
* **Mask** records the pattern instead of the real path, so the sensitive part never leaves the browser. Use `data-mask-paths`.

Patterns use this syntax:

* `*` matches one path segment (`[^/]+`).
* `**` matches any depth.
* `re:<expression>` matches a raw regular expression.

```html theme={null}
<script defer src="https://dash.tinyanalytics.io/script.js"
  data-site-id="123"
  data-mask-paths='["/orders/*", "/reset/**"]'></script>
```

With this, a visit to `/orders/abc123` is recorded as `/orders/*`. Masking happens in the browser, so the real path is never sent. A malformed pattern is ignored rather than breaking tracking.

## Tag every event on a page

Use `data-tag` to stamp a label on every event sent from a page — useful for grouping a campaign, an A/B variant, or a section of your site. The label is truncated to 256 characters.

```html theme={null}
<script defer src="https://dash.tinyanalytics.io/script.js"
  data-site-id="123"
  data-tag="black-friday"></script>
```

## Opt out of tracking

To exclude yourself (or anyone) from tracking on a device, set a `disable-<namespace>` key in the browser's `localStorage`. With the default namespace, that's:

```js theme={null}
localStorage.setItem('disable-tinyanalytics', 'true')
```

While that key is present, the script installs a no-op and sends nothing from that browser. This is the recommended way to keep your own visits out of your stats.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="How do I turn off a tinyanalytics tracking option?">
    Set the attribute to the literal value `"false"` on the tracking script tag — for example, `data-track-copy="false"`. If an attribute is absent its default applies, and any other present value turns it on.
  </Accordion>

  <Accordion title="Do I have to redeploy my site to change a tracking option?">
    Yes. tinyanalytics configuration lives in the `data-*` attributes on the script tag in your HTML, so changing an option means updating the tag and re-deploying your site. Use the snippet builder in **Settings → Tracking** to generate the updated tag.
  </Accordion>

  <Accordion title="How do I keep my own visits out of tinyanalytics?">
    Set a `disable-<namespace>` key in that browser's `localStorage` — with the default namespace, run `localStorage.setItem('disable-tinyanalytics', 'true')`. While the key is present, the tracking script installs a no-op and sends nothing from that browser.
  </Accordion>

  <Accordion title="What happens if a path pattern is malformed?">
    A malformed `data-skip-paths` or `data-mask-paths` pattern is ignored rather than breaking tracking. Valid patterns use `*` for one path segment, `**` for any depth, and `re:<expression>` for a raw regular expression.
  </Accordion>

  <Accordion title="Why is my single-page app double-counting pageviews?">
    Many SPA routers fire more than one history event per navigation, and each could become a pageview. tinyanalytics collapses a burst of route changes into one pageview using a **500 ms debounce** (`data-debounce`) and skips any route change that doesn't alter the URL. If a tool navigates by `replaceState` only and you want a pageview per change, set `data-debounce="0"`.
  </Accordion>
</AccordionGroup>

## Related

<Columns cols={2}>
  <Card title="Install the tracking script" icon="code" href="/docs/install-tinyanalytics-tracking-script">
    Get the snippet and add it to your site.
  </Card>

  <Card title="Track custom events" icon="hand-pointer" href="/docs/custom-event-tracking">
    Send named events with the JavaScript API.
  </Card>

  <Card title="Verify your setup" icon="circle-check" href="/docs/verify-tinyanalytics-installation">
    Confirm your configuration is working.
  </Card>

  <Card title="How tinyanalytics works" icon="diagram-project" href="/docs/how-tinyanalytics-works">
    What the script sends and what stays in the browser.
  </Card>
</Columns>


## Related topics

- [Install the tinyanalytics Tracking Script](/docs/install-tinyanalytics-tracking-script.md)
- [JavaScript Error Tracking](/docs/javascript-error-tracking.md)
- [Verify Your tinyanalytics Installation](/docs/verify-tinyanalytics-installation.md)