kobbe

Script options

Configure Kobbe tracker options for endpoints, hash routes, Web Vitals, and debugging.

Use data-* attributes on the <script> tag to configure the tracker.

The default tracker.js is lightweight and covers pageviews, custom events, custom endpoints, hash routes, UTM campaign capture, and debug logging. Advanced features such as cross-domain tracking, performance collection, and scroll tracking use tracker.full.js.

See also: Custom events · Scroll tracking · Hash page paths · UTM campaigns · Subdomains · Cross-domain tracking · Performance and Web Vitals · Exclude visits

Required

Site token

Your site token from Kobbe. It tells Kobbe which site should receive the pageview or event.

data-token="YOUR_SITE_TOKEN"

Example

<script
  defer
  data-token="YOUR_SITE_TOKEN"
  src="https://app.kobbe.io/tracker.js"
></script>

Optional

Custom collect endpoint

Override the full collect API URL. By default, the tracker posts to /api/collect on the same origin as tracker.js.

data-endpoint="https://my-worker.example.com/api/collect"

Hash-based routes

Set to true to include location.hash in page paths. Use only when hashes represent real routes. See Hash page paths.

data-track-hash="true"

UTM campaigns

Set to true to capture only allowlisted UTM fields (utm_source, utm_medium, utm_campaign, utm_term, utm_content). Query strings are still stripped from stored paths. See UTM campaigns.

data-campaigns="true"

Cross-domain hostnames

Allow cross-domain tracking for specific hostnames. Requires tracker.full.js. See Cross-domain tracking.

data-allowed-hostnames="app.example.com,shop.example.net"

Web Vitals collection

Set to true to send Web Vitals samples (LCP, INP, CLS, FCP, TTFB). Requires tracker.full.js. See Performance and Web Vitals.

data-performance="true"

Debug logging

Set to true while troubleshooting to log failed collect responses in the browser console. Remove after debugging.

data-analytics-debug="true"
<script
  defer
  data-token="YOUR_SITE_TOKEN"
  data-endpoint="https://my-worker.example.com/api/collect"
  data-allowed-hostnames="app.example.com,shop.example.net"
  src="https://app.kobbe.io/tracker.full.js"
></script>

When injecting the script from JavaScript, set script.dataset.token and optionally script.dataset.endpoint (for data-endpoint) or script.dataset.trackHash = "true" (for data-track-hash) before appending the element.

Element attributes

The tracker also supports opt-in attributes on your page elements:

Click events

Sends a custom event when the element is clicked. Optional data-kobbe-event-* attributes become string props.

data-kobbe-event="Newsletter signup"

Section visibility events

Sends a one-time section visibility event when the element enters the viewport.

Requires tracker.full.js.

data-kobbe-scroll="viewed_pricing"

Visibility threshold

Visibility threshold for data-kobbe-scroll. Default: 0.5. Allowed range: 0.1 to 1.

data-kobbe-scroll-threshold="0.75"

Visibility delay

Delay in milliseconds before a scroll event is sent. Default: 0. Maximum: 10000.

data-kobbe-scroll-delay="500"

See Scroll tracking for privacy guidance and examples.

Bot filtering and exclusions

Kobbe applies automatic bot detection on every collect request (e.g. headless clients and common crawler signals). Suspicious requests return a success response but do not increment usage or store an event.

Exclusions are separate: per-site rules you set in the Kobbe app (path, hostname, country, IP, or “ignore my browser” via localStorage). Those are evaluated after the bot filter and after your site is resolved. See Exclude visits and Reduce usage.

Local development

There is no separate “localhost toggle”: if your dev site loads the snippet with a valid token, events are sent like production. Use a dedicated test site in Kobbe when you want to keep local traffic out of production stats.

How it works

  • The script sends a pageview when the page loads (and on hashchange when data-track-hash is enabled).
  • The current path is sent without query strings. Hash fragments are omitted by default and included only with data-track-hash="true".
  • Campaign tracking is off by default; when data-campaigns="true" is enabled, only known UTM fields are extracted from the query string.
  • Scroll tracking is off by default and requires tracker.full.js; marked elements send one custom event when they become visible (see Scroll tracking).
  • Cross-domain tracking is off by default and requires tracker.full.js; when enabled, allowlisted links receive a short handoff parameter that is cleaned from the destination URL and kept in sessionStorage for the current tab (see Cross-domain tracking).
  • Performance collection is off by default and requires tracker.full.js; when enabled, Web Vitals samples are stored separately from custom events and one accepted performance payload counts toward usage (see Performance and Web Vitals).
  • The page hostname is stored on each event and powers the Hostnames breakdown (and hostname exclusions when collect is proxied).
  • The referrer is reduced to the origin, so search queries and private URL data are not collected.
  • No cookies or persistent identifiers: optional localStorage.kobbe_ignore === "true" stops this browser from sending events (see Exclude visits).
  • Custom events use the same tracker script and the same site token (see Custom events and window.kobbe.track).