# Choose your integration path

Source: https://dev.arcxp.com/content-recommendations/content-recommendations-integration-paths/

Compare the ways to collect reader events for Arc XP Compass and to render recommendations.

Every Arc XP Compass integration makes two independent choices: how reader events reach Compass, and how recommendations reach the page. This page explains the options for each, how they combine, and what each combination costs you. It does not walk through setup; each option links to the page that does. For the concepts behind these choices, see [How Compass works](https://dev.arcxp.com/content-recommendations/content-recommendations-overview/).

## What every integration shares

Three parts make up every integration, and two of them are the same no matter what you choose:

- **Content catalog sync** is the same for every path. Your CMS keeps the catalog current through the Content endpoint of the Collector API; for Arc XP CMS customers, a platform-managed integration does this for you. See [Content Sync from Your CMS](https://dev.arcxp.com/content-recommendations/content-recommendations-api-developer-guide/#content-sync-from-your-cms).
- **Behavioral event collection** is the first choice on this page.
- **Recommendations read** always goes through the same read path, `/experiences/recommend/v1`. How you render what it returns is the second choice on this page.

Every collection option feeds the **same** model, and every rendering option reads from the **same** read path. The choice is about where your signal comes from, who renders the cards, and how much you want to build.

## Choice 1: How events reach Compass

|                 | **Compass Web SDK**                                                                                                       | **Collector API, sent directly**                                            | **CDP or server-side forwarding**                                                                                                            |
| --------------- | ------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| What it is      | Arc XP’s first-party browser library (@arcxp/compass-sdk, global ArcCompass) that you embed in your pages                 | Your own server or app posts events to the Collector API                    | A translation you write that maps your CDP’s or analytics stack’s events onto the Compass event envelope and posts them to the Collector API |
| Where events go | collect-web/v1 (the browser events collector)                                                                             | collector/v1 (the server-side Collector API)                                | collector/v1 (the server-side Collector API)                                                                                                 |
| Key collection  | **collect-web** (browser-safe)                                                                                            | **collector** (server-side only)                                            | **collector** (server-side only)                                                                                                             |
| Reach           | Browser only                                                                                                              | Any source you control: servers, native apps, OTT                           | Whatever your CDP or analytics source already sees, including historical data for backfill                                                   |
| Built in        | Automatic page\_view capture (including SPA routes), a consent gate, identity and session management, batching, and retry | Nothing; you own batching, retry, identity stability, and consent filtering | Nothing; you own the mapping, batching, retry, identity stability, and consent filtering                                                     |
| Effort          | Paste a snippet, call init(), resolve consent: roughly one hour                                                           | Build a sender against the event envelope                                   | Build or adapt a forwarder from a template for your source                                                                                   |

**The Web SDK** is the fastest path when your signal is mostly web traffic and you do not already forward events from a CDP. What you give up is reach: it only sees browsers, and it only collects from readers who grant consent.

**Sending to the Collector API directly** fits events that originate somewhere the SDK cannot run: server-side, native apps, or OTT. What you give up is everything the SDK does for you. Identity, consent filtering, batching, and retry become your code.

**Forwarding from a CDP or server-side source** fits teams that already run a CDP (such as BlueConic, Amplitude, Adobe Real-Time CDP, Tealium, Permutive, or ActionIQ) or need to backfill history before launch. There is no per-vendor connector to enable: you translate your source’s events into the Compass envelope on your side. What you give up is the same as for direct sends, plus a dependency on your source’s latency and coverage.

The options are not mutually exclusive. A common pattern runs the Web SDK for live web traffic and a forwarder for historical backfill or non-web surfaces. When you combine them, the two streams only add up if the join keys match: send the same anonymized `user_id` for the same reader and the same `item_id` for the same content on every path. Otherwise the model treats the streams as unrelated readers and items. See the [ID Guidance](https://dev.arcxp.com/content-recommendations/content-recommendations-item-id-guidance/).

Setup guides:

- [Compass Web SDK: Integration Guide](https://dev.arcxp.com/content-recommendations/sdk/integration-guide/)
- [Forward Events from a CDP or Server](https://dev.arcxp.com/content-recommendations/content-recommendations-cdp-integration/) (covers both direct sends and CDP forwarding)

## Choice 2: How recommendations reach the page

|                            | **SDK-rendered components**                                                | **PageBuilder Editor block**                                                                                       | **Custom rendering from the API**                                        |
| -------------------------- | -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------ |
| What you provide           | One custom-element tag and CSS                                             | A reference block that you clone into your theme and configure with site properties                                | Your own components and rendering code                                   |
| What Compass provides      | The fetch, the card UI, consent gating, and exposure and click attribution | A starting implementation that calls the Recommendations API from the browser and maps each card onto a story card | The ranked list with a display-ready card per item                       |
| Reader identity comes from | The SDK (getUserId())                                                      | A fy\_user\_id value in a cookie or localStorage                                                                   | Whatever user\_id you pass                                               |
| Reach                      | Web pages that load the SDK                                                | Arc XP PageBuilder Editor pages                                                                                    | Any surface: web, app, email, server-side                                |
| Gives up                   | Markup control beyond theming tokens and ::part() hooks                    | You maintain the cloned block as your own code                                                                     | You build the UI, the empty and error states, and the attribution wiring |

**SDK-rendered components** are the lowest-code option: the recommendations carousel and list, and the Catch Up card, which is a separate Experience with its own read. They need the SDK loaded, initialized, and with consent granted on the page, so choosing them means the SDK is on the page whether or not you also use it as your primary event source.

**The PageBuilder Editor block** fits sites built on PageBuilder Editor that want a configured, in-editor surface. It is distributed as a reference recipe, so it behaves like your own code after you clone it.

**Custom rendering** fits surfaces that need full markup control, a framework-native component, or a channel the SDK cannot reach, such as email. You render the `card` objects yourself and are responsible for sending engagement back.

Setup guides:

- [Compass Web SDK: Recommendations Components](https://dev.arcxp.com/content-recommendations/sdk/recommendations-components/) and [Catch Up Card](https://dev.arcxp.com/content-recommendations/sdk/catch-up-card/)
- [PageBuilder Editor block setup guide](https://dev.arcxp.com/content-recommendations/content-recommendations-pagebuilder-setup-guide/)
- [Deploying and Rendering Recommendations](https://dev.arcxp.com/content-recommendations/content-recommendations-rendering-story-cards/)

## How the choices combine

Any collection option can pair with any rendering option, and one site can use several. What changes is what you have to keep aligned yourself.

| Collection ↓ / Rendering →        | **SDK-rendered components**                                                                                                                 | **PageBuilder Editor block**                                                                                           | **Custom rendering from the API**                                                                                        |
| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| **Compass Web SDK**               | The most built-in path: one SDK collects, identifies, renders, and attributes. You give up markup control and non-browser reach.            | Two identities on one page: the block reads fy\_user\_id, the SDK uses its own identity. See the caution that follows. | Pass getUserId() as the read’s user\_id, and tag rendered cards for the SDK to attribute. You give up the ready-made UI. |
| **Collector API, sent directly**  | The components bring the SDK onto the page, so it also collects from the browser. Keep user\_id and item\_id identical across both streams. | You own identity end to end: the user\_id you send on events must be the value in fy\_user\_id.                        | Full control and full responsibility: identity, consent, batching, retry, UI, and attribution are yours.                 |
| **CDP or server-side forwarding** | As with direct sends: the SDK is on the page anyway, so keep the join keys identical across the SDK stream and the CDP stream.              | Your CDP’s user\_id must be the value in fy\_user\_id, or the block reads for a reader with no history.                | Use the same ID your CDP sends as the read’s user\_id. You build the UI and the attribution wiring.                      |

For SDK-based attribution on host-rendered surfaces, see [Compass Web SDK: Recommendation Attribution](https://dev.arcxp.com/content-recommendations/sdk/attribution/). For how to report engagement when you render without the SDK, see the principles in [Recommendation Surfaces Playbook](https://dev.arcxp.com/content-recommendations/content-recommendations-recommendation-surfaces/#principles-that-apply-to-every-surface).

> **Caution:**
> 
> **Running the Web SDK and the PageBuilder Editor block on one page splits a reader’s identity.** The block reads its `user_id` from `fy_user_id` (a cookie or `localStorage`). The SDK puts its own identity on events: the ID you set with `setUserId()` or, if you set none, its anonymous `arccompass_aid` ID, which `getUserId()` returns. Compass does not stitch identities, so unless both resolve to the same raw value, the block requests recommendations for a reader whose SDK-collected history it cannot see. See [getUserId(): keep the recommend read path coherent](https://dev.arcxp.com/content-recommendations/sdk/consent-identity/#getuserid--keep-the-recommend-read-path-coherent) and [Provide a stable user ID](https://dev.arcxp.com/content-recommendations/content-recommendations-pagebuilder-setup-guide/#step-4--provide-a-stable-user-id).

## Related pages

- [How Compass works](https://dev.arcxp.com/content-recommendations/content-recommendations-overview/)
- [Compass Prerequisites & Enablement](https://dev.arcxp.com/content-recommendations/content-recommendations-prerequisites-enablement/)
- [Authentication and tokens](https://dev.arcxp.com/content-recommendations/content-recommendations-api-developer-guide/#authentication-and-tokens)
