Integration guide

How to deliver @usesophi/sophi-web-object to your storefront — choose between GTM, npm/bundler, or CDN script tag depending on your stack.

Choose how you deliver @usesophi/sophi-web-object. For Google Tag Manager, the detailed walkthrough is on a dedicated page so it is easy to find: GTM integration.

Chat widget

To load the Sophi assistant widget (SophiWidget, @usesophi/sophi-web-sdk) from GTM, use SDK GTM integration, not this package.

Choose an integration method

Method	Best when	Upgrade story
GTM	Marketing owns tag publishing; consent-gated load; you want one place to bump the script URL	Pin SDK version in a GTM Constant variable; change it + publish container
Script tag	Full control in your HTML templates; no GTM	Change the `src` URL (or your CMS snippet) and deploy
npm / ESM	Bundled app; type-aware codebase; tree-shaking not required for this global SDK	Bump dependency in `package.json` and release your app

All methods expose window.sophi_object and, after bootstrap, window.SophiTracker (see SophiTracker API).

Script tag

Define window.sophi_object with at least config.apiKey, then load the script after that block (or ensure config exists before the tracker runs).

<script>
  window.sophi_object = {
    config: {
      apiKey: 'YOUR_API_KEY'
    },
    page: {
      type: 'Home',
      url: 'https://example.com/'
    }
  };
</script>
<script src="https://cdn.jsdelivr.net/npm/@usesophi/sophi-web-object@latest/dist/sophi.min.js" async></script>

async is supported: the SDK waits for DOMContentLoaded (or runs immediately if the document is already loaded) before bootstrapping.

CDN URLs and build artifacts are listed on Installation.

npm / ESM

npm install @usesophi/sophi-web-object

ES module import is hoisted, so assign window.sophi_object first, then load the SDK with dynamic import (or a small separate entry file that runs before your main bundle):

window.sophi_object = {
  config: { apiKey: 'YOUR_API_KEY' },
};

await import('@usesophi/sophi-web-object/dist/sophi.esm.js');
// After bootstrap: window.SophiTracker and window.sophi_object

Alternatively, set window.sophi_object in an inline <script> before your bundled app, or use the script tag / GTM approaches.

Best practices

Pin versions in production — Use an exact semver in URLs or package.json, not @latest, so releases do not change behaviour unexpectedly.
Consent — Load the tracker and populate PII only when your policy allows (see Configuration and Types for UserObject).
SPAs — After route or context changes, update via SophiTracker.push() or assignments; see SophiTracker API and Integration patterns.
Config and apiKey — The SDK may strip apiKey from the public object after startup; avoid rewriting it on every render if your integration relies on that behaviour (see Configuration).

Events cheat sheet

When you assign to watched keys without overriding event_type, defaults are:

Key	Default `event_type`
`page`	`page_view`
`user`	`identify`
`product`	`product_view`
`basket`	`basket_view`
`listing`	`listing_view`
`transaction`	`purchase`

For add_to_cart, remove_from_cart, and checkout_started, set event_type explicitly (usually via SophiTracker.push). Details: Event types.

Next steps

GTM integration
Installation — CDN table and artifacts
Window object layer
Integration patterns — cart, checkout, login examples