Frontend IntegrationWeb ObjectSophiTracker API

SophiTracker API

After the bundle loads, window.SophiTracker exposes the public imperative API for SPAs, batched updates, login/logout events, and multi-object pushes such as add_to_cart.

After the bundle loads, window.SophiTracker exposes the public imperative API. Use it for SPAs, batched updates, login/logout, and multi-object events (e.g. add_to_cart with both product and basket).

SophiTracker.push(partial)

SophiTracker.push(
  partial: Partial<Omit<SophiObjectShape, 'config'>>
): void
  • Merges every key in partial into window.sophi_object.
  • Processes the update once per watched key present in partial (page, user, product, basket, listing, transaction), which may produce one event per key.
  • Exception — purchase: when transaction is present, page is treated as envelope context only. The SDK emits a single purchase event and does not also emit page_view. page may come from the same push or from leftover sophi_object.page; if page is missing entirely, purchase is skipped with a console warning.
  • If partial.event_type is set, it overrides the default event_type for all triggers in that single push call.
  • If called before the SDK is ready (before or during bootstrap), the call is buffered and replayed in FIFO order once initialisation completes — provided the official pre-load stub is installed.
  • If called after a fatal bootstrap failure (missing apiKey, session error), the call is discarded with a console warning.

You do not need to check whether window.SophiTracker is ready before calling push() — the official pre-load stub and internal buffer handle timing automatically. See Integration guide for the required inline snippet.

Typical use: route changes, add-to-cart, or syncing several objects atomically.

SophiTracker.updateUser(userId)

SophiTracker.updateUser(userId: string | undefined): void
  • Clears the current session (cookies and local session state).
  • Sets config.userId to the new value (or clears it when undefined / empty).
  • Establishes a new session with Sophi so subsequent events use fresh credentials.

Call after your auth layer confirms login (pass stable external id) or logout (pass undefined for an anonymous session).

SophiTracker.setConsent(granted)

SophiTracker.setConsent(granted: boolean): void

Grants or withdraws storage consent at runtime. Use it together with config.storageConsent: false to run the Web Object in Cookie Consent Management.

  • setConsent(true) — activates the previously passive Web Object: it creates a session, writes cookies, and starts sending events (including the current sophi_object snapshot). Any push() calls made while activation is in progress are buffered and drained after the session is ready.
  • setConsent(false) — makes it passive again and clears the session cookies.
// Visitor accepted cookies in your consent banner
window.SophiTracker.setConsent(true);

Until setConsent(true) is called (or config.storageConsent is true), the Web Object sends no events. Pre-load buffered push() calls are discarded at bootstrap when consent is denied — they are not replayed when setConsent(true) is later called. Events begin flowing from the sophi_object snapshot at the time consent is granted.

SophiTracker.getSession()

SophiTracker.getSession(): Promise<SophiSession>

Returns a promise for the SDK’s active session object. Intended for debugging or advanced integrations; normal storefront tracking does not require calling this.

The window.sophi_object layer

The global window.sophi_object follows the SophiObjectShape — a config block, an optional event-type override, and optional context objects (page, user, product, basket, listing, transaction) that trigger event collection when assigned.

Event types

Events sent to the backend use ExternalEventType on the envelope. Values are lowercase snake-case strings.

On this page

SophiTracker.push(partial)SophiTracker.updateUser(userId)SophiTracker.setConsent(granted)SophiTracker.getSession()Related