Analytics events
Every embed script puts the same SDK on your page: window.flexEmbedSdk.
embed.v1.js (iframe embed), flex-client.js
(Flex Inline) and flex-ssr.js (Flex SSR)
all install it, so the code you write to listen for experience events or
pass cookie consent is the same whichever way you embed. Switching an experience
from the iframe to Inline or SSR doesn't touch it.
There is one SDK per page, created by whichever Ceros script runs first. A page that mixes iframe and Inline embeds reaches every experience through the same calls.
Getting the SDK
The SDK exists once its script has run. embed.v1.js and flex-client.js are
plain scripts, so code placed after them can use window.flexEmbedSdk
directly. flex-ssr.js is emitted as <script type="module" defer>, which
runs after every inline <script> on the page, so an inline script that
calls window.flexEmbedSdk.on(...) at the top level throws a TypeError.
Each script dispatches flexEmbedSdkAvailable on document when it creates
the SDK. This helper works in every mode and from a tag manager:
function withFlexEmbedSdk(callback) {
if (window.flexEmbedSdk) {
callback(window.flexEmbedSdk)
} else {
document.addEventListener(
'flexEmbedSdkAvailable',
(event) => callback(event.detail.flexEmbedSdk),
{ once: true },
)
}
}
The SDK exists before any experience mounts, so subscribing through the helper never misses an event.
Subscribing to events
withFlexEmbedSdk((sdk) => {
// Every experience on the page.
const off = sdk.on('analytics.event', ({ experience, analyticsEvent }) => {
gtag('event', analyticsEvent.type, analyticsEvent.data)
})
off() // every subscription returns an unsubscribe function
})
Filtering by experience
onExperience takes a filter before the event name:
withFlexEmbedSdk((sdk) => {
// A substring match…
sdk.onExperience('spring-launch', 'analytics.event', ({ analyticsEvent }) => {
dataLayer.push({ event: analyticsEvent.type, ...analyticsEvent.data })
})
// …a RegExp…
sdk.onExperience(/campaigns\/2026\//, 'analytics.event', handler)
// …or everything.
sdk.onExperience('*', 'analytics.event', handler)
})
Filter on the experience slug. What the filter is matched against depends
on the embed: an iframe embed's experience.url is the published experience
URL (the iframe src), while an Inline or SSR experience has no iframe, so its
experience.url is the manifest URL and the filter also matches its slug.
The slug appears in all of these, so a slug filter matches the same experience
in every mode, unless an iframe embed points at a custom domain that serves the
experience without its slug in the path. A full-URL pattern written for one
mode won't match the other.
Experiences arriving and leaving
withFlexEmbedSdk((sdk) => {
sdk.on('experience.added', ({ experience }) => {
console.log(experience.delivery, experience.url) // 'iframe' | 'inline' | 'ssr'
})
sdk.on('experience.removed', ({ experience }) => {
/* … */
})
})
experience.embed is the element you placed on the page: the <div> for the
iframe embed and Flex Inline, the wrapper for Flex SSR. experience.iframe is
the iframe, or undefined on Inline and SSR.
Event types
analyticsEvent.type | Fires when |
|---|---|
experience.open | The experience first becomes visible |
page.view | A page is shown, including in-place swaps |
component.click | A clickable component is clicked |
link.click | A link is followed |
component.hover | A component is hovered |
video.play | Video playback starts |
video.progress.milestone | Video playback crosses a progress milestone |
On Flex Inline, events begin once the experience has rendered; on Flex SSR, once it has hydrated.
experience.open fires once per experience per tab, and again on a refresh.
Until the viewer gives performance consent it fires on each page load,
because Flex does not record that it fired until then.
component.click fires only for components the author made clickable — one
carrying a click or pointer-press interaction (on itself or an ancestor), a
carousel control, or a link. That's the same set that shows a pointer cursor in
the viewer. Clicks on inert layers — a bare shape, or one whose only interaction
is an entrance animation, hover effect, or scroll effect — are not reported.
Payload shape
analytics.event listeners receive { experience, analyticsEvent }:
{
"experience": {
"delivery": "inline",
"url": "https://acme.ceros.site/product-showcase/features/manifest.v1.json",
"slug": "product-showcase",
// embed, iframe — see "Experiences arriving and leaving"
},
"analyticsEvent": {
"type": "component.click",
"timestamp": 1718800000000,
"eventId": "…",
"data": {
"componentName": "Buy now",
"componentId": "…",
"componentType": "button",
"position": { "x": 10, "y": 20 },
},
"context": {
"page": { "id": "features", "slug": "features", "number": 2 },
"experience": {
"id": "acme/product-showcase",
"slug": "product-showcase",
"accountSlug": "acme",
},
},
},
}
Forwarding to GA4
<script>
window.dataLayer = window.dataLayer || []
function gtag() {
dataLayer.push(arguments)
}
function withFlexEmbedSdk(callback) {
if (window.flexEmbedSdk) {
callback(window.flexEmbedSdk)
} else {
document.addEventListener(
'flexEmbedSdkAvailable',
(event) => callback(event.detail.flexEmbedSdk),
{ once: true },
)
}
}
withFlexEmbedSdk((sdk) => {
sdk.on('analytics.event', ({ analyticsEvent }) => {
gtag('event', analyticsEvent.type.replace(/\./g, '_'), {
...analyticsEvent.data,
experience_slug: analyticsEvent.context?.experience?.slug,
page_slug: analyticsEvent.context?.page?.slug,
})
})
})
</script>
GA4 event names can't contain dots, hence the replace. The block can sit
anywhere on the page, before or after the embed script.
Reporting to Ceros analytics
The iframe embed reports to Ceros analytics unless its <div> carries
data-ceros-analytics="disabled". Flex Inline and Flex SSR report only when the
embed is marked data-ceros-analytics="enabled": on the Inline container, or on
the SSR wrapper that carries data-flex-manifest-url.
<div
data-flex-inline
data-flex-manifest-url="https://acme.ceros.site/spring-launch/manifest.v1.json"
data-flex-height="auto"
data-ceros-analytics="enabled"
></div>
<script src="https://assets.ceros.site/js/flex-client.js"></script>
A marked embed reports the same default analytics a standalone experience does.
Nothing is reported when the account has Ceros analytics turned off, when your
page URL carries ?ceros-analytics=disabled (useful on a CMS preview URL), or
when the experience requires consent your page hasn't given through
setCookieConsent. window.flexHostAnalytics.stop() stops reporting for the
page.
Either way, the events above keep firing on your page. Ceros analytics doesn't load Google Analytics or Google Tag Manager on Inline and SSR; forwarding to those stays your page's job. For what reporting keeps in the visitor's browser, see Cookie consent.
Older APIs
These keep working and need no changes, but new code should use
window.flexEmbedSdk.
window.flexAnalytics(Flex Inline and Flex SSR only):flexAnalytics.on(callback)andflexAnalytics.onExperience(filter, callback)deliver the sameanalyticsEventasanalytics.event, withexperiencecarrying only itsurl.flex.analytics.event, awindowevent carrying the same{ experience, analyticsEvent }detail.ceros.analytics.eventis a deprecated alias.ceros-analytics-event, a flat, legacy-compatibleCustomEventondocument.body(andwindowon Inline and SSR). Itsdetail.eventTypeuses hyphenated names;experienceName,pageName,pageNumandisFlexExperienceare always present, withcomponentName,page,urlorvideoProgressPctper type.
ceros-analytics-event eventType | analyticsEvent.type |
|---|---|
page-view | page.view |
component-click | component.click |
component-hover | component.hover |
link-click | link.click |
experience-open | experience.open |
video-play | video.play |
video-progress-percent | video.progress.milestone |