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:

• ?id= in the script URL — your Site ID. This is the one the SDK reads first, and the install snippet sets it for you.
• data-site-id — your Site ID.
• data-write-key — optional request-signing key. See allowed domains & write key.

One dashboard setting is worth calling out here because it changes what the SDK reads:

• Data layer bridge — off by default; turn it on under Site settings → Features → Data Layer. When enabled, the SDK reads your existing window.dataLayer: a push carrying an event key becomes a tracked event, and a push without one becomes visitor context. Google Tag Manager keeps working unchanged. See event context and variables.

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();

// Context — set once, attached to every event that follows
Spectry.setContext({ plan: 'pro', account_type: 'business' });
Spectry.getContext();
Spectry.clearContext();

// 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, event context, identifying users, feature flags and the full API reference.

Working on the backend instead? The Node.js SDK reads flags and sends events from your own servers, with no browser involved.