# Set up the Compass recommendations block in PageBuilder

Source: https://dev.arcxp.com/content-recommendations/content-recommendations-pagebuilder-setup-guide/

Add the Compass recommendations block to a PageBuilder page, configure its custom fields and site properties, and verify it can reach the Recommendations API.

This guide walks you through adding the Compass recommendations block to a PageBuilder page so a personalized reel renders for your readers, then verifying that the block can reach the Recommendations API from the browser.

Content ingestion and API token provisioning are covered elsewhere; this guide links out to those references rather than repeating them.

> **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.

## Overview

The block calls the **Recommendations API** directly from the browser with an `X-API-Key` header. The API returns a ranked list of items, each carrying a display-ready `card` object, and the block renders them as a reel.

The block can only recommend content that is already in your catalog. For Arc XP CMS customers, the platform-managed `arc_xp_compass` IFX integration keeps the catalog in sync; see [Content Sync from Your CMS](https://dev.arcxp.com/content-recommendations/content-recommendations-api-developer-guide/#content-sync-from-your-cms).

The Recommendations API is served from:

```
https://{org}-config-prod.api.arc-cdn.net/
```

Replace `{org}` with your organization identifier; the `config` and `prod`segments are fixed. The path prefix selects the backend — `/collector/v1` for the Collector API and `/experiences/recommend/v1` for the Recommendations API — appended to this host.

For the full API contract, see the [Compass API Developer Guide](https://dev.arcxp.com/content-recommendations/content-recommendations-api-developer-guide/) and the [API Reference](https://dev.arcxp.com/content-recommendations/content-recommendations-api-reference/).

## Prerequisites

Before you start, make sure you have:

- **Compass enabled** for your organization. If it is not, contact [Arc XP Customer Support](https://support.arcpublishing.com/).
- **A Developer (admin) token** from Developer Center, used to call the Delivery API when provisioning your headless API tokens.
- **A headless API token** (`X-API-Key`) assigned to the **experiences** key collection, used by the block in the browser. You do not need a **collector** key for the block.  
See [Compass Authentication and Tokens](https://dev.arcxp.com/content-recommendations/content-recommendations-api-developer-guide/#authentication-and-tokens) for why the collections are separated and for the full provisioning flow.
- **Roles:** PageBuilder admin (to place the block and set site properties).
- **Content in your catalog.** Without ingested content the block renders an empty reel. See [Content Sync from Your CMS](https://dev.arcxp.com/content-recommendations/content-recommendations-api-developer-guide/#content-sync-from-your-cms).

> **Caution:**
> 
> The **experiences** key ships in the browser and must be treated as public — it may only read recommendations and must never have collector _write_ access. Never place a **collector** key in the block or any browser bundle; it is server-side only.

## Add the recommendations block

The block renders the personalized reel. It reads your experiences key and site identifiers from PageBuilder site properties, calls the Recommendations API directly from the browser, and maps each returned `card` onto a story card.

> **Note:**
> 
> The recommendations block is distributed as a **reference recipe** that you clone into your own theme and adapt, not as a prebuilt block in the standard block catalog. The recipe lives at [arc-fy-recommendations-ui-recipe](https://github.com/ArcXP/arcxp-recommendations-ui-recipe). Add it to your theme following your normal block-integration workflow, then configure it as described below.

> **Caution:**
> 
> The block calls `/experiences/recommend/v1/recommendations`. A copy cloned while the recipe called the deprecated `/recommend/v1/recommendations` must be updated to the `/experiences` path, and its `fyRecommenderApiKey` assigned to the **experiences** collection. The response is the same, so nothing else in the block changes.

### Step 1 — Add the reference block to your theme

1. Clone the recipe from [arc-fy-recommendations-ui-recipe](https://github.com/ArcXP/arcxp-recommendations-ui-recipe) and copy the recommendations feature block into your theme’s blocks.
2. Deploy your theme so the block is available in PageBuilder.
3. In PageBuilder, edit the page or template where the reel should appear.
4. Add the **Recommendations** feature block (labeled **Recommendations – Arc Block** in the block picker) to the layout.
5. Save the page as a draft — you will publish it after configuring the properties below.

![Adding the Recommendations feature block to a page in the PageBuilder editor](https://dev.arcxp.com/_astro/pagebuilder-block-placement.VzZ1MWfv_25e1wy.webp)

### Step 2 — Set the block custom fields

The block exposes these custom fields in the PageBuilder editor:

| Custom field  | Purpose                                                                                                                                                                | Example   |
| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- |
| displayAmount | Number of recommendations to request and render (1–50).                                                                                                                | 10        |
| lazyLoad      | Defer fetching until the block scrolls into view.                                                                                                                      | true      |
| openInNewTab  | Open recommended items in a new browser tab.                                                                                                                           | false     |
| previewMode   | Editor-only preview. When on, the carousel renders sample data (or recommendations for **Preview User ID**) so you can see the layout while composing. Off by default. | false     |
| previewUserId | Editor-only. With **Preview Mode** on, preview recommendations for this user id; leave empty to preview sample data.                                                   | _(empty)_ |

> **Note:**
> 
> **Preview Mode** and **Preview User ID** only affect what you see while editing in PageBuilder (and in local development). They never change the published page — a published page always serves real recommendations for the visitor.

### Step 3 — Set the site properties

The block reads three site properties from your PageBuilder site configuration. Set these per deployment in the PageBuilder admin:

| Property            | Purpose                                                                               | Example        |
| ------------------- | ------------------------------------------------------------------------------------- | -------------- |
| fyRecommenderOrg    | Your organization identifier. Derives the API host {org}-config-prod.api.arc-cdn.net. | {org}          |
| fyRecommenderSite   | The recommender site\_id (the catalog partition key).                                 | <site\_id>     |
| fyRecommenderApiKey | The headless X-API-Key assigned to the **experiences** collection.                    | <headless-key> |

> **Caution:**
> 
> The recommender `site_id` is a **distinct identifier from your Arc website ID** (`arcSite`). By convention it is often `{org}-site`, not the Arc website ID. If they differ and `fyRecommenderSite` is not set to the recommender `site_id`, the block authenticates successfully but returns **0 results**.

![Setting the block's site properties in the PageBuilder admin](https://dev.arcxp.com/_astro/pagebuilder-site-properties.6H4r2L9W_OqPlx.webp)

### Step 4 — Provide a stable user ID

The Recommendations API requires a `user_id` for every request. The block reads a stable per-visitor identifier from `fy_user_id` (cookie or `localStorage`). If it is absent, the block cannot request personalized results.

- For logged-in readers, set `fy_user_id` to your anonymized, stable user identifier.
- For anonymous readers, generate a stable ephemeral ID once and persist it, so the same visitor produces the same `user_id` across sessions.

> **Note:**
> 
> `user_id` must be anonymized — never an email, name, or other PII — and stable across sessions. See [User ID Guidance](https://dev.arcxp.com/content-recommendations/content-recommendations-item-id-guidance/#user-id) for the anonymization and stability rules.

When your properties are set and the block has a `user_id`, publish the page. The block renders the reel once the API returns items.

For a framework-agnostic view of how the returned `card` maps onto a story card (empty and error states included), see [Deploying and Rendering Recommendations](https://dev.arcxp.com/content-recommendations/content-recommendations-rendering-story-cards/).

## Verify the block

Run these checks to confirm the block’s experiences key and browser access are working.

### 1\. Authentication check (server-side)

Confirm your experiences key is accepted and returns results:

Terminal window

```bash
curl -i -H "X-API-Key: <headless-key>" \
  "https://{org}-config-prod.api.arc-cdn.net/experiences/recommend/v1/recommendations?site_id=<site_id>&user_id=test-user&num_results=5"
```

Expected results:

- `200` with a `recommendations` array. On a cold catalog the array may be empty — that is still success.
- `401` / `403` → the key is missing or not assigned to the experiences collection. Re-check the assignment step in the token-provisioning guide.
- `422` → a required query parameter (`site_id` or `user_id`) is missing.

### 2\. CORS preflight check (browser-direct)

The block calls the API from the browser, so the preflight must succeed for your origin:

Terminal window

```bash
curl -i -X OPTIONS \
  -H "Origin: https://<your-site-origin>" \
  -H "Access-Control-Request-Method: GET" \
  -H "Access-Control-Request-Headers: x-api-key" \
  "https://{org}-config-prod.api.arc-cdn.net/experiences/recommend/v1/recommendations"
```

Expected: `200` (or `204`) with `access-control-allow-origin` for your origin, `access-control-allow-methods: GET, OPTIONS`, and `access-control-allow-headers` including `X-API-Key`.

If the allow headers are missing, your origin is not in the API’s allowed origins.

> **Note:**
> 
> `X-API-Key` is not a simple CORS header, so it must be explicitly allowed in the preflight response. If the preflight fails at the edge with a `403` and no allow-origin header, this is provisioned by the platform — contact Arc XP Customer Support with your origin.

### 3\. In-browser check

Load the page with the block and confirm the reel renders for a visitor with a valid `user_id`.

## FAQs

**Why do I get a `200` but an empty list?**

Cold start. The model needs a populated catalog and a meaningful behavioral signal before it returns ranked items. See the [Onboarding Checklist](https://dev.arcxp.com/content-recommendations/content-recommendations-onboarding-checklist/) for how to warm it up.

**Why is my `site_id` different from my website ID?**

The recommender partitions the catalog on its own `site_id`, which is often `{org}-site` rather than your Arc website ID (`arcSite`). Set `fyRecommenderSite` (block) to the recommender `site_id` so the block reads from the same partition your content is ingested under.

**Why does a card have no image?**

The item has no thumbnail in its `card`. The block renders a placeholder in that case. Make sure your published content carries a lead image so the ingest maps a thumbnail.

**Which key goes where — experiences or collector?**

The **experiences** key goes in the block (browser) and is public. A **collector** key is server-side only and must never reach the browser. The block never needs a collector key.

**The preflight returns `403` from the edge — who fixes it?**

CORS origins are provisioned at the platform edge. If your origin is not allowed and you cannot self-serve it, contact Arc XP Customer Support with the exact origin you need allowed.