Compass Prerequisites & Enablement

This page tells you the prerequisites that must be satisfied for Compass to operate on your site, and how each one gets put in place. It does not cover how to implement them in the browser — token usage, the loader snippet, init(), consent wiring, and meta-tag syntax all live in the Compass Web SDK: Integration Guide, which is the canonical setup reference. (The SDK-rendered Experiences’ own lifecycle events are documented on their component pages, not there.) Read this page first to scope the work and file the right requests; follow the Integration Guide when you sit down to build.

Note

For a phase-by-phase rollout plan once the prerequisites below are met — catalog loading, shadow-deploy, launch, and post-launch health checks — see the Content Recommendations Onboarding Checklist.

How enablement works

Compass is enabled for your organization by Arc XP. There is no self-serve “turn on Compass” toggle in an admin console: your Technical Account Manager (TAM) coordinates provisioning through a support request, and Arc stands up the per-organization resources on your behalf.

Practically, that means enablement starts with a conversation, not a code change. Before integration begins you will:

1. Ask your TAM (or open a request through the Arc XP Support Center) to enable Compass for your organization.
2. Confirm a few provisioning inputs Arc needs from you — see What Arc needs from you below.
3. Wait for Arc to confirm your organization is provisioned. Provisioning is an Arc-side operation; you do not run it yourself.

Caution

Site management is coordinated through your TAM — there is no self-serve. Enabling Compass, choosing which sites it serves, adding a site to a live tenant, and changing your data-residency region are all Arc-coordinated operations requested through your TAM or the Support Center. Plan for coordination lead time rather than an instant self-service change.

What Arc needs from you

To provision your organization, Arc needs a small set of inputs. Have these ready when you open the request:

Input	Why Arc needs it
The site(s) Compass should serve	Multi-site organizations serve a distinct catalog per site. Arc records the site set your tenant is configured for; adding sites later is a TAM-coordinated change.
Your data-residency region (US or EU)	Compass runs your organization’s backend in a single region. This is chosen once, at provisioning.
Your website origin(s) — exact scheme://host[:port] strings	The browser-facing Compass endpoints only accept cross-origin requests from origins you register. A page served from an unregistered origin is refused by the browser. Supply every origin your site is served from.

Your TAM will also confirm your Arc XP organization is on a supported Delivery version. If it is not, that upgrade is a prerequisite and is handled by Arc before Compass can be provisioned.

The prerequisites

Five things must be in place before Compass can operate. The first three are established during provisioning and content onboarding; the last two are properties your pages must carry at runtime.

#	Prerequisite	Who establishes it	Implement with
1	A provisioned Compass entitlement	Arc XP (TAM-coordinated)	This page
2	A delivery credential (API token)	You, via the Delivery API	Provisioning tokens · SDK Setup
3	Content sync (catalog ingestion)	You + Arc (see below)	Backfilling & Forwarding · End-to-end setup
4	Reader identity available on the page	You	Consent & Identity
5	Page/site identity available on the page	You	SDK Setup

1. A provisioned Compass entitlement

Your organization must be provisioned for Compass before anything else works. This is the entitlement Arc establishes when your TAM’s request is fulfilled: it stands up your organization’s recommendation backend, records the site set Compass will serve, and opens the browser-facing endpoints for the origins you supplied.

You cannot self-provision this, and integration code written against an un-provisioned organization will be rejected at the edge. Treat “Arc has confirmed the organization is provisioned” as the gate that unblocks everything below.

2. A delivery credential

Compass authenticates browser traffic with an Arc XP delivery token. You provision this yourself through the Delivery API — see Provisioning tokens through the Delivery API.

Delivery credentials are provisioned as separate, single-purpose key collections, and two of the three are browser-safe:

• collect-web posts browser events — what the SDK’s event collection uses. It can post events but cannot reach your content catalog. The SDK-rendered Experiences reuse this same init() token to read their recommendations (through the Arc Experiences edge), so the browser-SDK path needs no separate read key.
• recommend reads recommendations directly from the Recommendations API — the token a custom-rendered surface (your own components, an email sender, a server-side caller) uses to call the API itself. It is read-only.

Both are public by design — a reader can read either out of your page source — and each collection contains the blast radius of that exposure to its one surface, so both are safe to embed in page JavaScript. The third collection, collector (content ingestion), has no such containment and is server-only. Provision whichever browser-safe key(s) your integration needs; the key-collection model and how each is passed (X-API-Key) are documented in the API guide’s Authentication and tokens — they are not repeated here.

Caution

Never embed a collector (content-ingestion) key in client-side code — it can reach your catalog and must stay server-side. Only the browser-safe collect-web and recommend keys belong on the page.

3. Content sync

Compass can only recommend content it knows about. Your catalog must be ingested into Compass and kept in sync as you publish, update, and unpublish — otherwise recommendations point at content Compass has never seen, or at pages that no longer exist.

Two parts make this work:

• An initial load of your existing catalog, so there is a corpus to recommend from at launch.
• An ongoing feed that keeps the catalog current as editorial changes land.

How you satisfy both depends on whether you are an Arc XP CMS customer — see New customer vs. existing Arc XP customer below. For the mechanics of loading and forwarding content, see Backfilling and Forwarding Data to the Collector; Arc XP CMS customers should also see the end-to-end setup guide.

Note

The identifier you send content under must match the identifier you send on reader events for the same item — the recommendation model joins the two on this field. Settle your ID scheme before you load anything: see the ID Guidance.

4. Reader identity available on the page

Personalization is keyed on a reader identifier. For Compass to build a per-reader history, each page needs to make an identity available:

• A stable, host-managed reader ID — an opaque, pseudonymous account or visitor ID that stays the same for one reader across devices and sessions — is best, because it lets one reader’s history follow them. It must never be a directly identifying value (an email, name, phone number, or the like): the ID is sent to Arc as a join key, so it has to be anonymized. See the User ID Guidance for the anonymization rules.
• If you provide none, the SDK falls back to a per-device anonymous ID it manages itself, which works out of the box but is less durable.

Identity and consent are coupled, but the coupling is specific: the SDK’s own anonymous ID — the per-device fallback — is not created, read, or persisted until the reader’s consent decision resolves. A host-supplied ID you set with setUserId() is different — the SDK holds it in memory and getUserId() returns it regardless of consent, but never persists it. (Either way, the SDK still gates the Experiences’ render and their recommendation read behind granted consent.) The full identity model, consent gate, and the getUserId() contract that keeps your read path coherent are covered in Compass Web SDK: Consent & Identity — have your identity source decided before you integrate.

5. Page and site identity available on the page

Each page must declare which content item it represents so events attribute to the right item, and — for multi-site organizations — which site it belongs to so events attribute to the right catalog. Compass reads these from meta tags on the page.

Content identity (the item ID) is required for automatic page-view capture to work. Site identity is required for multi-site organizations’ event attribution — and, for any tenant, it is required by the SDK-rendered recommendation and Catch Up Experiences, whose render request needs a resolved site_id. A single-site tenant that uses those Experiences must therefore still emit the site meta tag, even though its events would not need one. The exact meta-tag names, syntax, and per-event override options are documented in the SDK Setup guide; what matters for preflight is that your page templates can emit a correct, stable item ID (and site ID where you are multi-site or use SDK-rendered Experiences) for every page.

New customer vs. existing Arc XP customer

The prerequisites are the same for everyone; how a few of them are satisfied differs by whether Compass is running alongside the Arc XP CMS.

Existing Arc XP CMS customers get the smoothest path:

• Content sync can run over Arc’s own integration framework (IFX) as a live content feed, on top of an initial bulk load. This is an explicit opt-in coordinated during onboarding.
• No CMS credential to hand over. Arc mints the credentials it needs to read your content and manage the integration; you are not asked to create or share a CMS or IFX-admin token for content sync.
• Site coordination — the site set Compass serves, and adding a site later — is handled through your TAM against your existing Arc organization.

New or non-Arc-CMS customers own more of the content path:

• Content sync is yours to build. IFX is Arc-CMS-only, so you keep the catalog current by forwarding publishes, updates, and deletes to the Compass Collector from your CMS or CDP, plus an initial backfill. See Backfilling and Forwarding Data to the Collector.
• Entitlement, credential, identity, and page/site identity work exactly as described above — none of those depend on the Arc CMS.

In both cases the entitlement itself is Arc-provisioned and TAM-coordinated; what changes is only who runs the content feed.

Preflight checklist

Before you start integrating, confirm:

• Your TAM (or a Support Center request) has enabled Compass for your organization, and Arc has confirmed provisioning is complete.
• Arc has the inputs it needs from you: the site set, your data-residency region, and your exact website origin(s).
• Your organization is on a supported Arc XP Delivery version (your TAM confirms this).
• You have provisioned the delivery token(s) your path needs — a collect-web token for the browser SDK (its event collection, and the SDK-rendered Experiences reuse the same token), a recommend token if you call the Recommendations API directly from your own code, and/or a collector token if you ingest or forward content server-side. See A delivery credential.
• Content sync is planned: an initial catalog load plus an ongoing feed, by whichever path fits your CMS.
• Your ID scheme is settled, and the ID you sync content under matches the ID you will send on events.
• Your pages can make a reader identity available (host-managed ID preferred, or the SDK anonymous fallback).
• Your page templates can emit a correct item ID (and a site ID — required for multi-site event attribution, and for any tenant that renders the SDK-rendered recommendation or Catch Up Experiences) for every page.

With all of these in place, you are ready to follow the Compass Web SDK: Integration Guide.

Where to go next

• Compass Web SDK: Integration Guide — the canonical setup reference: loader snippet, init(), consent, meta tags, and event tracking.
• Content Recommendations Onboarding Checklist — the phase-by-phase rollout plan once prerequisites are met.
• Content Recommendations API Developer Guide — endpoint reference, authentication, and how the pieces fit together.
• ID Guidance — the identifier rules that make content sync and events join correctly.