To host a Flex experience with server-side rendering, your server fetches the experience's manifest, renders its HTML into your page, and loads the
flex-ssr.js hydration script to make it interactive. There is no drop-in snippet, so you build this into your own server, framework, or CMS. The steps below walk you through it.
Important: Server-side rendering is currently in beta. Reach out to your CSM for more information about gaining access.
What Is Server-Side Rendering?
Server-side rendering has your server render a published experience's HTML directly into your page before it reaches the browser, then load a hydration script in the browser. Hydration is the step that makes the server-rendered HTML interactive. Because the experience HTML is part of your initial page response, server-side rendering gives the best SEO, the fastest first paint, and full control of the page head.
Server-side rendering is one of two delivery modes that don't require an iframe, the other being Inline. To compare and decide which delivery method fits your goal, see How Should I Deliver My Published Flex Experience?
How Do I Build a Server-Side Rendering Integration?
Note: Throughout this article, acme.ceros.site/spring-launch/ is a placeholder. Replace it with the real URL of your own published experience.
Server-side rendering is a build-it-yourself integration, so there is no drop-in snippet like the iFrame or Inline delivery methods. At a high level, your server, framework, or CMS does the following:
Fetch the experience's manifest from its URL.
Read the deep-link query parameter to decide which page of the experience to render.
Render that page's HTML into your response.
Include the CSS and JS manifest lists for server-side rendering mode, including the
flex-ssr.jshydration runtime, plus the experience's styles, webfonts, and any customer scripts.Populate the page head yourself, since with server-side rendering you own the
<head>, including meta tags, styles, and fonts.
A minimal server-side rendering page looks like this:
<html lang="en"> <head> <!-- meta, styles, and webfonts from the manifest --> </head> <body> <!-- server-rendered experience HTML from the manifest --> <script src="https://assets.ceros.site/js/flex-ssr.js"></script> </body> </html>
How Do I Capture Analytics With Server-Side Rendering?
With server-side rendering, Ceros does not set up Google Analytics or GTM for you. Instead, the experience fires analytics events on your page, and you listen for them and forward them to your analytics tool.
// Listen for Flex analytics events on your page document.body.addEventListener('ceros-analytics-event', (e) => { const { eventType, experienceName, pageName, componentName } = e.detail // forward to GA or your analytics here })
How Do I Deep-Link to a Specific Page?
Deep-linking lets a multi-page experience open to a specific page from a shared link, and it makes the browser back and forward buttons move between experience pages. The link carries a per-embed query parameter in the form cer_<experienceSlug>=<pageSlug>.
In server-side rendering, deep-linking works automatically, but to avoid a brief flash of the first page, your server should read the cer_<experienceSlug> query parameter and pre-render the matching page. Without that step, deep links still work, and the correct page swaps in after a brief flash.
Server-Side Rendering Beta Limitations
Server-side rendering is in beta, and several limitations apply in v1 that do not affect Standalone or iFrame:
position: fixedandposition: stickydo not work yet. Elements set to fixed or sticky positioning will not pin correctly because the experience no longer controls its own scroll container. This is a known issue.There is no built-in cookie-consent UI. Server-side rendering does not provide a cookie-consent interface, so your own consent management applies.
Flex sets no cookies in server-side rendering. The only cookies present are those your own injected code sets, such as your analytics or tracking pixels.
Password-protected experiences cannot be embedded with server-side rendering. Experiences that require a password are not supported in server-side rendering in v1. Use a standalone link or the iFrame embed for those.
Tip: For the fixed and sticky limitation, set the wrapping div to a fixed height, for example, 800px, or 100vh for full viewport height, to force the experience to scroll internally so fixed and sticky elements pin correctly.