# Compass Onboarding Checklist

Source: https://dev.arcxp.com/content-recommendations/content-recommendations-onboarding-checklist/

Pre-launch, launch, and post-launch checklist for rolling out Arc XP Compass.

_A practical, phase-by-phase checklist for taking Compass from zero to live traffic without launching on a cold model._

## About this checklist

This guide is a companion to the [Compass API Developer Guide](https://dev.arcxp.com/content-recommendations/content-recommendations-api-developer-guide/) and the [Recommendation Surfaces Playbook](https://dev.arcxp.com/content-recommendations/content-recommendations-recommendation-surfaces/). The developer guide covers _what_ the API does; this checklist covers _when_ to do each step in a rollout.

The phases are sequential. Before you start, confirm that everything on [Compass Prerequisites & Enablement](https://dev.arcxp.com/content-recommendations/content-recommendations-prerequisites-enablement/) is in place.

> **Note:**
> 
> There is no separate Sandbox or Production instance for the Content Recommendations API. It is provisioned in **Production only**. Every content payload and behavioral event trains the single model that serves your live traffic. Plan your testing and rollout accordingly, and use a dedicated test `site_id` to keep experimental data out of your production catalog.

## Pre-launch

The goal of this phase is to have a fully populated catalog, a meaningful behavioral signal, and a working integration.

### Choose your event-collection path

- Decide how you’ll collect behavioral events: the client-side [Compass Web SDK](https://dev.arcxp.com/content-recommendations/sdk/integration-guide/) or a [CDP / server-side forwarder](https://dev.arcxp.com/content-recommendations/content-recommendations-cdp-integration/) (you can use both). See [Choose your integration path](https://dev.arcxp.com/content-recommendations/content-recommendations-integration-paths/) for the comparison.

### Access and credentials

- Identify the team or service that will own the integration end-to-end.
- Provision the Headless API token(s) your integration path needs: one token in the **`collect-web`** and **`experiences`** collections if you use the browser [Compass Web SDK](https://dev.arcxp.com/content-recommendations/sdk/integration-guide/) (it authenticates both event posts and the SDK-rendered Experiences’ reads), a token in the **`experiences`** collection if you call the Recommendations API directly from your own code, and a **`collector`** token for server-side content ingestion or event forwarding. An SDK-only rollout needs only the one browser token. Follow [Provision and Manage Compass API Keys](https://dev.arcxp.com/content-recommendations/content-recommendations-api-keys/) for the key-collection setup and provisioning flow.
- Store tokens in your secrets manager and never commit them to source control.

### Identifiers and anonymization

- Decide on your `user_id` scheme. It must be anonymized: never an email, name, or other PII. See the [User ID Guidance](https://dev.arcxp.com/content-recommendations/content-recommendations-item-id-guidance/#user-id) for the full rules.
- Confirm the same `user_id` will be produced for the same person across sessions, devices (where possible), and between historical backfill and live traffic — see the stability rules in the [User ID Guidance](https://dev.arcxp.com/content-recommendations/content-recommendations-item-id-guidance/#user-id).
- Decide on your `item_id` scheme. Prefer your CMS’s stable internal record ID over a URL slug, and never a full URL. Arc XP customers should use the content’s ArcID. See the [Item ID Guidance](https://dev.arcxp.com/content-recommendations/content-recommendations-item-id-guidance/) for the full rules.
- Confirm the same `item_id` will be used in _both_ content payloads and behavioral events. The model joins on this field.
- Pick a dedicated test `site_id` to use for any QA or load testing. Never test against your production `site_id`.

### Content catalog

How you load the catalog depends on your CMS. See [Sync Your Content Catalog with Compass](https://dev.arcxp.com/content-recommendations/content-recommendations-content-sync/) for both paths.

- **Arc XP CMS customers:** Arc XP loads your published stories during onboarding, and the platform-managed `arc_xp_compass` integration keeps publishes, updates, and deletes in sync. Publish a test story and confirm it appears in a recommendations response.
- **Other CMSs:** Bulk-load every published item in your catalog via `POST /collector/v1/content` with `action: "publish"`.
- **Other CMSs:** Include accurate `categories`, `tags`, `author`, and `timestamp` on every item. Sparse metadata hurts cold-start quality for new content later.
- **Other CMSs:** Wire up the live CMS webhook so ongoing publishes, updates, and deletes stay in sync automatically.
- **Other CMSs:** Verify your unpublish/delete pipeline sends `action: "delete"` payloads. Stale catalog entries lead to recommendations pointing at dead pages.

### Behavioral signal

> **Note:**
> 
> **Live vs. backfill.** _Live_ web collection is where the two paths differ: the Compass Web SDK captures and posts browser events for you, while a forwarder POSTs them from your CDP or server. _Historical backfill_ is always a forwarder job — the SDK only sees events as they happen in the browser — so the first item in the following list applies whichever live path you chose.

- Replay 30–90 days of historical events through `POST /collector/v1/events` if your CDP or analytics system retains them.
- Preserve the original `timestamp` on each historical event — do not stamp them with the backfill time.
- Send richer event types (`click`, `article_save`, `deepest_scroll`, `engaged_read`) in addition to `page_view` where you have them.
- Filter internal employee traffic out of any event stream before sending. Editor and newsroom traffic skews the model away from real reader interest.
- Filter known bot and crawler traffic out of any event stream before sending.

### Shadow-deploy the collector

- Instrument live event collection against the real production `site_id` while recommendations remain hidden from users — add the Compass Web SDK snippet (SDK path) or point your forwarder at the Collector (CDP/server path).
- Let the collector run for a meaningful window — typically a few weeks — so the model trains on real traffic patterns alongside the historical backfill.
- Spot-check `GET /experiences/recommend/v1/recommendations` from internal surfaces (QA builds, staging, internal dashboards) during this window.

### Pre-launch validation

- Sample recommendations for a diverse set of `user_id`s — new users, heavy readers, anonymous sessions — and manually review whether results look on-topic.
- Confirm returned `item_id`s resolve cleanly in your CMS and aren’t pointing at deleted, unpublished, or non-existent content.
- Stress-test your card-rendering layer. Each recommendation returns a display-ready `card`; confirm your front-end degrades gracefully when a `card` (or an individual field) is missing.
- Decide on a rollout strategy: percentage of traffic, single surface, or single site first. Avoid flipping recommendations on everywhere at once.

## Launch

This phase is the cutover itself. Keep it small, observable, and reversible.

### Day-of cutover

- Enable recommendations on the chosen launch surface and traffic slice only.
- Confirm the front-end is sending `click` events back to the Events endpoint when readers click a recommended item. This feedback loop drives quality improvement.
- Watch error rates and latency on both the Collector and Recommendations APIs in real time for the first hour.
- Spot-check live recommendations for several real user sessions immediately after enabling.

### Health checks during the rollout window

- Confirm `POST /collector/v1/events` traffic volume matches expected page-view and click volume from your analytics. A large gap usually means an instrumentation bug.
- Confirm `POST /collector/v1/content` is firing on every publish, update, and delete from your CMS.
- Check that `recommendations` array lengths look reasonable across users — empty arrays for many users typically indicate a `site_id` mismatch.
- Keep a rollback path warm. If anything looks wrong, you should be able to disable the surface or reduce the traffic slice in minutes, not hours.

### Expand the rollout

- Increase the traffic slice in stages after health checks are stable. Common ramps are 5% → 25% → 50% → 100%, with a hold period at each step.
- Add additional surfaces (article-page rails, homepage modules, email, etc.) one at a time. See the [Recommendation Surfaces Playbook](https://dev.arcxp.com/content-recommendations/content-recommendations-recommendation-surfaces/) for surface-specific guidance.
- Avoid launching multiple new surfaces in the same week unless you have separate observability for each.

## Post-launch

After recommendations are live for real readers, the work shifts from _standing it up_ to _keeping it healthy_ and _making it better_.

### Ongoing data hygiene

- Monitor that the CMS → Content endpoint pipeline stays in sync. A silent webhook failure for even a day or two will bias recommendations toward stale content.
- Audit your `delete` payloads quarterly. Over-aggressive deletes silently shrink the recommendable catalog.
- Re-confirm your bot and employee filters periodically. Both tend to drift as your traffic mix and internal tooling evolve.
- Re-validate `user_id` stability. If session-scoped IDs leak in alongside authenticated IDs, the model can’t accumulate history per reader.

### Quality monitoring

- Track click-through rate on recommendation surfaces against your pre-launch baseline. Surface-level CTR is the cleanest read on whether the model is earning its keep.
- Track the rate of recommendations returned with `card: null` (items the model still references but whose content document has not synced). A nonzero number indicates a delete-pipeline or content-sync gap.
- Sample recommendations for a rotating set of `user_id`s on a recurring cadence — the same review you did pre-launch, but now with real engagement data behind it.
- Treat empty-recommendation responses as a signal to investigate, not a bug to suppress. Common causes are `site_id` mismatches and over-aggressive deletes — see [No recommendations returned](https://dev.arcxp.com/content-recommendations/content-recommendations-troubleshooting/#no-recommendations-returned).

### Iterate on surfaces and signals

- Add richer event types over time if you launched with `page_view` and `click` only. `deepest_scroll`, `article_save`, and `engaged_read` materially improve personalization quality.
- Expand to new surfaces from the [Recommendation Surfaces Playbook](https://dev.arcxp.com/content-recommendations/content-recommendations-recommendation-surfaces/) after an existing surface is healthy and instrumented.
- Revisit content metadata coverage. Pages missing `categories`, `tags`, or `author` reduce what the model can reason about — especially for new content.
- Schedule a recurring (quarterly is a reasonable default) review of recommendation quality with editorial and product stakeholders.

### Token and access maintenance

- Rotate Headless API tokens on whatever cadence your security policy requires.
- Remove tokens that are no longer in use via `DELETE /v1/access/keys/{key_id}`. The 30-token-per-environment limit is easy to hit if old tokens linger — see [Remove tokens you no longer use](https://dev.arcxp.com/content-recommendations/content-recommendations-api-keys/#5-remove-tokens-you-no-longer-use).

## Where to go next

- [Compass API Developer Guide](https://dev.arcxp.com/content-recommendations/content-recommendations-api-developer-guide/) — endpoint reference, authentication, field-level details, and troubleshooting.
- [Recommendation Surfaces Playbook](https://dev.arcxp.com/content-recommendations/content-recommendations-recommendation-surfaces/) — surface-by-surface guidance for where to deploy recommendations and what each placement is good at.
