Compass Web SDK: Distribution & FAQ

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, immutable, and cacheable.

Hosted bundle (`<script>`)

The bundle is served from a CDN on a versioned, cacheable URL:

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

…/arc-rec/v1/… is the major-pinned URL. Embed this: you receive backwards-compatible fixes automatically. It is served with a short cache TTL.
…/arc-rec/v1.4.2/… is an exact-version, immutable URL (cached forever, never overwritten). Use it if you need byte-for-byte stability.

Recommended embed (SRI-hardened)

Pin the bundle’s integrity so a tampered file is rejected by the browser:

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

The sha384-… value for each release is published in the manifest:

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

manifest.json lists every artifact with its bytes, sha256, and integrity (the sha384- SRI string), plus the recommended embedPath and embedIntegrity.

npm package (ESM)

Package-managed consumers install from the public npm registry:

npm install @arcxp/compass-sdk

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

The package follows semantic versioning; pin a major range (^1) to get fixes. npm-managed consumers can also load the bundle over a public CDN that fronts npm (no separate infrastructure), e.g. https://cdn.jsdelivr.net/npm/@arcxp/compass-sdk@1/dist/compass-sdk.iife.min.js — a convenient fallback, though the self-hosted URL above 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; the major-pinned URL (/arc-rec/v<major>/) and the npm major range are the supported handles.
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.

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 as patches ship
`arc-rec/manifest.json`	`public, max-age=300, must-revalidate`	Updated each release

On each release the CDN invalidates only the mutable paths (/arc-rec/v<major>/* and /arc-rec/manifest.json); immutable version directories are never invalidated.

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.