@cross-deck/web — Web SDK reference

@cross-deck/web is one SDK that handles all three Crossdeck pillars in a browser: verified subscriptions and entitlements, behavioural analytics, and error capture. Install it once, initialise with three options, and every customer gets one timeline across Stripe, Apple, and Google Play — plus events, sessions, Web Vitals, and uncaught errors flowing into the same dashboard.

TL;DR

• One install, three pillars. One package — @cross-deck/web — covers analytics, subscription/entitlement gating, and error capture. No separate Mixpanel + RevenueCat + Sentry stack.
• Three lines to start. npm install @cross-deck/web, call Crossdeck.init({ appId, publicKey, environment }), and you're collecting events, capturing errors, and ready to check entitlements.
• Auto-tracking by default. Page views, sessions, clicks, Web Vitals, and runtime errors are captured without writing any tracking code. Disable any of them via autoTrack options.
• Microsecond entitlement checks. Crossdeck.isEntitled("pro") reads from a local cache — safe to call inside a React render or a SwiftUI body.
• Bank-grade plumbing. Events survive crashes via a durable queue. Failed flushes retry with exponential backoff. Every batch carries an Idempotency-Key header. Network errors are caught and re-tried, not lost.
• Privacy-first defaults. Email and card-number patterns are scrubbed from event properties automatically. Three consent dimensions (analytics / marketing / errors) gate every transmission. Crossdeck.forget() implements GDPR right-to-be-forgotten.
• ~30 KB gzipped total. For comparison: Sentry's browser SDK is ~30 KB on its own, Mixpanel is ~55 KB, PostHog is ~40 KB. Crossdeck ships all three pillars in the same budget.

Install

Pick the install path that matches your stack. Every path ships the same SDK with the same API — only the surrounding wrapper changes. The onboarding flow asks which framework you're on and generates the right snippet automatically; this section is the manual reference.

npm — for bundled apps

npm install @cross-deck/web

If you're using React, the same package exports React hooks at @cross-deck/web/react. If you're using Vue 3, Vue composables live at @cross-deck/web/vue. Both are tree-shake-friendly subpath imports — no extra npm install step. Svelte and vanilla JS use the core @cross-deck/web import directly.

CDN script tag — for plain HTML pages

<script src="https://unpkg.com/@cross-deck/web@^1/dist/crossdeck.umd.min.js"></script>

The UMD bundle exposes window.Crossdeck.Crossdeck for direct use. jsdelivr.net works as a mirror at the same path. Pin to the current major (@^1) — it tracks every 1.x release but never a breaking 2.0. Avoid @latest, which ships breaking changes to your customers on every release.

Node.js — for server-side use

The same package works in Node 18+ for tests and rendering use cases. Pass { storage: new MemoryStorage(), autoHeartbeat: false } at init so the Node runtime doesn't try to read localStorage or fire boot heartbeats. Browser-only features (window.onerror, fetch wrapping, page.viewed, sessions) silently no-op — you only get the API methods you call explicitly.

import { Crossdeck, MemoryStorage } from "@cross-deck/web";

Crossdeck.init({
  appId: "app_node_xxx",
  publicKey: "cd_pub_test_…",
  environment: "sandbox",
  storage: new MemoryStorage(),
  autoHeartbeat: false,
});

Quickstart — five lines, three pillars

The fastest path from zero to "events flowing, entitlements checking, errors caught" is a Next.js / React app:

"use client"
import { useEffect } from "react";
import { Crossdeck } from "@cross-deck/web";
import { useEntitlement } from "@cross-deck/web/react";

export function RootProvider({ userId, children }) {
  useEffect(() => {
    Crossdeck.init({
      appId: "app_web_xxx",
      publicKey: "cd_pub_test_…",
      environment: "sandbox",
    });
    // Warm the entitlement cache so isEntitled() answers in microseconds
    Crossdeck.getEntitlements();
  }, []);

  useEffect(() => {
    if (userId) Crossdeck.identify(userId);
    else Crossdeck.reset();
  }, [userId]);

  return children;
}

function ProBadge() {
  const isPro = useEntitlement("pro");
  return isPro ? <span>Pro</span> : null;
}

That single setup gives you, automatically and without writing any more code:

• page.viewed events on every navigation (SPA-aware — pushState + popstate trigger them).
• session.started / session.ended events with a 30-minute idle session window matching GA4 semantics.
• element.clicked events for every interactive click, with selector, text, viewport coordinates, and any data-cd-prop-* attributes you tagged.
• webvitals.lcp, webvitals.inp, webvitals.cls, webvitals.fcp, webvitals.ttfb events flushed at page hidden.
• error.unhandled, error.unhandledrejection, error.http events for every uncaught JavaScript error, unhandled promise rejection, and HTTP 5xx response your app receives.
• UTM parameters and paid-traffic click IDs (gclid, fbclid, msclkid, ttclid, li_fat_id, twclid) captured at session start and attached to every event.
• A durable event queue persisted to localStorage so a tab crash doesn't lose data — events replay on next page load.

Initialise the SDK

Every browser app calls Crossdeck.init() exactly once at boot.

Crossdeck.init({
  appId: "app_web_xxx",           // required
  publicKey: "cd_pub_test_…",     // required
  environment: "sandbox",         // required: "sandbox" | "production"
});

Three required options. The trio is validated up-front — a typo'd key, a missing app ID, or a key prefix that doesn't match the declared environment all throw CrossdeckError at boot rather than failing silently at first network call.

Localhost dev mode (automatic)

The SDK detects when it's running on a local-development hostname (localhost, 127.0.0.1, ::1, *.local, RFC1918 ranges like 10.x / 192.168.x) and switches to a silent dev mode: every method works normally, but no network calls fire. A single line lands in the console explaining what happened:

[crossdeck] Localhost detected — running in dev mode (no network calls).
Set publicKey: 'cd_pub_test_…' and deploy to a real domain to test against the Crossdeck Sandbox.

This is intentional and Stripe-grade. A developer running their app on localhost:3000 with a live key cannot accidentally pollute their production analytics.

Idempotency

init() is synchronous and idempotent. Calling it twice with the same options is a no-op; calling it with different options replaces the previous configuration. There is no second call needed to "start" the SDK — init() IS the start.

Identity & users

Crossdeck tracks two identity axes:

• anonymousId — generated on first install, persisted across reloads. Identifies the device, not the human. Always present.
• developerUserId — your auth provider's stable user ID. Populated by Crossdeck.identify(userId). Links the anonymous device to a specific human.

A third value, crossdeckCustomerId (the cdcust_… identifier), is the canonical Crossdeck-side handle. The backend resolves it from the other two via an identity-graph merge. Most developers never have to think about it directly — the SDK persists it on the device after the first identify() resolves and uses it for subsequent calls.

Crossdeck.identify(userId, options?)

Link the anonymous device to your stable user ID. Returns a promise resolving to the resolved customer record.

await Crossdeck.identify("user_847", {
  email: "[email protected]",
  traits: {
    name: "Wes",
    plan: "pro",
    signedUpAt: "2026-05-11",
  },
});

Each call merges additively per key on the customer record. A later identify("user_847", { traits: { plan: "enterprise" } }) updates only plan — it does not wipe name or signedUpAt.

Traits are sanitised at the SDK boundary. Functions, symbols, and undefined values are dropped. Date objects are coerced to ISO strings. BigInt values are coerced to strings. Strings longer than 1024 characters are truncated with an ellipsis. The server applies a second-layer cap: max 32 keys, max 1 KB per value, primitives only — nested objects and arrays are dropped silently.

Crossdeck.reset()

Wipe persisted identity, entitlement cache, super-properties, groups, breadcrumbs, error context, and queued events. Call on logout. Synchronous. The next session mints a fresh anonymousId so a new user on the same device starts as a clean identity graph entry.

Before wiping, the SDK emits a user.signed_out event with the old identity stamped on it. The event leaves the queue with the correct user before reset clears local state — your dashboard's Activity stream shows the right sign-out attribution, not an anonymous orphan.

Super properties — set once, attached to every event

Mixpanel's register pattern. Register a property bag once; the SDK auto-attaches those keys to every subsequent track() call's properties.

Crossdeck.register({ plan: "pro", releaseChannel: "beta" });
Crossdeck.track("paywall_viewed");
// → properties include plan: "pro", releaseChannel: "beta"

Crossdeck.unregister("releaseChannel");
Crossdeck.getSuperProperties();
// → { plan: "pro" }

Values that are null are deleted (explicit "stop tracking this key"). Values that are undefined are silently ignored. Caller-supplied properties on track() override super-properties on key collision — your per-event data is always more authoritative.

Super properties persist across page reloads via localStorage (under the key crossdeck:super_props). They are cleared on Crossdeck.reset() and Crossdeck.forget() because they are identity-scoped, not SDK-instance-scoped.

Group analytics — for B2B SaaS

Associate the current user with one or more organisational entities (an organisation, team, account, workspace, plan tier). Every subsequent event carries $groups.<type>: id on its properties bag, so dashboards can pivot on group membership.

Crossdeck.group("org", "acme_inc");
Crossdeck.group("team", "design", { headcount: 12 });
Crossdeck.track("paywall_viewed");
// → properties include $groups: { org: "acme_inc", team: "design" }

Pass id: null to clear a membership. Multiple types coexist — a user can simultaneously belong to an org, a team, and a plan. Crossdeck.getGroups() returns the current state.

Events & analytics

Crossdeck.track(name, properties?)

Synchronous — enqueues an event. The network round-trip happens in the background batched flush.

Crossdeck.track("paywall_viewed", {
  variant: "v3",
  source: "upgrade-button",
});

Properties are validated at the SDK boundary before the event enters the queue. The contract is bulletproof — one bad property can never crash JSON.stringify at flush time or poison the batch:

• Functions, symbols, and undefined values are dropped.
• Date objects become ISO strings.
• BigInt values become strings.
• Error objects become { name, message, stack }.
• Map becomes a plain object, Set becomes an array.
• Strings longer than 1024 characters are truncated with an ellipsis.
• Circular references are replaced with "[circular]".
• Objects nested deeper than 5 levels become "[depth-exceeded]".
• If the property bag exceeds 8 KB total, the largest fields drop first and a __truncated: true marker is added.
• The caller's input object is never mutated — sanitisation always produces a defensive copy.

The output is JSON-safe by contract.

Auto-tracked events

When init() is called in a browser, the SDK installs its auto-tracker and emits the events in the table below without any further code. Each can be disabled via the autoTrack init option (covered in Configuration reference).

Enrichment attached to every event

Every event the SDK ships carries a baseline set of properties auto-attached by the client. You don't have to send any of these explicitly; they appear on every event automatically:

• Device: os, osVersion, browser, browserVersion, locale, timezone, screenWidth, screenHeight, viewportWidth, viewportHeight, devicePixelRatio.
• App: appVersion (when passed to init()).
• Session: sessionId, pageviewId.
• Acquisition (first-touch, session-scoped): utm_source, utm_medium, utm_campaign, utm_content, utm_term, referrer.
• Paid-traffic click IDs (when present in the landing URL): gclid, fbclid, msclkid, ttclid, li_fat_id, twclid.
• Super properties: every key you've called register() for.
• Groups: $groups: { type: id, … }.

Click autocapture with custom tags

The default element.clicked event covers most behavioural analytics. For higher-fidelity tagging, add data-cd-* attributes to your HTML:

<button data-cd-event="upgrade_clicked" data-cd-prop-plan="pro" data-cd-prop-source="paywall">
  Upgrade
</button>

This emits upgrade_clicked (instead of element.clicked) with { plan: "pro", source: "paywall" } on the properties bag.

To exclude a subtree from autocapture (e.g. a sensitive form, an embedded widget), add class="cd-noTrack" or data-cd-noTrack to its container. No events fire from descendants of an opted-out element.

Flush control

Events flush automatically when the buffer reaches eventFlushBatchSize (default 20) or after eventFlushIntervalMs of inactivity (default 1500 ms). To force-flush before a critical moment:

await Crossdeck.flush();

The SDK also installs pagehide, beforeunload, and visibilitychange→hidden listeners that fire a terminal flush with keepalive: true, so events queued just before unload still land on the server.

Entitlements & gating

Entitlements are the named "what this user is allowed to do" facts your app reads to gate paid features — pro, team, ai_addon, whatever your catalog defines. A customer holds a set of them. The SDK maintains a durable local cache so isEntitled("pro") answers in microseconds — safe inside a React render or any hot path.

Crossdeck.getEntitlements()

Async. Fetches the current customer's active entitlements from the server, replaces the local cache, and persists it to device storage. Call once after identify() resolves; subsequent isEntitled() / useEntitlement() reads are sync cache hits. A failed fetch never clears the cache — only a successful fetch replaces it.

const entitlements = await Crossdeck.getEntitlements();
// → PublicEntitlement[]

Crossdeck.isEntitled(key): boolean

Synchronous. Reads from the local cache, with zero I/O. Returns true iff a matching entitlement is active and not past its own validUntil — so a timed-out trial reads false even while still cached. Microsecond lookup — call it inside any render path. For a returning customer it is correct from the very first call: the cache hydrates from device storage on SDK boot (see below). It only returns false for a genuinely unknown entitlement, an expired one, or a brand-new install with nothing stored yet.

The cache is durable last-known-good

The entitlement cache (sdks/web/src/entitlement-cache.ts) is not a plain TTL cache. It is durable last-known-good — the RevenueCat model — and that has two consequences worth relying on:

• It survives reloads. Every successful getEntitlements() is written to device storage and re-hydrated synchronously when the SDK boots. A returning Pro customer reads isEntitled("pro") === true before the boot fetch even resolves — there is no cold-start window where they flash as free. The cache clears only on reset() (logout) and on an identity switch; there is no TTL.
• It rides out a Crossdeck outage. A failed getEntitlements() never touches the stored set — only a successful fetch replaces it. If Crossdeck is briefly unreachable, the SDK keeps serving the last entitlements it successfully fetched. An outage cannot fail a paying customer down to free. Per-entitlement validUntil is still honoured, so a trial that ends mid-outage still ends.

Serving stale data through an outage is the right trade, but it must be visible. Once a refresh attempt fails — or last-known-good ages past 24 hours — the cache flags itself stale, surfaced as diagnostics().entitlements.stale. Staleness never changes what isEntitled() returns; it only makes serving-through-an-outage something you can observe and alert on (an event-based revoke such as a chargeback has no validUntil, so this flag is how that case stays visible).

useEntitlement(key) — React

import { useEntitlement } from "@cross-deck/web/react";

function ProBadge() {
  const isPro = useEntitlement("pro");
  return isPro ? <span>Pro</span> : null;
}

SSR-safe: useEffect is a no-op on the server, the initial state is the cache's current value (false pre-init), so server output never claims a non-existent entitlement. Hydrates correctly on the client.

Sibling hook: useEntitlements() returns an array of active entitlement keys, kept in sync with the cache.

useEntitlement(key) — Vue 3

<script setup>
import { useEntitlement } from "@cross-deck/web/vue";
const isPro = useEntitlement("pro");  // Ref<boolean>
</script>

<template>
  <span v-if="isPro">Pro</span>
</template>

Crossdeck.syncPurchases(input)

Async. Forward Apple StoreKit 2 transaction evidence directly to Crossdeck for server-side verification. Used by hybrid web apps that live alongside an iOS native app on the same Crossdeck customer.

await Crossdeck.syncPurchases({
  signedTransactionInfo: "<JWS from Transaction.currentEntitlements>",
  signedRenewalInfo: "<optional JWS>",
});

Stripe and Google Play do not need this call — those rails deliver evidence server-side via webhooks. Only Apple's flow requires client-side forwarding.

Error capture

The third Crossdeck pillar. Default-on — installing the SDK gets you Sentry-grade error monitoring with no further code. Every captured error flows through the same durable, retried, idempotent queue analytics uses; reports are gated by the consent.errors dimension; PII is scrubbed automatically.

What gets caught automatically

• Uncaught synchronous errors via window.addEventListener("error", …) → error.unhandled.
• Unhandled promise rejections via window.addEventListener("unhandledrejection", …) → error.unhandledrejection.
• Failed HTTP requests — the SDK wraps fetch and XMLHttpRequest. Status >= 500 or a network-layer failure becomes error.http. Crossdeck's own API calls are explicitly excluded to prevent cycle-amplification on a Crossdeck outage.

Getting complete error data — symptom → fix

Capture is on by default, but whether each error arrives complete and useful depends on a few things on your side. When one is missing the failure is quiet or misleading — a blank stack, an anonymous error, nothing at all — and it looks like Crossdeck is broken when really a setup step was skipped. Every row is framed by what you'd see, so you can self-diagnose from the symptom.

Blank or empty stack traces — fix cross-origin scripts

If your errors arrive as a generic Script error with an empty frames array, the failing script is cross-origin and the browser is hiding its detail. The browser only exposes a cross-origin script's error detail when the tag carries crossorigin and the script's origin sends a CORS header:

<!-- the script tag on your page -->
<script src="https://cdn.yourdomain.com/app.js" crossorigin="anonymous"></script>

// the server/CDN serving app.js must send:
Access-Control-Allow-Origin: *        // (or your specific page origin)

Minified, unreadable stack traces — upload source maps

If stacks arrive present but minified (a.b.c is not a function at bundle.min.js:1:48217), no source map was uploaded for that release. Upload maps at build time, keyed to the same release identifier your build ships with:

crossdeck upload-sourcemaps \
  --release v1.2.3 \
  --url-prefix https://app.example.com/static/js/ \
  ./dist

Missing React / Vue render crashes — forward from your error boundary

If your React or Vue render crashes never appear, the framework's error boundary is catching them before they reach the global handler. Forward them yourself — there's no Crossdeck boundary component to install; it's two lines in your own:

class ErrorBoundary extends React.Component {
  componentDidCatch(error, info) {
    Crossdeck.captureError(error, { context: { react: info } });
  }
  render() { return this.props.children; }
}

Anonymous errors (Developer ID: Not linked) — call identify()

If errors arrive but aren't attributed to a known user, identify() hadn't run for that visitor before the error fired — anonymity is an absence, not an error, so there's nothing for the dashboard to flag. Call it after sign-in and every error after that attaches to the user:

await Crossdeck.identify(userId);

Nothing arrives under a strict CSP — allowlist the endpoint

Under a strict Content-Security-Policy the reporting request is blocked before it sends — Crossdeck never receives it, so there's nothing for it to flag, but your browser console shows a CSP violation for api.cross-deck.com. Allowlist the endpoint in connect-src:

Content-Security-Policy: connect-src 'self' https://api.cross-deck.com;

One rule ties these together: if the failure leaves a fingerprint Crossdeck receives (a blank cross-origin stack, a minified frame with no map), the dashboard flags it for you. If nothing reaches Crossdeck at all (a swallowed try/catch, a CSP-blocked beacon, an error that fired before identify()), only this setup prevents it — there's no error for Crossdeck to annotate.

Manual capture

try {
  await risky();
} catch (err) {
  Crossdeck.captureError(err, {
    context: { cart: { items: 3 } },
    tags: { flow: "checkout" },
    level: "error",
  });
}

Crossdeck.captureMessage(msg, level?) reports a non-error signal as an issue (e.g. "deprecated path hit", "soft warning"). Emits error.message.

Tags & context — attach metadata to every error

Crossdeck.setTag("release", "v2.3.1");
Crossdeck.setTags({ flow: "checkout", experiment: "v3" });
Crossdeck.setContext("cart", { items: 3, total: 42.99 });

Tags are flat { key: value } string pairs for filtering. Context is a named structured blob for richer detail. Both attach to every subsequent error report. Cleared on reset() / forget().

Breadcrumbs — what the user did just before the crash

The SDK keeps a rolling buffer of the last 50 things the user did — page views, clicks, custom events. When an error fires, the buffer is attached so the engineer reading the report can replay the path into the broken state.

Automatic breadcrumbs cover every track() call (except error.* and webvitals.* events, which would create noise). For domain-specific moments not already auto-captured, add manual crumbs:

Crossdeck.addBreadcrumb({
  timestamp: Date.now(),
  category: "custom",
  message: "user-opened-paywall",
  data: { variant: "v3" },
});

Fingerprinting — group identical errors

Every error gets an 8-character hex fingerprint derived from the message and the top 3 in-app stack frames. Identical errors share a fingerprint, so 1,000 occurrences of one bug appear as 1 issue in your dashboard, not 1,000 events.

Rate limiting & sampling

• Per-fingerprint cap: max 5 reports per minute, per fingerprint. Defends against runaway loops (an error inside setInterval).
• Per-session cap: max 100 total errors. After that, capture stops silently until the next session — the dashboard sees "1 unique error" instead of a million identical events.
• Sampling: error capture sends every error it keeps (internal sample rate 1.0) — there is no client-side sampling rate to configure. Volume is controlled by the per-fingerprint and per-session caps above, not by a sample knob.

Built-in noise filtering

By default, the SDK suppresses:

• ResizeObserver loop limit exceeded and the related … undelivered notifications variant — classic browser-internal noise, not an application bug.
• Errors with top-frame URLs starting with chrome-extension://, moz-extension://, safari-extension://, webkit-extension://, safari-web-extension:// — browser-extension errors aren't your code.

Add to the ignore list or URL gates via init options (see Configuration reference).

HTTP 0 is connection noise, not an error

A captured error with HTTP status 0 is classified as a distinct connection_noise class — never a real error, regardless of host, URL, method, or framework. Status 0 means the request never reached a server: a cancelled request, a closed tab, a dropped connection, an ad blocker, tracking protection, or VPN interference. There is nothing on your side to fix. The trigger is status === 0 alone — Crossdeck fixes the category, not the host, because every blocked tracker (Firestore Listen, GA g/collect beacons, a new pixel domain) is otherwise an endless game of whack-a-mole.

• Collected, never dropped. HTTP-0 events are still captured and stored — the full firehose stays auditable.
• Excluded from Issues. They never roll up into an issue you would triage and never appear in the default Issues list.
• Never prioritized, never alerted. Connection noise cannot carry a priority — not HIGH, not auto — and no spike or breadth signal escalates it. It never fires an email or Slack alert.
• Inspectable on demand. The Issues page has a Connection noise toggle that surfaces only this class, for when you want to see exactly what is being filtered.

Crossdeck.setErrorBeforeSend(hook) — the redaction last line

Install a pre-send filter. The hook is called LAST, after the rate limit, sampling, and URL gates have already passed. Return null to drop the error entirely, or a modified CapturedError to scrub specific fields.

Crossdeck.setErrorBeforeSend((err) => {
  if (err.message.includes("auth-token")) return null;
  err.context = { ...err.context, scrubbed: true };
  return err;
});

A throwing hook falls back to the original error rather than dropping the report — your buggy hook code cannot make errors disappear silently.

Crash safety

Every code path in the error-capture module is wrapped in try / swallow. A bug in the SDK can never take down the host app's error handler. A recursion guard prevents the SDK from reporting its own errors recursively forever.

Privacy & consent

Three consent dimensions

Crossdeck.consent({
  analytics: false,    // drops track() + identify() + auto events
  marketing: false,    // drops paid-traffic click IDs + referrer URL
  errors: true,        // keeps error reporting + Web Vitals on
});

Each dimension defaults to true (granted). Pass partial state — only the keys you provide are changed. Crossdeck.consentStatus() returns the current snapshot.

Gating policy per event family:

• error.* events → gated by consent.errors.
• webvitals.* events → gated by consent.errors (treated as performance/reliability data, not behavioural analytics).
• Paid-traffic click IDs (gclid, fbclid, etc.) + full referrer URL → gated by consent.marketing.
• Everything else → gated by consent.analytics.

Do Not Track

Opt in to honour the browser's navigator.doNotTrack header by passing respectDnt: true to init(). When enabled, and the browser reports DNT, all three consent dimensions are locked off permanently. Subsequent consent({...: true}) calls cannot flip a DNT-derived deny back on.

Defaults to false because industry has effectively deprecated DNT — opt-in support is the polite default for privacy-first apps.

PII scrubbing

Enabled by default (scrubPii: true). The SDK runs a regex pass on every string property value, URL, and title before flush — email-shaped substrings become [email], card-number-shaped sequences become [card]. The caller's original object is never mutated.

This protects against unintentional PII leakage in URLs like /users/[email protected]/profile which would otherwise ship verbatim. Set scrubPii: false only when your pipeline does its own redaction downstream.

Right to be forgotten

await Crossdeck.forget();

Calls the backend's /v1/identity/forget endpoint to queue server-side deletion of the customer's events and profile, then wipes all local state — identity, entitlements, queued events, super-properties, groups, breadcrumbs, error context. Idempotent. Server-side failure does not block local wipe — when the user asks to be forgotten, declining to clear their device because the backend hiccupped would be the wrong call.

Configuration reference

Every option accepted by Crossdeck.init(). Required options are bold.

AutoTrackOptions sub-flags

API reference

Every public method on the Crossdeck singleton (and on new CrossdeckClient() instances).

Lifecycle

Identity

Events

Entitlements

Error capture

Privacy & consent

Auto-tracked events reference

Full list above in Events & analytics. Auto-tracked events are gated by the same consent rules as manual ones:

• session.* and page.viewed and element.clicked → consent.analytics.
• webvitals.* → consent.errors.
• error.* → consent.errors.

Diagnostics & debugging

Crossdeck.diagnostics() returns a stable shape regardless of init state — pre-init values are sensible empties. Use it from your DevTools console at any time to verify the SDK is healthy.

{
  started: true,
  anonymousId: "anon_mp10knb…",
  crossdeckCustomerId: "cdcust_xxx",
  developerUserId: "user_847",
  sdkVersion: "1.9.0",
  baseUrl: "https://api.cross-deck.com/v1",
  clock: {
    lastServerTime: 1715414400000,
    lastClientTime: 1715414400003,
    skewMs: 3            // positive = client ahead of server
  },
  entitlements: {
    count: 2,
    lastUpdated: 1715414410000,
    stale: false,         // true once a refresh failed, or data aged past 24h
    listenerErrors: 0     // swallowed throws from buggy subscribers
  },
  events: {
    buffered: 0,
    dropped: 0,
    inFlight: 0,
    lastFlushAt: 1715414411500,
    lastError: null,
    consecutiveFailures: 0,
    nextRetryAt: null     // epoch ms when next retry is scheduled
  }
}

Healthy SDK: started: true, events.consecutiveFailures: 0, events.nextRetryAt: null, clock.skewMs within ±60 seconds. entitlements.stale: true is not a fault on its own — the cache is correctly serving last-known-good — but a persistently stale flag means getEntitlements() has not succeeded in a while, so a recent revoke may not be reflected; check it if a customer's access looks wrong.

Debug-mode console signals

Setting debug: true in init() (or calling setDebugMode(true)) prints a stable vocabulary of signals to console.info. They're suppressed at runtime but available for onboarding integration checks and dashboard verification flows.

AI install prompts

If you're using an AI coding assistant (Cursor, Copilot, Claude Code, Continue) to install Crossdeck, paste the prompt below into the chat. The prompt encodes the SDK's conventions tightly so the AI doesn't guess wrong on the npm scope, the env-prefix rule, or the React hook pattern.

You are helping me install Crossdeck into my React/Next web app. The npm scope is "cross-deck" with a hyphen — NOT "crossdeck".

Configure with:
Package: @cross-deck/web (core SDK)
React subpackage: @cross-deck/web/react (subpath import on the same package — no extra install)
App ID: app_web_xxxxxxxxxxxx
Public SDK Key: cd_pub_test_xxxxxxxxxxxx
Environment: sandbox

Tasks:
1. Run "npm install @cross-deck/web". The React hooks live at the "@cross-deck/web/react" subpath — same package, no separate install. Requires react >= 18.
2. Create or open a top-level Provider component (Next.js: app/providers.tsx as a client component with "use client"; CRA/Vite: a top-level wrapper inside src/main.tsx). The CrossdeckProvider takes a userId prop and handles BOTH Crossdeck.init() and Crossdeck.identify() internally — wrap my tree in <CrossdeckProvider userId={session?.user?.id}> (NextAuth) or <CrossdeckProvider userId={user?.uid}> (Firebase Auth) or my equivalent. Inside, the Provider calls Crossdeck.init({ appId, publicKey, environment }) once on mount, then mirrors the userId prop into Crossdeck.identify(userId) / Crossdeck.reset() as the auth state changes. Do NOT call Crossdeck.start() — that's a deprecated alias.
3. Wire userId from MY actual auth provider — figure out from my code which one it is (NextAuth: useSession().data?.user?.id, Firebase Auth: useAuthState() or onAuthStateChanged user.uid, Supabase: useUser().data?.id, custom backend: whatever my session hook returns). Do NOT hardcode a placeholder string — that aliases every visitor to the same fake user. Pass null/undefined while logged out — the Provider calls Crossdeck.reset() automatically.
4. Do NOT manually track "Page.viewed" or "App.opened" — the SDK's auto-tracker emits page.viewed + session.started/ended automatically. Only track domain-specific events (e.g. Crossdeck.track("paywall_viewed", { variant })). track() is sync, fire-and-forget — never await it.
5. For React entitlement gating, import { useEntitlement } from "@cross-deck/web/react" and use it inside components: const isPro = useEntitlement("pro"); return isPro ? <ProBadge /> : null. The hook subscribes to the SDK's reactive entitlements cache so the component re-renders the moment the cache changes; every subsequent check is a microsecond sync cache hit. SSR-safe. Do NOT call Crossdeck.isEntitled() directly inside JSX render paths — a bare call reads the cache at mount but does not re-render when a later getEntitlements() mutates it, so the component freezes on the mount-time answer. The bare Crossdeck.isEntitled(key): boolean is fine in non-React contexts (vanilla JS, server-side renders, route handlers); it's sync (returns boolean, NOT a Promise — no await).
6. Do NOT expose any secret server keys in the browser bundle — only the publishable key above. Secret keys (cd_sk_…) are server-only.
7. Tell me exactly which files to edit and what the imports should look like, including the "use client" directive on the Provider file (Next.js App Router), where to wrap the tree (app/layout.tsx for App Router, _app.tsx for Pages Router, src/main.tsx for Vite/CRA), and how to source userId from my specific auth provider.

Same shape for the other six frameworks — only the wrapper around Crossdeck.init() / Crossdeck.identify() changes. Vue uses composables from @cross-deck/web/vue with Ref<boolean> returns, Svelte uses a Readable<boolean> store built on onEntitlementsChange, vanilla JS / plain HTML / Node call the core SDK directly.

The fastest way to get the right snippet + an AI prompt for your stack is the framework picker on the dashboard's SDKs page: pick one of nextjs, react, vue, svelte, vanilla-bundler, plain-html, node and you get a snippet pre-filled with your app's key, plus a paste-ready AI prompt tuned to that framework's conventions. Every snippet is locked in by scripts/test-sdk-snippets.mjs (runs node --check on JS, tsc --noEmit on TS/TSX, HTML tag-balance on the CDN snippet, plus must-contain / must-not-contain assertions per framework) so a regression in any of the seven generators fails CI.

Troubleshooting

"Cannot find module @crossdeck/web"

The npm scope is @cross-deck with a hyphen. AI assistants frequently guess wrong. Run npm install @cross-deck/web (note the hyphen).

"Environment mismatch" thrown at init

The key prefix and the environment option disagree. cd_pub_test_… requires environment: "sandbox". cd_pub_live_… requires environment: "production". Reconcile in the Apps page or update the init options.

Events not appearing in the dashboard during local development

The SDK auto-detects localhost and similar dev hostnames, and short-circuits every API call to a no-op. Look for the [crossdeck] Localhost detected — running in dev mode line in your console. Deploy to a real domain (Vercel preview, Netlify branch deploy, custom staging) or use ngrok to test against the real Sandbox.

useEntitlement("pro") always returns false in a React app

You probably haven't called Crossdeck.getEntitlements() after init. The hook reads from the cache; the cache is populated by a server fetch. Add Crossdeck.getEntitlements() inside the same boot useEffect that calls Crossdeck.init().

Errors appearing in Sentry but not in Crossdeck (or vice versa)

Both can run side-by-side without interfering. If only one sees an error: check Crossdeck.consentStatus() in DevTools. If errors: false, Crossdeck is silently dropping the report. Sentry has its own consent / sample-rate config that may differ.

"Failed to fetch" errors are spamming Sentry but Crossdeck is quiet

Working as intended. The Crossdeck SDK has exponential backoff and retries built in — a transient network blip is invisible. Sentry catches the moment of failure with no retry-aware noise filtering. After running both for a week the comparison answers "did Crossdeck's plumbing actually catch what we hoped".

Tab close losing events

Should not happen — the SDK persists the queue to localStorage under crossdeck:queue.v1 on every enqueue, and a terminal flush fires on pagehide / beforeunload / visibilitychange→hidden with keepalive: true. Inspect the localStorage key in DevTools → Application; if events are stuck there across reloads, paste the JSON shape into a support ticket.

Versioning & changelog

The SDK follows semantic versioning. The current version and full release history live in the changelog; the SDK_VERSION constant derives from package.json so the wire header can never drift from the published bundle.

The full changelog ships with every npm tarball at node_modules/@cross-deck/web/CHANGELOG.md.

Related

• Error codes reference — every CrossdeckError code the SDK can throw, with description, resolution, and retryable flag.
• API keys & authentication — publishable vs secret, key rotation, origin allowlists.
• Create a project — the dashboard flow that produces the appId + publishable key you pass to init().
• Connect Stripe — wire your Stripe account so subscription state becomes available via getEntitlements().
• Source on GitHub — the SDK lives under sdks/web/. SDK_TRUTH.md is the canonical contract reference.

Last updated when @cross-deck/[email protected] shipped (May 11, 2026). Future versions are documented in the table above as they publish to npm.