Sophi Web Object (@usesophi/sophi-web-object)

The Sophi Web Object package is a framework-agnostic browser SDK that tracks e-commerce behaviour and sends structured events to the Sophi event API. It is separate from the Sophi Web SDK, which embeds the conversational assistant widget (SophiWidget).

Package	Purpose
@usesophi/sophi-web-object	Data layer on window.sophi_object, automatic sends when tracked fields change, and window.SophiTracker for SPAs
@usesophi/sophi-web-sdk	Widget UI, commerce events from the assistant, runtime methods on SophiWidget

Use Web Object when you need server-style tracking (page, product, basket, purchase, etc.) without depending on the widget bundle.

How it works (high level)

1. You define window.sophi_object with a config block (at minimum apiKey) and optional context objects before the script runs, or you update them after load via assignments or SophiTracker.push().
2. On DOMContentLoaded, the SDK starts: validates config, creates or restores a client session (cookies and server handshake), then watches window.sophi_object for changes to tracked fields.
3. Assignments to tracked keys (page, user, product, basket, listing, transaction) build event payloads and add them to an outbound queue.
4. The queue debounces sends (default 300 ms), retries on failure, and tries to flush remaining items when the visitor leaves the page.

Events are delivered to Sophi over HTTPS (see Configuration for the options you control).

Documentation map

• Installation

Script tag, npm ESM, and GTM patterns.

• Configuration

SophiConfig, defaults, session cookies.

• The window.sophi_object layer

Watched keys, event_type overrides, shape of the data layer.

• SophiTracker API

push, updateUser, getSession.

• Event types

ExternalEventType, defaults per key, required context.

• Types reference

PageObject, UserObject, commerce objects, EventEnvelope.

• Data and auth flows

From data-layer updates to HTTPS delivery and session lifecycle.

• Validation

Client-side rules and field conventions.

• Integration patterns

Static pages, SPA navigation, cart, checkout, login.

Builds

The package publishes:

Artifact	Format
dist/sophi.js	IIFE (window.SophiTracker)
dist/sophi.min.js	Minified IIFE
dist/sophi.esm.js	ES module

See Installation for how to load each variant.