--- url: 'https://docs.kitbase.dev/tracking-script.md' description: >- Add Kitbase analytics to any website with a lightweight tracking script. Privacy-friendly, no cookies, works on static sites, SPAs, and SSR. --- # Tracking Script Kitbase provides a lightweight tracking script for web analytics and event tracking. It is privacy-friendly, requires no cookies by default, and works on any website -- static HTML, single-page applications (SPAs), and server-side rendered (SSR) frameworks alike. ## Installation ### Script Tag (Simplest) Add these two snippets to your HTML `` section: ```html ``` The `KITBASE_CONFIG` object **must** be set before the tracking script loads. The `defer` attribute ensures the script is fetched in parallel and executed after the HTML is parsed, so it never blocks page rendering. ### NPM Package For JavaScript/TypeScript projects with a build step, install the SDK as a dependency: ::: code-group ```bash [pnpm] pnpm add @kitbase/analytics ``` ```bash [npm] npm install @kitbase/analytics ``` ```bash [yarn] yarn add @kitbase/analytics ``` ::: Then initialize the SDK in your application entry point: ```typescript import { init } from '@kitbase/analytics'; const kitbase = init({ sdkKey: 'YOUR_SDK_KEY', analytics: { autoTrackPageViews: true, trackBfcacheRestore: true, autoTrackOutboundLinks: true, autoTrackClicks: true, autoTrackScrollDepth: true, autoTrackVisibility: true, }, }); ``` ::: tip Lite Build For a smaller bundle size (~12KB vs ~50KB), use the lite build which excludes offline queue support: ```typescript import { init } from '@kitbase/analytics/lite'; ``` The lite build has the same API surface for analytics and event tracking. Only the offline queue module (`offline` config) is removed. ::: ## Configuration Reference Below is the full configuration object with every available option and its default value. ```typescript const kitbase = init({ // ── Core ─────────────────────────────────────────────── sdkKey: 'YOUR_SDK_KEY', // Required. SDK API key from the dashboard. debug: false, // Enable console logging for troubleshooting. baseUrl: 'https://ingest.kitbase.dev', // Ingestion endpoint. Override for self-hosted. storage: localStorage, // Storage backend for the anonymous ID. // Set to `null` to disable persistence. storageKey: 'kitbase_anonymous_id', // Key used in the storage backend. // ── Analytics ────────────────────────────────────────── analytics: { autoTrackPageViews: true, // Fire `screen_view` on every navigation. trackBfcacheRestore: true, // Fire `screen_view` on bfcache restore (back/forward in MPAs). autoTrackOutboundLinks: true, // Fire `outbound_link` for external link clicks. autoTrackClicks: true, // Fire `click` for interactive element clicks. autoTrackScrollDepth: true, // Fire `scroll_depth` when the user leaves a page. autoTrackVisibility: true, // Observe `data-kb-track-visibility` elements. }, // ── Offline Queue ────────────────────────────────────── offline: { enabled: false, // Queue events when offline, sync when back. maxQueueSize: 1000, // Maximum events held in the queue. flushInterval: 30000, // Flush interval in milliseconds (30 s). flushBatchSize: 50, // Events sent per batch. maxRetries: 3, // Retry attempts before an event is dropped. retryBaseDelay: 1000, // Base delay for exponential backoff (1 s). }, }); ``` ### Configuration Options Summary | Option | Type | Default | Description | |--------|------|---------|-------------| | `sdkKey` | `string` | -- | **Required.** SDK API key from your dashboard. | | `debug` | `boolean` | `false` | Enable verbose console logging. | | `baseUrl` | `string` | `'https://ingest.kitbase.dev'` | Ingestion endpoint. Override for self-hosted deployments. | | `storage` | `Storage \| null` | `localStorage` | Storage backend for anonymous ID persistence. Set to `null` to disable. | | `storageKey` | `string` | `'kitbase_anonymous_id'` | Key name used in the storage backend. | #### `analytics` | Option | Type | Default | Description | |--------|------|---------|-------------| | `autoTrackPageViews` | `boolean` | `true` | Automatically track page views on navigation. | | `trackBfcacheRestore` | `boolean` | `true` | Track a pageview when the browser restores a page from the back-forward cache (bfcache). Important for MPA sites where back/forward navigation does not re-execute scripts. | | `autoTrackOutboundLinks` | `boolean` | `true` | Track clicks on links to external domains. | | `autoTrackClicks` | `boolean` | `true` | Track clicks on interactive elements. | | `autoTrackScrollDepth` | `boolean` | `true` | Report maximum scroll depth when the user leaves. | | `autoTrackVisibility` | `boolean` | `true` | Observe elements with `data-kb-track-visibility`. | #### `offline` | Option | Type | Default | Description | |--------|------|---------|-------------| | `enabled` | `boolean` | `false` | Enable the offline event queue. | | `maxQueueSize` | `number` | `1000` | Maximum events to hold in the queue. | | `flushInterval` | `number` | `30000` | Interval between automatic flushes (ms). | | `flushBatchSize` | `number` | `50` | Events sent per flush batch. | | `maxRetries` | `number` | `3` | Retry attempts before an event is dropped. | | `retryBaseDelay` | `number` | `1000` | Base delay for exponential backoff (ms). | ## What the Script Does (Behind the Scenes) When the tracking script loads, it performs the following sequence of actions automatically. Understanding this lifecycle helps you debug issues and reason about the data you see in the dashboard. ### 1. Generates an Anonymous ID A UUID v4 is generated and stored in `localStorage` under the key `kitbase_anonymous_id`. This ID persists across page loads so the same browser is recognized as the same visitor without cookies. If `storage` is set to `null`, the ID is regenerated on every page load. ### 2. Starts a Session A `session_start` event is fired with a new session ID (UUID v4). The session remains active as long as events arrive within 30 minutes of inactivity. After 30 minutes of inactivity, the next interaction starts a fresh session. ### 3. Listens for Page Navigations The SDK patches `history.pushState` and listens for the `popstate` event. This means route changes in single-page applications are detected automatically -- no framework-specific code is needed. ### 4. Tracks Page Views A `screen_view` event is fired on the initial page load and on every subsequent navigation (pushState or popstate). Each event includes the page path, document title, referrer, and any UTM parameters present in the URL. ### 5. Monitors Clicks on Interactive Elements A global click listener watches for clicks on interactive elements: ``, `