Skip to content

Installation

The npm package name is @usesophi/sophi-web-object. Published artifacts live under dist/ in the package.

File Use case
sophi.min.js Production: <script src="..."> or GTM Custom HTML
sophi.js Debugging (source maps, readable bundle)
sophi.esm.js Bundlers / import

The package is publicly available on the jsDelivr CDN:

URL Resolves to
https://cdn.jsdelivr.net/npm/@usesophi/sophi-web-object@latest/dist/sophi.min.js Latest published version
https://cdn.jsdelivr.net/npm/@usesophi/sophi-web-object@0.1.0/dist/sophi.min.js Pinned version (example)

Version pinning

@latest always tracks the newest release, which is convenient during development. For production, pin to a specific version (e.g. @0.1.0) so your integration is not affected by future breaking changes.

Script tag

Load the script after inline code that defines window.sophi_object with at least config.apiKey, 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.

npm / ESM

npm install @usesophi/sophi-web-object

import '@usesophi/sophi-web-object/dist/sophi.esm.js';
// window.SophiTracker and window.sophi_object are available after bootstrap

Ensure window.sophi_object.config is set before the module executes, or set it in your app entry before importing.

Google Tag Manager

GTM supports two loading strategies — choose one per tag.

  1. Create a Custom HTML tag.

  2. Add a <script src="..."> pointing at the jsDelivr URL:

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

  3. Trigger on Consent Granted (or your policy equivalent), then All Pages if appropriate.

Note

For production GTM deployments, replace @latest with a pinned version such as @0.1.0 so a new release cannot silently change tracking behaviour after you publish the container.

Option B — inline the bundle

  1. Create a Custom HTML tag.
  2. Paste the full contents of sophi.min.js directly into the tag body, then prepend the window.sophi_object config block.
  3. Trigger identically to Option A.

Inlining avoids an extra network round-trip and ensures the tracker fires even if the CDN is temporarily unreachable, at the cost of a larger GTM container payload.

Define window.sophi_object in a tag that fires before the tracker tag (e.g. a prior Custom HTML or a data layer variable mapped in a tag template). For consent-sensitive fields, see Configuration and Types reference (UserObject / PII gating).

Next steps