trackkit / index / AnalyticsOptions

Interface: AnalyticsOptions

Defined in: types.ts:424

Configuration options for initialising the analytics system.

This is the main entry point for configuring Trackkit. It combines:

• facade options: core tracking behaviour (autoTrack, domains, consent, etc.)
• provider options: which analytics backend to use and how to configure it
• dispatcher options: transport, batching, and resilience settings

All facade options are optional and will use sensible defaults.

Example

const analytics = createAnalytics({
  provider: {
    name: 'ga4',
    measurementId: 'G-XXXXXXXXXX',
  },
  autoTrack: true,
  trackLocalhost: false,
  dispatcher: {
    batching: { enabled: true, maxSize: 10 },
  },
});

Extends

• Partial<FacadeOptions>

Properties

allowWhenHidden?

optional allowWhenHidden: boolean

Defined in: types.ts:255

Whether to allow tracking when the document is hidden.

When false, events may be skipped while the tab is backgrounded to avoid noisy data.

Inherited from

FacadeOptions.allowWhenHidden

---

autoTrack?

optional autoTrack: boolean

Defined in: types.ts:263

Automatically track page views.

When true, navigation events detected by the facade will emit pageview() calls without you needing to call them manually.

Inherited from

FacadeOptions.autoTrack

---

bustCache?

optional bustCache: boolean

Defined in: types.ts:271

Enable cache-busting for provider HTTP requests.

When true, Trackkit adds query params / headers to avoid accidental caching of analytics requests.

Inherited from

FacadeOptions.bustCache

---

debug?

optional debug: boolean

Defined in: types.ts:279

Enable debug logging to the console.

When true, the facade and dispatcher emit verbose logs under a Trackkit-specific logger namespace.

Inherited from

FacadeOptions.debug

---

domains?

optional domains: string[]

Defined in: types.ts:287

Whitelist of domains to track.

If set, only events whose hostname matches one of these entries will be sent.

Inherited from

FacadeOptions.domains

---

doNotTrack?

optional doNotTrack: boolean

Defined in: types.ts:295

Honour the browser’s “Do Not Track” setting.

When true and DNT is enabled, non-essential events will be blocked by policy.

Inherited from

FacadeOptions.doNotTrack

---

exclude?

optional exclude: string[]

Defined in: types.ts:303

Exclude paths from tracking.

Typically used for admin routes or internal tools. Matching happens against the resolved URL; see the docs for matching semantics.

Inherited from

FacadeOptions.exclude

---

includeHash?

optional includeHash: boolean

Defined in: types.ts:310

Include the URL hash fragment when computing the reporting URL.

Useful for hash-based SPAs that encode route state in #....

Inherited from

FacadeOptions.includeHash

---

queueSize?

optional queueSize: number

Defined in: types.ts:317

Maximum number of events to hold in the in-memory queue.

When this limit is exceeded, oldest events are dropped first.

Inherited from

FacadeOptions.queueSize

---

trackLocalhost?

optional trackLocalhost: boolean

Defined in: types.ts:322

Whether to track events on localhost and similar development hosts.

Inherited from

FacadeOptions.trackLocalhost

---

consent?

optional consent: ConsentOptions

Defined in: types.ts:332

Consent configuration and defaults.

Controls how consent categories map to providers and how the policy gate behaves. See ConsentOptions.

Inherited from

FacadeOptions.consent

---

navigationSource?

optional navigationSource: NavigationSource

Defined in: types.ts:341

Navigation source for SPA URL change detection.

When omitted, Trackkit falls back to a basic popstate / hashchange listener, which works well for many SPAs but can be overridden with router-specific integration.

Inherited from

FacadeOptions.navigationSource

---

onError()?

optional onError: (error) => void

Defined in: types.ts:351

Custom error handler for analytics errors.

Defaults to a console-based handler. You can integrate this with your own error reporting (Sentry, etc).

Parameters

error

AnalyticsError

Returns

void

Inherited from

FacadeOptions.onError

---

urlResolver()?

optional urlResolver: () => string

Defined in: types.ts:359

Provide a custom way to resolve the current URL.

When omitted, the facade derives it from window.location. This is typically only needed in SSR or highly customised routing setups.

Returns

string

Inherited from

FacadeOptions.urlResolver

---

urlTransform()?

optional urlTransform: (url) => string

Defined in: types.ts:372

Transform the resolved URL before it is used for:

• de-duplication,
• exclusions,
• and provider payloads.

Common use cases:

• stripping PII tokens from query params,
• normalising trailing slashes,
• collapsing noisy routes.

Parameters

url

string

Returns

string

Inherited from

FacadeOptions.urlTransform

---

provider?

optional provider: ProviderOptions

Defined in: types.ts:430

Analytics provider configuration (GA4, Plausible, Umami, or noop).

See ProviderOptions and provider-specific docs for details.

---

dispatcher?

optional dispatcher: DispatcherOptions

Defined in: types.ts:437

Advanced transport, batching, and resilience configuration.

See DispatcherOptions.