Skip to content

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"

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").

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);
  },
});
  1. Confirm cookie consent has been obtained, if required by your policy.
  2. Confirm the SDK script is loaded (or the npm bundle is ready).
  3. Confirm the widget container is mounted in the DOM.
  4. Call await widget.init(...).
  5. Register event listeners with on(...).

Note

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