@arcxp/compass-sdk

ArcCompass client-side SDK for the user-events collector. Distributed as a single bundled JS file for <script> inclusion; also published as an ESM module for npm consumers (npm install @arcxp/compass-sdk). See Distribution for the versioned URL scheme, the SRI-hardened embed, and the self-host fallback.

Quickstart

Paste the snippet, then call init() once and track() for each event. The item an event refers to comes from the <meta name="arc-compass:item-id"> tag or a per-call itemId; multi-site tenants can add the optional <meta name="arc-compass:site-id"> tag (or a per-call siteId) to attribute events to a Site. page_view is captured automatically on load and SPA route changes (disable with autoPageView: false).

<script>
  (function (w, d) {
    w.ArcCompass = w.ArcCompass || { q: [] };
    ["init", "setConsent", "setUserId", "track", "flush"].forEach(function (m) {
      w.ArcCompass[m] = w.ArcCompass[m] || function () { w.ArcCompass.q.push([m, [].slice.call(arguments)]); };
    });
    var s = d.createElement("script");
    s.async = true;
    s.src = "https://arc-rec.app-recommend.aws.arc.pub/arc-rec/v1/compass-sdk.iife.min.js";
    d.head.appendChild(s);
  })(window, document);

  window.ArcCompass.init({
    // Events ASI base path for your org. The SDK appends `/events/batch`.
    domain: "https://<org-id>-config-prod.api.arc-cdn.net/collect-web/v1",
    apiKey: "<arc-delivery-token>",
  });
  // Single collect-for-personalization gate: pass true once the host's CMP
  // reports consent. Nothing is sent or persisted until then.
  window.ArcCompass.setConsent(true);
  window.ArcCompass.track("page_view");

Documentation

• Getting started
• Configuration
• Consent
• Identity & sessions
• Events
• Reliability
• Distribution
• FAQ
• Generated API reference: run pnpm run docs, then open docs/api/index.html.

Development

pnpm install
pnpm run lint       # ESLint
pnpm run typecheck  # tsc --noEmit
pnpm run test       # Vitest unit tests with coverage
pnpm run test:e2e   # Playwright browser tests
pnpm run build      # tsup → dist/
pnpm run size       # gzipped-size check
pnpm run verify     # all of the above

License

Internal — Arc XP / The Washington Post.