Embedding Flex experiences
Every published Flex experience can be delivered four different ways. They all render the same experience from the same publish pipeline — what changes is where the experience's HTML comes from and how much of the page you control.
| Mode | You write | The experience lives in | First paint is server-rendered |
|---|---|---|---|
| Standalone | Nothing — just share the URL | A page Ceros hosts | Yes |
| Iframe embed | A <div> and a <script> | An <iframe> on your page | Yes (inside the iframe) |
| Flex Inline | A <div> and a <script> | A shadow root on your page | No — fetched in the browser |
| Flex SSR | Server code that composes the page | Your page's own markup | Yes |
Choosing a mode
Work down this list and stop at the first match.
You don't need it on your own site. Use Standalone. Publish, share the URL, done. It's also the canonical URL for SEO and the target every other mode ultimately points back to. While not technically embedding, it's important to mention so that the differences can be understood.
You need analytics inside the experience or better security. Use the iframe embed. It is currently the only mode that ships Google Analytics, Google Tag Manager, and error monitoring inside the experience. It's also the safest choice when your site has aggressive global CSS, or from a security perspecitve, because the iframe is a hard boundary.
You want it to feel native, and a <script> tag is all you can add. Use
Flex Inline. No iframe, no scroll-jail, no nested
document — the experience renders into a shadow root on your page, so your CSS
and the experience's stay out of each other's way. The trade-off is that the
browser fetches the experience after your page loads, so it isn't in your
initial HTML.
You control your server and want the experience in the first byte of HTML.
Use Flex SSR. Your server fetches the experience's manifest,
writes the pre-rendered markup straight into its own response, and the browser
loads one small hydration script. This is the mode to pick for SEO, for the
fastest LCP, and when you want the experience to sit inside your own <head>,
structured data, and caching rules. It is also the most work.
Full comparison
| Concern | Standalone | Iframe | Flex Inline | Flex SSR |
|---|---|---|---|---|
| Integration effort | None | Paste a snippet | Paste a snippet | Write server code |
| HTTP documents on the page | 1 | 2 (page + iframe) | 1 | 1 |
| CSS isolation | n/a | iframe | Shadow DOM | None — shares your styles |
| JS isolation | n/a | Separate window | Shared window | Shared window |
| In your initial HTML payload | n/a | No (iframe loads it) | No | Yes |
| Indexable without running JavaScript | Yes | Only the iframe URL | No | Yes |
| GA / GTM / error monitoring inside | Yes | Yes | Not yet (beta) | Not yet (beta) |
| Analytics events on your page | n/a | Yes | Yes | Yes |
| Sizing | Viewport | Iframe box | Its container | Its container |
| Status | GA | GA | Public beta | Public beta |
Getting your embed code
For the iframe and Flex Inline modes, Flex generates the snippet for you — open
the experience in Flex and choose Embed. You can also fetch embed codes
programmatically from the
/experiences/{resourceId}/embed-codes endpoint in the API reference.
Flex SSR has no paste-able snippet, because your server does the assembly. What you need instead is the experience's manifest URL — see Flex SSR § Finding the manifest URL.
Related
- Analytics events — subscribing to experience events from your page (Flex Inline and Flex SSR).
- Flex Experience SDK — scripting a published experience: find the components you designed and drive them at runtime. See its delivery modes page for how the SDK differs across the modes above.
Flex Inline and Flex SSR are in public beta. The manifest contract they read
is versioned (schemaVersion: "1") and changes to it are additive.