Configuration

Your workspace’s write key, sent as the X-Write-Key header. Find it under Settings → API keys. Write keys can only ingest events — they can’t read data or change settings — so they’re safe to ship in browser code.

The collector base URL, e.g. https://api.pivolio.com. Point this at your own subdomain to beat ad-blockers and Safari ITP — see First-party domains.

Cookie domain, e.g. .example.com. Set this when you track across subdomains — without it, shop.example.com and www.example.com mint separate visitors. For separate registrable domains use the cross-domain linker instead.

Cookie path.

Prefix for every cookie and storage key the SDK writes. Change it only to avoid a collision with another script on the page; changing it on a live site orphans the existing identity and every visitor is counted as new.

Set the Secure flag, restricting cookies to HTTPS. Turn it off only for local development over plain HTTP.

Anonymous ID cookie lifetime, in days.

How long captured UTMs and click IDs persist, in days. This is your client-side attribution window; the server applies per-platform click expiry on top of it, so raising this beyond 90 days buys little.

Inactivity before a new session starts, in minutes.

Fire a page_view automatically when the tracker initializes. If you call page() yourself, leave this off or you’ll count every landing twice.

Emit a page view on history.pushState/replaceState and popstate. Enable it for a single-page app that doesn’t reload between routes.

On Next.js, use <PivolioPageView /> instead — it’s App Router-aware, and combining the two double-counts navigations.

Stamp test_mode: true on every event. This excludes them from your billable usage and lets you filter them out of the events list.

It does not stop delivery and does not exclude them from reporting — test events still dispatch to connected destinations and still count in your dashboards. Use a separate workspace to isolate staging, not this flag.

Verbose console logging. Toggle it at runtime with debug(true).

When the browser sends Do Not Track, disable the tracker entirely — it never initializes, and isInitialized() returns false.

Initial Google Consent Mode v2 state: { ad_storage, analytics_storage, ad_user_data, ad_personalization }, each 'granted' or 'denied'. Unset is treated as not-denied. See Identity and consent for what each category gates.

Buffer events and send them via /batch. Turning this off sends each event immediately via /track — simpler to debug, materially more requests.

Events buffered before an immediate flush.

Maximum time to hold a partial batch, in milliseconds.

Per-request timeout, in milliseconds.

Total attempts before falling back to sendBeacon, with exponential backoff between them. 4xx responses other than 429 are permanent and stop retrying immediately — retrying a rejected payload only wastes the visitor’s battery.

Fires after an event is accepted by the collector.

Fires only after every delivery path has failed: retried fetch, then sendBeacon, then persisting to the offline queue. An event that lands in the offline queue is not lost — it is retried on the next page load — so this callback firing means the event is genuinely gone.