Skip to content

Installation

Install the SDK from npm:

npm install @usesophi/sophi-web-sdk

Package reference:

Import and create widget

import { SophiWidget } from "@usesophi/sophi-web-sdk";

const widget = new SophiWidget();

Initialize

await widget.init({
  apiKey: "YOUR_SOPHI_API_KEY",
  container: "#sophi-widget-container",
  userId,
  userName,
  environment: "production",
  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",
      },
      {
        url: "/product/nike-air-max-001",
        timestamp: "2026-04-01T10:46:10Z",
        type: "pdp",
        attributes: {
          productId: "sku-001",
        },
      },
    ],
  },
});

Minimum metadata requirements:

  • metadata.profile.userId
  • metadata.profile.isLoggedIn
  • metadata.visitedPages[] with url and ISO-8601 timestamp on each item

visitedPages[*].type is optional and intentionally free-form.

Note

If your project loads the SDK through Google Tag Manager (GTM) instead of npm, see GTM Integration.