# Compass Prerequisites & Enablement

Source: https://dev.arcxp.com/content-recommendations/content-recommendations-prerequisites-enablement/

Everything that must be in place before you can integrate Compass — a provisioned entitlement, a delivery credential, content sync, reader identity, and page/site identity — and how enablement is coordinated through Arc XP Customer Support.

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](https://dev.arcxp.com/content-recommendations/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 [Compass Onboarding Checklist](https://dev.arcxp.com/content-recommendations/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: you request provisioning from Arc XP Customer Support, 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. Open a request through the [Arc XP Support Center](https://arcpublishing.atlassian.net/servicedesk/customer/portal/2) to enable Compass for your organization.
2. Confirm a few provisioning inputs Arc needs from you — see [What Arc needs from you](#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 Arc XP Customer Support — there is no self-serve.**Enabling Compass, choosing which sites it serves, and adding a site to a live tenant are all Arc-coordinated operations requested through 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 change you request through the Support Center.                           |
| 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. |

## 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 (requested through the Support Center)       | This page                                                                                                                                                                                                                                                                |
| 2 | A delivery credential (API token)        | You, via the Delivery API                           | [Provisioning tokens](https://dev.arcxp.com/platform-tools/developer-docs/provisioning-tokens-through-delivery-api/) · [SDK Setup](https://dev.arcxp.com/content-recommendations/sdk/integration-guide/)                                                                 |
| 3 | Content sync (catalog ingestion)         | Arc XP for Arc XP CMS customers; you for other CMSs | [Backfilling & Forwarding](https://dev.arcxp.com/content-recommendations/content-recommendations-cdp-integration/) · [Content Sync from Your CMS](https://dev.arcxp.com/content-recommendations/content-recommendations-api-developer-guide/#content-sync-from-your-cms) |
| 4 | Reader identity available on the page    | You                                                 | [Consent & Identity](https://dev.arcxp.com/content-recommendations/sdk/consent-identity/)                                                                                                                                                                                |
| 5 | Page/site identity available on the page | You                                                 | [SDK Setup](https://dev.arcxp.com/content-recommendations/sdk/integration-guide/)                                                                                                                                                                                        |

### 1\. A provisioned Compass entitlement

Your organization must be provisioned for Compass before anything else works. This is the entitlement Arc establishes when your provisioning 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](https://dev.arcxp.com/platform-tools/developer-docs/provisioning-tokens-through-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.
- **`experiences`** reads recommendations from the Recommendations API. It is read-only. The SDK-rendered Experiences read through it, and so does a **custom-rendered** surface (your own components, an email sender, a server-side caller) that calls the API itself.

The browser SDK uses one `init()` token for both, so assign that token to the **`collect-web`** and **`experiences`** collections.

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](https://dev.arcxp.com/content-recommendations/content-recommendations-api-developer-guide/#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 **`experiences`** 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.

**Arc XP CMS customers:** this is handled for you. During onboarding, Arc loads your existing published stories into Compass. After that, a platform-managed IFX integration forwards stories to Compass as they are published, updated, and unpublished. There is nothing for you to build or configure, and you do not need to create or share a CMS token. See [Content Sync from Your CMS](https://dev.arcxp.com/content-recommendations/content-recommendations-api-developer-guide/#content-sync-from-your-cms).

**Other CMSs:** you build content sync yourself. It has two parts:

- **An initial load** of your existing catalog, so there is a corpus to recommend from at launch.
- **An ongoing feed** that forwards publishes, updates, and deletes to the Compass Collector from your CMS or CDP.

See [Backfilling and Forwarding Data to the Collector](https://dev.arcxp.com/content-recommendations/content-recommendations-cdp-integration/).

> **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](https://dev.arcxp.com/content-recommendations/content-recommendations-item-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](https://dev.arcxp.com/content-recommendations/content-recommendations-item-id-guidance/#user-id) 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](https://dev.arcxp.com/content-recommendations/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](https://dev.arcxp.com/content-recommendations/sdk/integration-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.

## Preflight checklist

Before you start integrating, confirm:

- 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)**.
- You have provisioned the **delivery token(s)** your path needs — a token in the **`collect-web`** and **`experiences`** collections for the browser SDK (its event collection and its Experiences’ reads), a token in the **`experiences`** collection 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](#2-a-delivery-credential).
- **Content sync is planned** (non-Arc CMSs only; Arc XP CMS customers can skip this): an initial catalog load plus an ongoing feed.
- 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](https://dev.arcxp.com/content-recommendations/sdk/integration-guide/).

## Where to go next

- [Compass Web SDK: Integration Guide](https://dev.arcxp.com/content-recommendations/sdk/integration-guide/) — the canonical setup reference: loader snippet, `init()`, consent, meta tags, and event tracking.
- [Compass Onboarding Checklist](https://dev.arcxp.com/content-recommendations/content-recommendations-onboarding-checklist/) — the phase-by-phase rollout plan once prerequisites are met.
- [Compass API Developer Guide](https://dev.arcxp.com/content-recommendations/content-recommendations-api-developer-guide/) — endpoint reference, authentication, and how the pieces fit together.
- [ID Guidance](https://dev.arcxp.com/content-recommendations/content-recommendations-item-id-guidance/) — the identifier rules that make content sync and events join correctly.