Composable Personalization with Contentful Studio

Once pages could resolve a visitor’s nearest office on the server, the next request was richer: marketing wanted different content for different locations — not just swapped words, but entirely different sections. A flagship office might lead with a video; another might use a half-screen image; everywhere else should see a sensible default.

This is the authoring layer on top of Server-Side Personalization, which resolves the facility code this system renders against.

Without a composition primitive for this, every location variant becomes a burden:

• Each variation means a separate page to build and maintain, or a code change per layout.
• Editors can’t target content by location themselves — they have to file engineering work.
• Toggling variants in the browser reintroduces the flicker and layout shift that server-side rendering was meant to eliminate.

The goal was to let editors build location-specific layouts with the same atoms they already use, and have the right one chosen on the server.

• Designed and built the Segments Container and Segment Item atoms in Contentful Studio
• Defined the facility-code matching and fallback rules
• Implemented server-side selection so only the matching segment renders
• Shaped the authoring model and guidance so it stays predictable for editors

A “smart folder” for segments

The Segments Container behaves like a smart folder: editors drop it onto a page, then add a Segment Item for each variation. Each Segment Item has a Facility IDs field and can contain any atoms — images, text, buttons, whole sections — just like anywhere else in Studio. It’s composition, not configuration.

The match logic

At render time the container looks at the visitor’s resolved facility code and shows the single best match:

• A Segment Item listing 0001, 0002 is shown to visitors near those offices; another listing 0003, 0004 targets a different set of locations.
• A Segment Item with an empty Facility IDs field is the default — everyone who doesn’t match a targeted segment sees it.
• Facility IDs are matched exactly, so codes are entered without extra spaces.
• IDs are kept unique per segment, and if more than one somehow matches, the first one wins.

Always keep a default

The default (empty) segment is the safety net. If a visitor’s office doesn’t match any targeted segment and there’s no default, the container simply renders nothing — leaving a hole in the page. The guidance is therefore to always include one empty segment as a catch-all, and to put the shared content there so only the genuinely special locations need their own segment.

Editor view vs. live site

In Studio, editors see all segments stacked so they can edit every location’s version side by side. On the live site the server hides everything except the one segment that matches the visitor.

Rendered on the server

Selection happens server-side using the facility code from the personalization pipeline, so the matching layout is in the HTML from the first paint. Different offices can get fundamentally different renderings — video, image background, half-screen — with no client-side flicker and no layout shift.

Personalization scales only when the people closest to the content can author it. By making location targeting a composition primitive in Studio — and resolving the match on the server — marketing can ship meaningfully different experiences per location without new pages, new components, or a regression in performance and SEO.