Install the JavaScript SDK

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

yarn add @spotzee/js-sdk

pnpm add @spotzee/js-sdk

<script src="https://unpkg.com/@spotzee/js-sdk/lib/esm/index.js"></script>

The package ships dual CJS + ESM builds. Static types ship with the package.

Pick a class

Class	Runtime	Identity handling
`Client`	Node, edge runtimes, server jobs	You pass `anonymousId` and / or `externalId` on every call
`BrowserClient`	Web browsers (modern bundlers)	Mints an anonymous ID on first use, caches `externalId` after `identify`
`Spotzee`	Browser 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 })

import { BrowserClient } from '@spotzee/js-sdk'

const spotzee = new BrowserClient({ apiKey: 'pk_…' })

<script src="https://unpkg.com/@spotzee/js-sdk/lib/esm/index.js"></script>
<script>
  Spotzee.initialize({ apiKey: 'pk_…' })
</script>

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.

Header	Value	Why
`Authorization`	`Bearer <your apiKey>`	Authenticates the request
`Spotzee-Version`	`2026-04-28`	Pins the API version this SDK release targets
`x-spotzee-client-type`	`sdk-js`	Helps the platform attribute traffic by client type. Read Identify your API client type
`Content-Type`	`application/json`	Set 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.

Get started

Build

Configure

Integrate

Tools

SDKs

API conventions

Recipes

Releases

Install the JavaScript SDK

Install

Pick a class

Initialise

What every request carries

Errors

Debugging

Next steps

Identify users

Track events

Devices and notifications

Typed API client

​Install

​Pick a class

​Initialise

​What every request carries

​Errors

​Debugging

​Next steps

Identify users

Track events

Devices and notifications

Typed API client

Install

Pick a class

Initialise

What every request carries

Errors

Debugging

Next steps