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