Snippet API Overview

The `window.zenstep` object

After the Zenstep snippet loads, it exposes a global window.zenstep API. The snippet initialises synchronously by installing a pre-init queue, so you can call any method before the script has fully loaded — calls are queued and replayed on init.

interface ZenstepAPI {
  identify: (userId: string, attributes?: UserAttributes) => void;
  track: (event: string, data?: Record<string, unknown>) => void;
  _q: Array<["identify" | "track", unknown[]]>;
}

interface UserAttributes {
  [key: string]: string | number | boolean | undefined;
}

Queue behaviour

The snippet uses the GA4 dataLayer pattern. Before the snippet bundle has evaluated, window.zenstep is a stub that captures calls:

// This is safe to call at any point in your page lifecycle
window.zenstep?.identify("user_123");
window.zenstep?.track("onboarding_started");

When the bundle evaluates, it drains the queue in order — your calls are not lost.

Methods

Method	Description
`identify()`	Associate the current browser session with a known user ID and optional traits
`track()`	Send a custom behavioural event for use in targeting rules

Calling conventions

All methods are fire-and-forget — they do not return a Promise. Errors are caught internally and logged as warnings to the browser console. Your code will never throw due to a Zenstep API call.

// No await needed
window.zenstep?.identify("user_123", { plan: "grow" });

// Optional chaining (?.) prevents errors if snippet fails to load
window.zenstep?.track("feature_used", { feature: "csv_export" });

Identity state

Zenstep persists identity state in localStorage under the key zenstep_identity. The identity survives page reloads but is cleared when the user clears their browser data or you call identify() with a new user ID. An anonymous ID (zenstep_anonymous_id) is created on first load and persists across page reloads before identify() is called. This allows Zenstep to track behaviour and show flows to unauthenticated users.

​The window.zenstep object

​Queue behaviour

​Methods

​Calling conventions

​Identity state

The `window.zenstep` object

Queue behaviour

Methods

Calling conventions

Identity state