Set up the Compass recommendations block in PageBuilder

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.

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 and the API Reference.

Prerequisites

Before you start, make sure you have:

• Compass enabled for your organization. If it is not, contact Arc XP Customer Support.

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

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

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.

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

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:

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:

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