# Compass Web SDK: Distribution & FAQ

Source: https://dev.arcxp.com/content-recommendations/sdk/distribution/

How the Compass Web SDK is distributed — hosted script bundle, npm package, self-hosting, SRI, versioning, and caching — plus frequently asked questions.

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:

```html
<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`.

> **Note:**
>
> Because the `v1` alias moves as patches ship, pin SRI against an **exact-version** URL if you want the `integrity` value to stay valid across your own deploys. The loader snippet in the [Integration Guide](https://dev.arcxp.com/content-recommendations/sdk/integration-guide/)uses the plain (non-SRI) form for brevity; the SRI-hardened tag above is the recommended production embed.

## npm package (ESM)

Package-managed consumers install from the public npm registry:

Terminal window

```bash
npm install @arcxp/compass-sdk
```

```js
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.
- **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 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](https://dev.arcxp.com/content-recommendations/sdk/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](https://dev.arcxp.com/content-recommendations/sdk/integration-guide/#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.

## See also

- [Compass Web SDK: Integration Guide](https://dev.arcxp.com/content-recommendations/sdk/integration-guide/)
- [Compass Web SDK: Events & Reliability](https://dev.arcxp.com/content-recommendations/sdk/events-reliability/)