Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.spotzee.com/llms.txt

Use this file to discover all available pages before exploring further.

The JavaScript SDK ships three classes for three runtimes. Pick the one that matches where your code runs, install with your usual package manager, and initialise once with a publishable key.

​
Install

npm install @spotzee/js-sdk
The package ships dual CJS + ESM builds. Static types ship with the package.

​
Pick a class

ClassRuntimeIdentity handling
ClientNode, edge runtimes, server jobsYou pass anonymousId and / or externalId on every call
BrowserClientWeb browsers (modern bundlers)Mints an anonymous ID on first use, caches externalId after identify
SpotzeeBrowser script tag (window.Spotzee)Static singleton wrapper around BrowserClient

​
Initialise

The SDK needs a publishable API key. Read Manage API keys for how to create one. Use pk_… keys for client builds (browsers, mobile, anywhere the key is visible to end users). Server-side jobs that already have a backend can use either a publishable key for SDK flows or a secret key (sk_…) for the typed client. 
import { Client } from '@spotzee/js-sdk'

const spotzee = new Client({ apiKey: process.env.SPOTZEE_API_KEY })
The browser variants persist the anonymous ID for the duration of the page session. To carry an anonymous ID across page loads, pass it explicitly into track / identify from your own storage.

​
What every request carries

Every call the SDK makes adds these headers automatically. You don’t need to set them yourself.
HeaderValueWhy
AuthorizationBearer <your apiKey>Authenticates the request
Spotzee-Version2026-04-28Pins the API version this SDK release targets
x-spotzee-client-typesdk-jsHelps the platform attribute traffic by client type. Read Identify your API client type
Content-Typeapplication/jsonSet on POST and PUT requests
The SDK also converts JavaScript camelCase property names to snake_case before sending, so calling identify({ externalId: 'u_42', timezone: 'Australia/Sydney' }) puts external_id and timezone on the wire.

​
Errors

Failed requests throw an Error whose message includes the HTTP status, the API error code (when present), the human-readable message, and the request_id for support. The SDK parses the RFC 7807 envelope on 2026-04-28 and falls back to the legacy { error: string } shape across the cutover. 
try {
  await spotzee.track({ event: 'Signed up', properties: { plan: 'starter' } })
} catch (err) {
  console.error('Spotzee track failed:', err)
  // → "API Error HTTP 401 | code=auth_invalid_key | invalid API key | request_id=req_abc123"
}
Quote the request_id when contacting support so the team can find the request in the platform logs.

​
Debugging

The SDK doesn’t ship a debug toggle. Use your runtime’s standard tools.
  • Node. Set NODE_DEBUG=http,https to see outbound requests, or wrap the SDK call in a logging block. The SDK’s thrown error already contains everything support needs.
  • Browser. Use the network panel of your browser’s developer tools to inspect the request and response payloads. Filter by apix.spotzee.com to isolate Spotzee traffic.

​
Next steps

Identify users

Link anonymous activity to a known user, set traits, and alias on sign-up.

Track events

Send custom events with properties to trigger journeys and segment users.

Devices and notifications

Register browser or web push tokens, fetch in-app notifications.

Typed API client

The full OpenAPI surface for server-side and agentic use.