Compass Web SDK: Distribution & FAQ

Last updatedOct 16, 2026View as Markdown

The Compass Web SDK ships on two channels: a hosted <script> bundle (IIFE) for snippet embedding, and an npm package (ESM) for build-pipeline consumers (React / Next). Both are versioned and cacheable, and every published version is immutable.

We recommend one of two integrations. Both let you decide when to adopt a new version:

The exact-version script URL with Subresource Integrity (SRI).
The npm package with a committed lockfile.

Hosted bundle (`<script>`)

Each version is served from a CDN on its own exact-version URL. The URL is immutable: it is cached forever and never overwritten, so its bytes never change.

https://arc-rec.app-recommend.aws.arc.pub/arc-rec/v1.1.1/compass-sdk.iife.min.js

Recommended embed (SRI-hardened)

Load an exact-version URL with its integrity hash, so the browser rejects a tampered file:

<script
  src="https://arc-rec.app-recommend.aws.arc.pub/arc-rec/v1.1.1/compass-sdk.iife.min.js"
  integrity="sha384-ISFjYTqROCK5CLja+zupnWEfyWerhFhGnuvnj+4uV8wJW7SQB8bAXcKxnsh6rU/u"
  crossorigin="anonymous"
  async
></script>

crossorigin="anonymous" is required: browsers check integrity on a cross-origin script only in CORS mode. To adopt a new version, update both the version in the URL and the integrity value.

The current version and its hash are published in the manifest:

https://arc-rec.app-recommend.aws.arc.pub/arc-rec/manifest.json

manifest.json lists the latest version’s artifacts with their bytes, sha256, and integrity (the sha384- SRI string). Its version is the latest version, and the iife artifact’s path and integrity are the values for the recommended embed.

Auto-update URL (optional)

If you want new backwards-compatible versions without changing your page, you can load the major-version alias instead:

<script
  src="https://arc-rec.app-recommend.aws.arc.pub/arc-rec/v1/compass-sdk.iife.min.js"
  async
></script>

The v1 alias serves a version that Arc XP has promoted within major version 1. Publishing a new version doesn’t move it; Arc XP moves it deliberately, so it can lag behind the latest version. It is served with a short cache TTL.

npm package (ESM)

Package-managed consumers install from the public npm registry:

npm install @arcxp/compass-sdk

import { ArcCompassClient } from "@arcxp/compass-sdk";

Commit your lockfile (package-lock.json, pnpm-lock.yaml, or yarn.lock) so each build installs the version you tested. The package follows semantic versioning, and a major range such as ^1 picks up compatible fixes when you update your lockfile. Stable versions publish to the latest tag. Prereleases publish to the next tag, so npm install @arcxp/compass-sdk never installs a prerelease.

npm-managed consumers can also load the bundle from a public CDN that fronts npm, for example https://cdn.jsdelivr.net/npm/@arcxp/compass-sdk@1.1.1/dist/compass-sdk.iife.min.js. It is a convenient fallback, but the Arc XP-hosted URL is the supported primary.

Self-hosting the bundle

Customers who cannot reference the hosted URL (strict CSP, air-gapped build, policy requiring first-party assets) can self-host: take dist/compass-sdk.iife.min.js from the npm package (or the release manifest) and serve it from your own origin. Serve it with a long Cache-Control on a versioned path and, if loading cross-origin, the appropriate CORS headers. You own updates when you self-host — re-pull on each SDK release.

Versioning and deprecation policy

Semantic versioning. Breaking changes bump the major version. An exact-version URL (/arc-rec/v<version>/) or a locked npm version gives you the version you chose; the major-version alias (/arc-rec/v<major>/) and an npm major range follow compatible updates.
Deprecation window. A superseded major is supported for at least 90 days before its alias URL is sunset. Exact-version URLs are immutable and remain reachable even after an alias is retired.
Changelog. Every release is recorded in the SDK’s CHANGELOG.md, published with the @arcxp/compass-sdk npm package.

Caching

Path	`Cache-Control`	Notes
`arc-rec/v<version>/…`	`public, max-age=31536000, immutable`	Cache forever; never rewritten
`arc-rec/v<major>/…`	`public, max-age=300, must-revalidate`	Moves only when promoted
`arc-rec/manifest.json`	`public, max-age=300, must-revalidate`	Updated each release

On each release the CDN invalidates only /arc-rec/manifest.json; immutable version directories are never invalidated. When the alias is promoted, the CDN invalidates /arc-rec/v<major>/*.

FAQ

Why is `event_value` not type-checked against `eventType`?

The collector accepts event_value for any event type; only some types (notably video_progress) populate it in practice. Tight typing would have to change every time a new event type is added. A future refinement could discriminate the track() overload by event type.

Why don’t you parse TCF / GPP strings?

Vendor-specific consent strings are large and evolving. Forcing the SDK to parse them couples it to a TCF/GPP version and balloons the bundle. The single collect-for-personalization gate (setConsent(true | false)) is small enough that hosts can map any CMP onto it in a few lines.

Why no automatic retry across page loads?

Retry-with-backoff in the browser is mostly useless: the user navigates away long before the third attempt fires. Persistent retry across page loads (via localStorage / IndexedDB) raises consent and correctness problems — replayed events would carry stale identity / consent context. The SDK does retry transient failures within a page (see Events & Reliability).

Why is the `item_id` for `search` events synthetic?

The collector requires an item_id on every event, and a search has no natural item. Pass a synthetic ID such as { itemId: "search:" + query }.

Will events sent before consent be replayed if I never call `setConsent`?

No. They sit in the in-memory queue until the queue cap is reached, at which point oldest-first eviction kicks in. The SDK never assumes consent — setConsent must be called explicitly.

How do I see what the SDK is doing?

Pass debug: true to ArcCompass.init() for lifecycle and transport diagnostics on the console. For terminal batch drops in production, wire the onError callback (see Error visibility).

What about server-side rendering?

The SDK is browser-only. The IIFE bundle is safe to include in an SSR page — it no-ops on import when window is undefined.