Skip to content

Configuration

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

SophiConfig

Field Required Default Description
apiKey Yes — API key issued for your Sophi tenant; required to open a browser session
userId No — External user id from your auth system; used in session creation and guest→logged-in merge
maxRetries No 3 Retries per event after failed send
debounceMs No 300 Milliseconds to wait before sending batched events after an update
debug No false When true, internal log() output goes to the console

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
  }
};

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-token Short-lived credential used when delivering events
client-id Stable visitor identifier managed by Sophi
external-user-id Copy 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.