JavaScript API reference

All methods are available on the global window.Spectry object after the snippet loads.

Events & users

• Spectry.track(name, properties?) — record a custom event. Ignored without analytics consent.
• Spectry.identify(userId, traits?) — attach a stable user ID and traits. Also writes the ID and any scalar traits into context, so events sent afterwards carry them.
• Spectry.resetIdentity() — clear identity and context, and issue a new anonymous ID (call on logout).

Context

Context is the state that describes the visitor, as opposed to what just happened. Set it once and it is attached to every event that follows. See Event context and variables.

• Spectry.setContext(attributes) — shallow-merge attributes into the visitor's context.
• Spectry.getContext() — read the current context back as an object.
• Spectry.clearContext(keys?) — clear the named keys, or the whole context when called with no argument.

Limits

Context is attached to every event, so it is deliberately bounded. Values outside these limits are dropped silently rather than throwing:

• Values must be a string, number, boolean or null. Objects and arrays are dropped — use event properties for nested data.
• Keys may contain letters, digits, _, . and -, up to 64 characters.
• Up to 32 keys, strings up to 255 characters, and 2 KB serialised in total.
• Kept for 30 days, refreshed on each write, and shared across tabs.
• Held in memory until analytics consent is granted, then persisted. Revoking analytics consent erases it immediately.

Ecommerce

• Spectry.setCartValue(value, currency?) — record the visitor's cart total for the session.
• Spectry.getCartValue() — read it back.
• Spectry.clearCartValue() — clear it (e.g. after checkout completes).

Consent

• Spectry.acceptAll() / Spectry.declineAll() — set all categories at once.
• Spectry.setConsent({ analytics, heatmaps, feedback, replay }) — set individual categories.
• Spectry.getConsent() — read the current consent state.
• Spectry.onConsentChange(callback) — listen for changes.
• Spectry.revokeConsent() — revoke all consent.
• Spectry.openConsentBanner() — reopen the banner (e.g. from a footer link). Available once the banner has initialised.

Feature flags

• Spectry.getFlag(key) — read a flag's value, or null if unknown or not yet loaded.
• Spectry.onFlagChange(key, callback) — listen for flag changes.

Behaviour notes

• Events use navigator.sendBeacon when available, falling back to fetch with keepalive — so data still leaves the page during unload.
• Every request carries the current consent state, and the server re-validates it before storing anything.
• Calls that require consent are no-ops until that consent is granted. Nothing is buffered and retried.
• Revoking consent tears down the affected subsystems immediately (e.g. replay stops mid-session) and erases stored context.
• setContext is the one call that still does something useful before consent: values are held in memory and written to storage only once analytics consent is granted. A visitor who declines never has context stored at all.
• Failures are swallowed — the SDK never throws into your application code, and never blocks rendering. The flip side is that a misconfigured call gives you no error; check the dashboard to confirm data is arriving.

Core Web Vitals: how they're measured

Vitals follow the official definitions rather than a naive reading, so Spectry's numbers line up with Chrome's field data:

• CLS uses the session-window algorithm — the largest burst of shifts within a 5-second window with 1-second gaps, not the lifetime sum. Shifts that follow user input are excluded.
• INP takes the worst latency per interaction, then reports roughly the 98th-percentile interaction, not the single worst event.
• LCP stops accruing at the first keypress or pointer press, per spec.
• TTFB subtracts activationStart, so prerendered pages aren't credited with a negative or misleadingly fast time.
• Metrics are flushed on pagehide and on visibilitychange to hidden — deliberately not beforeunload, which breaks the back/forward cache and is unreliable on mobile.
• On SPA route changes, whatever accrued is attributed to the URL it happened on before the accumulators reset.

For thresholds and how to read the results, see Core Web Vitals. For consent UI configuration, see Configure the Spectry consent banner.