trackkit / index / FacadeOptions

Interface: FacadeOptions

Defined in: types.ts:248

Core analytics facade configuration options.

These control the behaviour of the Trackkit facade layer – the piece that manages:

• URL resolution and normalisation
• consent and policy gating
• queueing and dedupe
• navigation integration

They apply regardless of which concrete provider you configure.

All fields are required in the internal ResolvedFacadeOptions; callers use them via AnalyticsOptions, where everything is optional with sensible defaults.

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.

---

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.

---

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.

---

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.

---

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.

---

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.

---

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.

---

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

---

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.

---

trackLocalhost?

optional trackLocalhost: boolean

Defined in: types.ts:322

Whether to track events on localhost and similar development hosts.

---

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.

---

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.

---

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

---

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

---

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