Frontend IntegrationWeb ObjectConfiguration

Configuration

All runtime settings for the Sophi Web Object, provided via window.sophi_object.config including apiKey, userId, maxRetries, debounceMs, debug, and storageConsent.

All runtime settings are provided under window.sophi_object.config. The SDK reads this object when it starts.

SophiConfig

FieldRequiredDefaultDescription
apiKeyYes—API key issued for your Sophi tenant; required to open a browser session
userIdNo—External user id from your auth system; used in session creation and guest→logged-in merge
maxRetriesNo3Retries per event after failed send
debounceMsNo300Milliseconds to wait before sending batched events after an update
debugNofalseWhen true, internal log() output goes to the console
storageConsentNotrueWhen false, the Web Object loads passively: no session, no cookies, and no events are sent until consent is granted. See Cookie Consent Management.

If apiKey is missing, startup stops with a warning and no tracking runs.

Example

window.sophi_object = {
  config: {
    apiKey: 'YOUR_API_KEY',
    userId: 'usr-123',
    maxRetries: 3,
    debounceMs: 300,
    debug: false
  }
};

When storageConsent is false, the Web Object stays completely passive:

  • No session is created and no cookies are written.
  • SophiTracker.push(...) calls are dropped — no events reach the backend.
  • Only window.SophiTracker is exposed so you can activate it later.

Call SophiTracker.setConsent(true) once the visitor grants consent to start a session, write cookies, and begin sending events (including the current sophi_object snapshot). See Cookie Consent Management.

Session and cookies

After your configuration is valid, the SDK establishes or restores an authenticated browser session with Sophi over HTTPS and receives credentials it can use when sending events. Those credentials are stored in first-party cookies (30-day lifetime, path=/, SameSite=Lax).

Cookie names are namespaced by API key:

Suffix (after sophi-{apiKey}-)Content
access-tokenShort-lived credential used when delivering events
client-idStable visitor identifier managed by Sophi
external-user-idCopy of config.userId from when the session was created (used when linking guest and logged-in activity)

When a shopper was anonymous and later logs in, the SDK may ask Sophi to associate the existing anonymous profile with the user id you provide in config.userId, so continuity is preserved without you managing that protocol yourself.

To reset session state (e.g. logout), use SophiTracker.updateUser or the underlying session clear behaviour described there.

Debug logging

With debug: true, the SDK prints diagnostic messages via its internal logger (implementation-defined prefix). Disable in production to avoid noise and accidental disclosure of state.

Installation

The npm package is @usesophi/sophi-web-object. Artifacts live under dist/ in the package.

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.

On this page

SophiConfigExamplePre-consent passive mode (no consent)Session and cookiesDebug loggingRelated