Skip to content
Arc XP

Content Recommendations User Experience Guide

Five surfaces where personalized recommendations earn their keep, and what it takes to ship each one.

About this guide

This document is a companion to the Content Recommendations API Developer Guide. Where the developer guide covers endpoints, authentication, and data ingestion in depth, this guide focuses on the other half of the problem: where on your site, app, and in your email program you should actually deploy recommendations, what each placement is good at, and what it takes — on both the product and engineering side — to stand one up well.

Every surface here uses the same backend APIs. The core endpoint you’ll call to populate each one is the same:

GET /recommendations/v1/recommendations?site_id={site}&user_id={user}

What changes between surfaces is the presentation, the signals you feed back to the model, and whether you’re asking for a general personalized feed or a contextual “more like this” ranking anchored to a specific article. Each section below spells that out.

Before you build any of these

The API returns ranked item_ids — not rendered content. For every surface in this guide, your front-end is responsible for hydrating those IDs against your CMS (title, image, URL, byline) and rendering the card. Plan for that hydration layer once and reuse it across surfaces.

Principles that apply to every surface

A few design and engineering decisions show up in every placement. Get these right once and they pay off across all five surfaces:

  • Send a click event back when a reader engages. Every recommendation a reader clicks is a signal that trains the next one. Posting a click event to your Customer Data Platform (CDP) and forward the events to the Collector endpoint /collector/v1/events when a reader taps a recommended card is the single highest-leverage thing you can do to improve relevance over time.
  • Label personalized content, don’t hide it. “For You,” “Picked for you,” “Based on what you’ve read” — explicit labeling builds trust and sets the right expectation. It also gives readers a reason to engage with a module that could otherwise read as generic recirculation.
  • Use stable, anonymized user IDs. The model learns per-user. If the same reader shows up under different IDs across sessions or devices, personalization quality degrades. Use a consistent anonymized identifier — a hashed logged-in ID where available, a persistent cookie / device ID otherwise — and never send raw PII.
  • Exclude the current article from contextual surfaces. Whenever you call the API with an anchor item_id, filter that same ID out of the returned list on render. The API can return the anchor itself in some cases and you don’t want a “read next” module recommending the article the reader is already on.

Surface 01  ·  Homepage “For You” module

A personalized rail on your front page — the flagship surface, and usually the first one customers ship.

  • UX goal: Give returning readers a reason to scroll past the top of the homepage by surfacing content they’re likely to care about.
  • Best for: Publishers with a meaningful share of returning, identified, or cookied traffic.
  • API mode: General personalized recommendations (no anchor item_id).

The experience

The “For You” module lives on the homepage, typically below the main news hierarchy — after the hero and the top editorial rails, but above the deep tail of section blocks. This placement matters: putting it above editorially curated news signals that personalization replaces the newsroom’s judgment, which isn’t what most publishers want. Putting it after the lead coverage positions it as “here’s what else is worth your time,” which is exactly the job it does well.

A typical layout is a labeled rail — “For You,” “Picked for you,” or “Your briefing” — with 6 to 12 cards in a horizontal scroll on mobile and a grid on desktop.

For anonymous or first-time readers, the module still renders — the API returns popularity-weighted results by default for cold-start users — but you can choose to label it differently (“Most popular today”) until the reader has accumulated enough signal. That’s a product call, not an API one.

How to implement it

On page load, call the Recommendations endpoint with the reader’s user_id (and no content anchor):

GET /recommendations/v1/recommendations?site_id=my-site&user_id=user-abc
  • Request 10–15 items, more than you plan to show. That gives you headroom to filter out articles the reader has recently viewed or items that fail CMS hydration.
  • Hydrate item_ids against your CMS to pull headline, image, URL, and publish date.
  • Cache carefully. Personalization is per-user, so typical CDN page caching won’t apply to this module. Most implementations render the module client-side after the shell loads, or fetch it at the edge keyed on user_id.
  • Fire a click event to your CDP (and forward to /collector/v1/events via your middleware) the moment a reader taps a card, with event_type: "click" and the item_id of the clicked article.

Things to watch for

Because the homepage is your highest-traffic surface, this module’s performance matters. Fetch it asynchronously so it never blocks above-the-fold render, and have a sensible fallback — popular articles from your CMS, say — ready if the Recommendations API call fails or times out.

Test with anonymous and logged-out sessions explicitly. A “For You” module that looks identical to every reader on their first visit will feel broken even when it’s working as designed.

Surface 02  ·  “For You” tab or landing page

A full-surface, personalized destination — the long-form version of the homepage rail.

  • UX goal: Give highly engaged readers a dedicated home for personalized content, and give the app a prominent hook for habitual use.
  • Best for: News apps, logged-in experiences, and publishers with a clear power-user segment.
  • API mode: General personalized recommendations (no anchor item_id), typically paginated or infinitely scrolled.

The experience

Where the homepage rail is an appetizer, the “For You” tab is the meal. In a mobile app, it usually sits as a first-class tab alongside Home, Sections, and Saved. On desktop web, the equivalent is a dedicated /for-you landing page reachable from the main nav or a persistent CTA for logged-in users.

The experience is a deep, scrollable feed — cards or list items, one recommendation per row or in a staggered grid, loading more as the reader scrolls.

How to implement it

Call the same endpoint, but pull more results and paginate. Fetch the first page on tab load, then fetch additional pages as the reader scrolls:

GET /recommendations/v1/recommendations?site_id=my-site&user_id=user-abc
  • Treat this as the highest-signal surface you own. A reader who sits in the For You tab and scrolls is generating dense behavioral data. Make sure you’re capturing click, deepest_scroll, and engaged_read events here — they improve recommendations across every other surface.
  • De-duplicate against session history. On mobile especially, readers may see the same items across the homepage rail and the For You tab. Keep a client-side set of item_ids the reader has already been shown this session and filter them out on render.
  • Consider a refresh affordance. A pull-to-refresh on mobile or a “Refresh feed” button on web, which re-calls the API, gives readers an explicit way to get a new set of picks.
  • Log impressions, not just clicks, if your analytics can support it. Knowing which recommendations were shown but skipped is valuable product signal, even if you don’t send it back to the Collector.

Things to watch for

A full “For You” surface sets a high bar for relevance. If the model is still cold — newly provisioned, or the customer hasn’t backfilled historical events — this surface will expose that thinness more than a homepage rail will.

If you already have an editorially curated feed or a “Saved” tab, think carefully about tab order and labeling. “For You” should feel like a distinct, additive destination — not a replacement for what readers already reach for.

Surface 03  ·  Inline article recommendation

A single, contextually relevant recommendation dropped mid-article, where engaged readers meet it.

  • UX goal: Catch readers at peak engagement and offer the one most relevant next story — without derailing the one they’re in.
  • Best for: Long-form articles, feature stories, and explainer content where readers are likely to read deeply.
  • API mode: “More like this” — personalized recommendations anchored to the current article.

The experience

Unlike the homepage rail or the For You tab, this is a single-item placement embedded in the body of the story itself — typically between the fifth and seventh paragraph, where reader engagement is highest but attention hasn’t yet begun to drop off. Readers who make it that far into an article are highly qualified; a well-placed, contextually relevant recommendation here converts at rates that end-of-article modules often can’t match.

The UX is intentionally restrained: a single card or a compact two-line teaser, visually distinct from the article body (a subtle tint, a thin top-and-bottom rule, an “Also in [section]” or “Related reading” label), but not so loud that it interrupts the reader’s flow. Think of it less as an ad unit and more as a well-edited sidebar — the kind of thing an editor might add to a print feature.

Because the recommendation is anchored to the article the reader is currently in, the result is tightly topical. A reader halfway through a piece on local housing policy gets a contextual next read on zoning, not an off-topic recommendation from their general reading history.

How to implement it

Call the Recommendations endpoint with both the user_id and the current article as the anchor item_id:

GET /recommendations/v1/recommendations?site_id=my-site&user_id=user-abc&item_id=ARTICLE-123
  • Fetch once, render once. Only one item goes in-body. Request five results and take the top one that (a) isn’t the current article and (b) hydrates cleanly in your CMS.
  • Render server-side where possible. Because the anchor is known at page render time, this is one of the few personalized surfaces you can render into the initial HTML. That’s good for both performance and SEO.
  • Fire a click event on tap. As with every surface: event_type: "click" back to your CDP (and forward to /collector/v1/events via your middleware), with the clicked item_id. Inline placements tend to have strong click signal — don’t leave it on the table.
  • Consider an engaged_read event on the article itself, triggered when a reader has been on page past a dwell threshold or hit a deep scroll mark. These richer events meaningfully improve model quality, and articles are the natural place to capture them.

Things to watch for

Placement is the whole game. Too early and it feels like an interruption; too late and you’ve missed the window. Five to seven paragraphs in is the general heuristic, but test with your own content — feature-length pieces may warrant a later insertion.

Be cautious about stacking this with display ads in the same vertical span. If there’s an ad slot at paragraph four and a recommendation at paragraph six, readers experience both as interruptions and tune both out.

Surface 04  ·  Article end cap (story ender)

The recirculation module at the bottom of the article — the workhorse of content recirculation.

  • UX goal: Capture readers who finished the article and give them an obvious next click before they bounce.
  • Best for: Every article page. This is the default recirculation pattern on almost every news site for a reason.
  • API mode: “More like this” — personalized recommendations anchored to the article just finished.

The experience

The story ender is the module that sits immediately after the article body, typically labeled “Read next,” “You might also like,” or “More from [section].” It’s the most common recirculation surface on the web, and with personalized recommendations powering it, it becomes substantially more effective than a static “latest from this section” list.

A typical layout shows four to six cards in a grid, each with thumbnail, headline, section, and optionally a timestamp. On mobile, this often becomes a vertical stack or a horizontal swipe. The visual treatment should be clearly distinct from the article body — a different background tone, a section heading, a rule above — so readers understand they’ve moved from the article into recirculation.

Unlike the inline recommendation, which is disciplined to a single item, the end cap is where you can be a little more generous. A reader who made it to the bottom has finished the article; offering multiple options respects that they may want something similar, something from the same author, or a palate-cleansing change of topic.

How to implement it

Same anchored call as the inline recommendation, but request more items:

GET /recommendations/v1/recommendations?site_id=my-site&user_id=user-abc&item_id=ARTICLE-123
  • Mix personalized with editorial if you want. Some publishers render the top three API results followed by an editor’s-pick slot or a “Most read” item. That hybrid approach keeps the module feeling curated while still getting the personalization lift.
  • Exclude the anchor article from the rendered list. The API can return it; you don’t want to show a reader the article they just finished.
  • Track clicks and log impressions. The end cap is a high-volume surface; the event data it generates is some of the most valuable training signal you’ll have.

Things to watch for

If you already have an end-cap module powered by a static rule (“latest from this section,” “more from this author”), consider A/B testing the personalized version against it rather than cutting over cold. It’s a clean comparison and a natural way to build internal confidence in the recommendations quality.

Watch the overlap between the inline recommendation and the end cap. If both surfaces are live on the same article and both are anchored to the same item_id, they’ll pull from the same result set. Request more results than you need in the end cap and filter out whatever the inline recommendation has already shown.

Surface 05  ·  “For You” email

Personalized recommendations delivered directly to a reader’s inbox — on their schedule, not yours.

  • UX goal: Drive reengagement and return visits by delivering a curated, personalized digest without requiring the reader to open the app or site first.
  • Best for: Publishers with an established newsletter program and an identified, emailable audience.
  • API mode: General personalized recommendations (all-personalized variant) or anchored recommendations (editorial-plus-personalized variant).

The experience

There are two strong patterns for using recommendations in email, and many publishers will want to run both.

The first is the fully personalized “For You” digest — an email that consists entirely of recommended articles for each subscriber, typically six to ten items, sent on a regular cadence (daily or several times a week). It’s a powerful reengagement tool: the content is different for every subscriber, and the cadence keeps your publication in the reader’s inbox without requiring editorial production effort beyond the template itself.

The second pattern is a hybrid — what’s often called a “1+3” or “1+N” email. An editor authors a single anchor piece (a top story, a “pick of the day,” a staff column), and the rest of the email is filled with personalized recommendations, often anchored to that lead story. The editorial voice does the work of signaling why this email is worth opening; the personalization does the work of making the rest of the email relevant to each individual reader. For publishers who already send editor’s-pick emails, this pattern is a natural evolution — it keeps the editorial lead and dramatically expands what the tail of the email can do.

Both patterns live or die on the quality of the subject line and the top item. Neither is a substitute for editorial judgment on the lead — they’re a way to extend its reach.

How to implement it

At send time, iterate over your subscriber list and call the Recommendations API once per subscriber. For the fully personalized variant, call without an anchor. For the 1+N variant, anchor to the editor’s selected item:

GET /recommendations/v1/recommendations?site_id=my-site&user_id=user-abc[&item_id=editor-pick-id]
  • Include UTM parameters on every link, and make sure clicks back to your site still resolve to a user_id your front-end can recognize. You want the click events from email to feed back into the same model that powers your on-site surfaces.
  • Request more items than you’ll render. Email templates are visually rigid; if one of your six slots fails to hydrate, you want a seventh ready to take its place rather than sending a broken layout.
  • Send a click event on link click, ideally via a redirect endpoint that logs the event server-side to your CDP (and forwards to the Collector) before forwarding the reader to the article. This keeps email-driven engagement in the same training signal as on-site engagement.
  • For the 1+N pattern, pass the editor’s lead item as the item_id anchor so the personalized tail is topically related, not a grab bag.

Things to watch for

Email deliverability and list hygiene matter as much as personalization quality. A perfectly personalized email that lands in spam is a wasted call. Make sure your email infrastructure is solid before investing heavily in the content selection layer.

Be thoughtful about cadence. A fully personalized daily digest can feel algorithmic in a way some readers bristle at; framing it as “your briefing” or pairing it with a clear sender identity (“From the newsroom”) softens that. Watch unsubscribe rates on the fully personalized variant especially.

If you run both patterns, hold them on different sending schedules so subscribers don’t receive a personalized digest and a 1+N email on the same day from the same publisher.

Choosing where to start

Five surfaces is a lot to ship at once, and you shouldn’t. Most customers see the strongest return on a sequenced rollout that builds signal and confidence before expanding reach:

  • Start with the article end cap. It’s the highest-volume, lowest-risk surface. Every article page gets one, readers are already expecting a recirculation module there, and it generates dense click data that trains the model for every other surface.
  • Add the homepage For You module next. Higher visibility, but the end cap has already been collecting signal by the time you ship it, so the experience on day one is meaningfully better than launching the homepage cold.
  • Layer in inline article recommendations once you’re confident in the model’s relevance on longer-form content. The UX bar is higher here — a bad inline recommendation is more jarring than a bad end cap.
  • Ship the For You email program alongside or after the homepage. Email drives return visits that further enrich the training signal, so it compounds well with on-site surfaces.
  • Build the dedicated For You tab or landing page last. It has the highest quality bar because readers have explicitly opted into personalized content. Wait until the model has enough signal that a full-screen experience stands on its own.

The feedback loop is the product

A pattern that’s worth underlining: every surface in this guide gets better because of every other surface. A click on the homepage rail improves the inline recommendation three articles later. An engaged_read event on a feature story sharpens the email digest tomorrow morning. The “For You” tab, if you ship it, becomes the densest source of training data you have.

That only works if you’re consistent about sending events back. A deployment that reads from the Recommendations API without ever posting events to the Collector API is a deployment whose quality never improves. Treat the click event as a mandatory half of every recommendation render, not an optional enhancement.

Further reading

For the full API reference, authentication and token provisioning, event schemas, and detailed onboarding guidance, see the developer documentation:

Content Recommendations API Developer Guide

Arc XP CMS customers should also ask their Technical Account Manager about the IFX Recipe, which wires the content sync webhook end-to-end without custom code.