Configuration - Clickbase Docs

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.
`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.
`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):

<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:

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. 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:

{
    "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.
`track_initial_pageview`	Whether the widget auto-fires a pageview on load. See Pageviews & SPAs.
`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.
`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).
Web Vitals / error tracking / session replay — the enable endpoints in Tracking configuration.

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

​Install-time data attributes

​Global event properties

​Remote configuration

​What each field controls

​Where to change these

Install-time data attributes

Global event properties

Remote configuration

What each field controls

Where to change these