SDK overview & configuration

The Spectry SDK is a single async script you add to your site. It auto-initialises on page load — no manual bootstrapping required — and exposes a global window.Spectry object for advanced use.

What it collects automatically

Once consent is granted, the SDK tracks (subject to your feature and consent settings):

• Page views & navigation, including SPA route changes (pushState/replaceState/popstate).
• Scroll depth and session end (duration, page count).
• Core Web Vitals — FCP, LCP, CLS, INP, TTFB.
• Outbound link clicks.
• Heatmap interactions — clicks, mouse moves, scroll (with the heatmaps category).
• Friction & errors — rage clicks, dead clicks, JavaScript errors, attack signals.
• Session replay — when enabled and sampled.

Configuration

Most configuration lives in your site settings in the dashboard (features, privacy, replay sampling) and is fetched by the SDK at runtime — so you can change behaviour without editing code. Snippet-level options:

• data-site-id — your Site ID.
• data-write-key — optional request-signing key. See allowed domains & write key.

Single-page applications

No extra work is required. The SDK hooks pushState, replaceState and popstate, so a route change is recorded as a page view, scroll tracking resets for the new route, and accumulated Core Web Vitals are attributed to the URL they actually happened on rather than to your entry page.

When the SDK does nothing

The SDK short-circuits — collecting nothing at all — when:

• the URL contains ?spectryDisable=1 (useful for internal QA and for excluding your own team);
• the browser sends Global Privacy Control or Do Not Track;
• the user agent matches a known bot, crawler, or headless/automation tool (Googlebot, Puppeteer, Playwright, Lighthouse, uptime monitors and similar).

That last one is why synthetic monitoring and your own Lighthouse runs never show up in analytics — and why comparing Spectry's Core Web Vitals to a Lighthouse score is comparing real visitors to a lab test.

The JavaScript API at a glance

// Events & users
Spectry.track('event_name', { any: 'data' });
Spectry.identify('user_123', { email, plan });
Spectry.resetIdentity();

// Consent
Spectry.acceptAll();
Spectry.setConsent({ analytics: true, replay: false });
Spectry.getConsent();
Spectry.openConsentBanner();

// Feature flags
Spectry.getFlag('new_checkout');

// Ecommerce
Spectry.setCartValue(129.90, 'EUR');

See the dedicated pages for custom events, identifying users, feature flags and the full API reference.