Initialization

Initialize the widget in your application after the SDK is loaded and the target container is available in the DOM.

Configuration object

The init() method accepts the following configuration:

Required
- apiKey: string
- container: string | HTMLElement
Optional
- userId?: string
- userName?: string
- metadata?: Metadata
- width?: string
- height?: string
- onReady?: () => void
- onError?: (error: Error) => void
- environment?: "test" | "production"
- storageConsent?: boolean

`storageConsent`

Type	Default	Description
`boolean`	`true`	When `true`, the widget persists the session in cookies (current behavior). Set to `false` for pre-consent memory-only mode: no cookies are written or read, the session lives only in memory, and the visitor starts fresh on every load. Upgrade to persistent mode at runtime with `widget.setStorageConsent(true)`. See Cookie Consent Management.

Metadata

Use metadata to provide structured ecommerce context to Sophi.

Minimum requirements

metadata.profile.userId: string
metadata.profile.isLoggedIn: boolean
metadata.visitedPages: Array<{ url: string; timestamp: string }>

Each timestamp value must use ISO-8601 format (for example, "2026-04-01T10:46:10Z").

Recommended shape

type Metadata = {
  profile: {
    userId: string;
    isLoggedIn: boolean;
    email?: string;
    firstName?: string;
    lastName?: string;
    locale?: string;
    country?: string;
    currency?: string;
    attributes?: Record<string, string | number | boolean | null>;
  };
  visitedPages: Array<{
    url: string;
    timestamp: string;
    type?: string;
    productId?: string;
    title?: string;
    attributes?: Record<string, string | number | boolean | null>;
  }>;
};

visitedPages[*].type is intentionally free-form so integrators can map their own page taxonomy.

Example

const widget = new window.SophiWebSDK.SophiWidget();

await widget.init({
  apiKey: "YOUR_SOPHI_API_KEY",
  container: "#sophi-widget-container",
  userId: "user-123",
  userName: "Jane Doe",
  environment: "production",
  width: "100%",
  height: "600px",
  metadata: {
    profile: {
      userId: "user-123",
      isLoggedIn: true,
      email: "jane@example.com",
      firstName: "Jane",
      lastName: "Doe",
      locale: "en-US",
      country: "US",
      currency: "USD",
    },
    visitedPages: [
      {
        url: "/women/shoes",
        timestamp: "2026-04-01T10:45:00Z",
        type: "category",
        attributes: {
          categoryId: "cat-women-shoes",
        },
      },
      {
        url: "/product/nike-air-max-001",
        timestamp: "2026-04-01T10:46:10Z",
        type: "pdp",
        attributes: {
          productId: "sku-001",
        },
      },
    ],
  },
  onReady: () => {
    console.log("Sophi widget ready");
  },
  onError: (error) => {
    console.error("Sophi widget init error", error);
  },
});

Recommended flow

Confirm cookie consent has been obtained, if required by your policy.
Confirm the SDK script is loaded (or the npm bundle is ready).
Confirm the widget container is mounted in the DOM.
Call await widget.init(...).
Register event listeners with on(...).

If you want the assistant to be available before consent, initialize with storageConsent: false and upgrade on consent at runtime.

Store apiKey in your application configuration layer. Do not hardcode production secrets in publicly shared examples.

Run without waiting for consent

To make the assistant available before the visitor accepts cookies, initialize with storageConsent: false and call widget.setStorageConsent(true) when consent is granted. See Cookie Consent Management.