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.
• Spectry.resetIdentity() — clear identity and issue a new anonymous ID (call on logout).

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).
• 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.