Skip to main content

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.typeFires when
experience.openThe experience first becomes visible
page.viewA page is shown, including in-place swaps
component.clickA clickable component is clicked
link.clickA link is followed
component.hoverA component is hovered
video.playVideo playback starts
video.progress.milestoneVideo 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.

What counts as a click

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) and flexAnalytics.onExperience(filter, callback) deliver the same analyticsEvent as analytics.event, with experience carrying only its url.
  • flex.analytics.event, a window event carrying the same { experience, analyticsEvent } detail. ceros.analytics.event is a deprecated alias.
  • ceros-analytics-event, a flat, legacy-compatible CustomEvent on document.body (and window on Inline and SSR). Its detail.eventType uses hyphenated names; experienceName, pageName, pageNum and isFlexExperience are always present, with componentName, page, url or videoProgressPct per type.
ceros-analytics-event eventTypeanalyticsEvent.type
page-viewpage.view
component-clickcomponent.click
component-hovercomponent.hover
link-clicklink.click
experience-openexperience.open
video-playvideo.play
video-progress-percentvideo.progress.milestone