Flex Inline
Flex Inline puts the experience directly on your page — no iframe, no nested
document. You paste a two-line snippet, and flex-client.js loads the Flex
runtime that renders the experience into an open shadow root attached to
your marker <div>.
<div
data-flex-inline
data-flex-manifest-url="https://acme.ceros.site/spring-launch/manifest.v1.json"
data-flex-height="auto"
></div>
<script src="https://assets.ceros.site/js/flex-client.js"></script>
Get the snippet from Embed in Flex, or from the
/experiences/{resourceId}/embed-codes endpoint in the API reference.
How it works
flex-client.jsfinds the first<div data-flex-inline>on the page and fetches its manifest — the JSON document atdata-flex-manifest-urlthat describes the pre-rendered HTML, styles, webfonts, and scripts for one page of the experience.- The manifest names the Flex runtime the experience was published with, and
flex-client.jsloads that runtime from the versioned Ceros CDN (assets.cdn.ceros.site). - For each
<div data-flex-inline>, the runtime attaches an open shadow root, injects a CSS reset and the manifest's styles into it, and writes the experience markup inside. - It registers the experience's custom elements, hydrates, and starts interactions.
- A
MutationObserverkeeps watching your page, so markers added later — by a single-page app after navigation, say — are picked up automatically.
Which version runs
An experience runs the Flex runtime it was published with, not whatever Flex released since, so its markup, styles, and code always come from the same release. It moves to a newer runtime when it is re-rendered: when you republish it, or when Flex re-renders it after a release.
A page loads one runtime, chosen by its first experience, and that runtime renders every experience on the page. Right after a Flex release, two experiences on one page can briefly need different runtimes, because each one is re-rendered on its own; when that happens the browser console logs an error naming both. It clears once both have been re-rendered and the page is reloaded.
Content Security Policy
If your page sets a Content-Security-Policy, allow both Ceros script hosts in
script-src: assets.ceros.site serves flex-client.js, and
assets.cdn.ceros.site serves the runtime it loads. The runtime's styles and
fonts come from assets.cdn.ceros.site too, so allow it in style-src and
font-src as well. A blocked runtime is reported in the browser console with
its URL.
Loading faster
An optional hint in your page's <head> opens the connection to the CDN that
serves the runtime, its styles, and fonts before flex-client.js asks for
them:
<link rel="preconnect" href="https://assets.cdn.ceros.site" crossorigin />
Don't preload the manifest or the runtime. flex-client.js requests the
manifest with its own query string, so a preload of the snippet's URL is never
reused and downloads the manifest twice. The runtime's URL changes whenever the
experience is re-rendered on a new release.
Sizing
The experience width is sized to its container. Give the marker
<div> the width you want and the experience scales to fit.
You have two options for the experience height:
- Keep
data-flex-height="auto"on the<div>if you'd like the container to adjust automatically to the full height of the content. - Add a height style tag,
style="height: 200px;", to the<div>to use a fixed size and force the experience content to scroll.
Older snippets use data-embed-height="auto", which keeps working.
Why a shadow root
It's the middle ground between an iframe and dumping markup into your page.
- Your CSS can't leak in. The experience renders exactly as designed, even
if your site sets
* { box-sizing: content-box }or styles every<p>. - The experience's CSS can't leak out. Its component styles stay scoped to the shadow root and never repaint your navigation or footer.
- It's still one document. No iframe scroll-jail, no separate window, no
postMessagefor basic things. The experience participates in your page's layout and scrolling like any other element.
The shadow root is open, so you can reach into it from your own scripts
(el.shadowRoot) if you need to.
Multiple experiences on one page
One marker per experience, one script tag:
<div
data-flex-inline
data-flex-manifest-url="https://acme.ceros.site/spring-launch/manifest.v1.json"
data-flex-height="auto"
></div>
<div
data-flex-inline
data-flex-manifest-url="https://acme.ceros.site/q3-report/manifest.v1.json"
data-flex-height="auto"
></div>
<script src="https://assets.ceros.site/js/flex-client.js"></script>
Each hydrates independently, with its own interactions.
Multi-page experiences
A multi-page experience swaps pages in place, without reloading your page. Links authored in the experience are intercepted by a small client-side router.
Those links are written as query parameters on your URL, not Ceros':
?cer_<experienceSlug>=<pageSlug>
So a link to the pricing page of spring-launch renders as
?cer_spring-launch=pricing. This is deliberate: the experience is a component
on a page it doesn't own, so middle-click, cmd-click, and "Copy link address"
have to resolve against your URL. Someone who opens such a link in a new tab
lands on your page with the experience already on the right page.
If your server or router does anything with query parameters, leave cer_*
parameters alone.
What Ceros does not do
Ceros never touches your page's <head> or <body>. Two consequences:
- Custom head/body HTML you attached to the experience in Flex is not emitted. Analytics snippets, consent scripts, fonts, and meta tags you configured there won't run. Put them on your page instead.
- SEO, meta, and OpenGraph tags are yours to provide. The experience isn't in your initial HTML, so it doesn't contribute to indexing either. If that matters, use Flex SSR.
Analytics
flex-client.js puts window.flexEmbedSdk on your page, the host-page SDK
for every delivery mode:
<script src="https://assets.ceros.site/js/flex-client.js"></script>
<script>
window.flexEmbedSdk.on('analytics.event', ({ analyticsEvent }) => {
gtag('event', analyticsEvent.type.replace(/\./g, '_'), analyticsEvent.data)
})
window.flexEmbedSdk.setCookieConsent('*', ['necessary', 'performance'])
</script>
To report to Ceros analytics as well, add data-ceros-analytics="enabled" to
the marker <div>. Ceros doesn't load Google Analytics or Google Tag Manager
inside the experience; forwarding events to them is your page's job.
See Analytics events for event names, payload shapes and filtering, and Cookie consent for consent and what Flex stores in the browser.
Scripting the experience
To drive components from your own JavaScript, use the
Flex Experience SDK. On Flex Inline the experience lives
inside a shadow root, so pass the container to connect() — the SDK reaches
through for you:
<script type="module">
import { connect } from 'https://assets.ceros.site/js/flex-experience-sdk.js'
const experience = await connect(document.querySelector('[data-flex-inline]'))
experience.findByLocator('hero-video').media.play()
</script>
Because page changes are in-place swaps, your handle goes stale on every swap.
Re-connect on the flex.page.change window event — see
the SDK's delivery modes page.
When to use it
- You want the experience to feel like part of your page, with no iframe.
- Adding a
<script>tag is all the access you have to the host page. - Your page forwards events to your own analytics tools; Ceros doesn't load Google Analytics or Google Tag Manager inside the experience.
When to reach for something else
- You need the experience in your initial HTML for SEO or LCP → Flex SSR.
- You need Ceros to load Google Analytics, Google Tag Manager, or error monitoring inside the experience → iframe embed.