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

# Configuration

> The widget is configured from two places: a small set of install-time data- attributes on the <script> tag (set once, at install), and the remote configuration

The widget is configured from two places: a small set of **install-time `data-*` attributes** on the `<script>` tag (set once, at install), and the **remote configuration** fetched from your dashboard at runtime (change any time, no code edit). Behavior toggles — tracking mode, autocapture, Web Vitals, replay — live in the remote config; the tag only carries identity and a few advanced switches.

## Install-time data attributes

Read from the tracker's own `<script>` tag. Only `data-site-id` is required; the rest are optional.

| Attribute              | Values                               | Default                | Description                                                                                                                                                  |
| ---------------------- | ------------------------------------ | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `data-site-id`         | UUID                                 | —                      | **Required.** Your site's tracking key.                                                                                                                      |
| `data-domain`          | domain (e.g. `example.com`)          | none                   | Shared cookie domain in cookie mode, so a visitor is recognized across subdomains. Applied only when it suffix-matches the hostname.                         |
| `data-manual`          | `true`                               | off                    | Disable **all** automatic pageviews. You call `clickbase.pageview()` yourself. See [Pageviews & SPAs](/widget/pageviews).                                    |
| `data-hash`            | `true`                               | off                    | Hash-based routing: track `location.hash` changes as pageviews and keep the hash in the recorded path.                                                       |
| `data-include`         | comma list of path patterns          | none                   | Only track paths matching these patterns. `*` matches within a segment, `**` across segments.                                                                |
| `data-exclude`         | comma list of path patterns          | none                   | Never track paths matching these patterns (same wildcard syntax).                                                                                            |
| `data-file-downloads`  | `true` or a comma list of extensions | inherits remote toggle | Customize the download-extension list. Only applies when file-download autocapture is enabled remotely; a comma list **replaces** the default extension set. |
| `data-tagged-events`   | `true`                               | off                    | Enable manual event tagging via `cb-event-*` CSS classes on elements and forms. See [Autocapture](/widget/autocapture).                                      |
| `data-allow-localhost` | `true`                               | off                    | Send hits from `localhost` (normally suppressed). For local testing only.                                                                                    |
| `data-api`             | URL (must include `/api`)            | build default          | Override the API base. Rarely needed.                                                                                                                        |
| `data-replay-src`      | URL                                  | CDN sibling            | Override the rrweb recorder script URL used by session replay.                                                                                               |

### Global event properties

Any attribute on the script tag prefixed with `event-` becomes a **global property** merged into every event's `props` (an explicit `props` value on a specific event wins):

```html theme={null}
<script
  defer
  data-site-id="YOUR_SITE_KEY"
  data-domain="example.com"
  event-plan="pro"
  event-env="production"
  src="https://cdn.clickbase.so/t.js"></script>
```

Here every event carries `{ plan: 'pro', env: 'production' }`.

## Remote configuration

Before its first pageview, the widget fetches your site's config from:

```http theme={null}
GET /api/tracking-config/{trackingKey}
```

`{trackingKey}` is the same value as `data-site-id`. This endpoint is public and unauthenticated (it only exposes on/off toggles, never analytics data), and it is documented in full — including its own rate-limit bucket — in [Tracking configuration](/api/tracking-config#public-tracking-config). If the fetch fails (network / 404 / bad JSON), the widget boots on safe schema defaults instead of not loading.

The response is a flat JSON object:

```json theme={null}
{
    "tracking_mode": "cookieless",
    "track_initial_pageview": true,
    "track_spa_navigation": true,
    "track_url_params": true,
    "track_outbound_links": true,
    "track_file_downloads": true,
    "track_button_clicks": false,
    "track_form_submits": false,
    "track_copy": false,
    "track_errors": false,
    "track_web_vitals": false,
    "track_session_replay": false,
    "session_replay_sample_rate": 0
}
```

### What each field controls

| Field                        | Controls                                                                                                                                |
| ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `tracking_mode`              | `cookieless` or `cookie` — see [Cookieless vs cookie](/cookieless).                                                                     |
| `track_initial_pageview`     | Whether the widget auto-fires a pageview on load. See [Pageviews & SPAs](/widget/pageviews).                                            |
| `track_spa_navigation`       | Whether SPA route changes are tracked as pageviews.                                                                                     |
| `track_url_params`           | Whether URL query parameters are recorded on pageviews.                                                                                 |
| `track_outbound_links`       | Autocapture: outbound link clicks. See [Autocapture](/widget/autocapture).                                                              |
| `track_file_downloads`       | Autocapture: file downloads.                                                                                                            |
| `track_button_clicks`        | Autocapture: button clicks.                                                                                                             |
| `track_form_submits`         | Autocapture: form submits.                                                                                                              |
| `track_copy`                 | Autocapture: copy events.                                                                                                               |
| `track_errors`               | Whether unhandled JavaScript errors are reported (also gates manual `clickbase.error()`).                                               |
| `track_web_vitals`           | Whether Core Web Vitals are measured and sent.                                                                                          |
| `track_session_replay`       | Whether the session is recorded for replay. Forced to `false` when the team can't currently ingest events, even if the site flag is on. |
| `session_replay_sample_rate` | Percentage of sessions recorded, `0`–`100`.                                                                                             |

## Where to change these

Every remote toggle is set from the site's settings in your dashboard, or through the API:

* **Tracking mode** — `PATCH /api/sites/{siteKey}/tracking-mode` ([Sites](/api/sites#update-tracking-mode)).
* **Web Vitals / error tracking / session replay** — the enable endpoints in [Tracking configuration](/api/tracking-config).

Changing any of them invalidates the config cache, so the next config fetch returns the new values.