Embed Events

Embed events are signals emitted by embedded analytics components that the host application can listen to and act on. They form the coordination layer between the analytics experience and the surrounding product – enabling the host app to respond when a user interacts with a chart, changes a filter, or triggers an export.

Without embed events, embedded analytics operate as a black box. The host app renders a dashboard; the user interacts with it; the host app knows nothing about what happened inside. Embed events open that black box and make the interaction two-directional.

What events are available

The specific events vary by analytics platform, but most mature embedded analytics tools expose a common set.

Dashboard loaded. Fires when the embedded dashboard has fully rendered and is interactive. The host app uses this to hide loading placeholders, trigger onboarding tooltips, or log time-to-interactive metrics.

Filter changed. Fires when a user selects, clears, or modifies a filter value within the embedded analytics. This lets the host app synchronize its own UI state – updating a sidebar, adjusting a header, or reflecting the filter selection in the URL for deep linking.

Chart clicked. Fires when a user clicks on a specific data point – a bar in a bar chart, a row in a table, a segment in a pie chart. The event payload typically includes the clicked value and its dimensional context. The host app can use this to navigate to a detail page, open a modal, or trigger a workflow.

Drill-down triggered. Fires when a user drills into a data point to see underlying detail. The host app may want to track this for usage analytics, adjust the page layout to accommodate expanded content, or apply additional context from outside the embedded component.

Export requested. Fires when a user initiates a PDF, CSV, or image export. The host app can intercept this to apply branding, append disclaimers, log the export for compliance, or route it through a custom delivery mechanism.

How the host app subscribes

The subscription mechanism depends on the integration method.

SDK event listeners. When using a JavaScript SDK, the host app registers callback functions for specific event types. The SDK invokes the callback with an event payload containing the relevant data – which filter changed, what value was selected, which chart was clicked, and the associated data point.

analytics.on('filterChanged', (event) => {
  updateHostFilters(event.filterName, event.value);
});

analytics.on('chartClicked', (event) => {
  navigateToDetail(event.dimension, event.value);
});

postMessage for iframes. When analytics are embedded via iframe, the embedded content sends messages to the parent window using the browser's postMessage API. The host app listens on window.addEventListener('message', handler) and parses the event data from the message payload. This approach requires careful origin validation to prevent cross-origin security issues.

Callback functions. Some SDKs accept callback functions at initialization time rather than using an event listener pattern. The distinction is minor – callbacks are invoked directly; event listeners allow multiple subscribers. Either works.

Use cases

Embed events enable several patterns that turn embedded analytics from passive displays into integrated product features.

Navigate on click. A user clicks a customer name in an embedded table. The host app catches the click event and navigates to that customer's detail page in the main product. The analytics component becomes a navigation surface rather than just a visualization.

Synchronized filters. The host app has its own filter bar – a date picker, a region selector, a product dropdown. When the user changes a filter in the host UI, the host app pushes the value into the embedded analytics. When the user changes a filter inside the embedded analytics, the embed event pushes the value back to the host app. Both stay in sync.

Usage logging. Every filter change, chart click, and export request generates an event. The host app logs these to its own analytics pipeline. This data reveals which dashboards customers actually use, which charts drive engagement, and where users drop off – product intelligence that the embedded analytics vendor may lack natively.

Trigger workflows. A user sees an anomaly in a chart – a spike in error rates, a drop in conversion. They click the data point. The host app catches the event and opens a workflow: create a Jira ticket, send a Slack alert, start an investigation. The embedded chart becomes the starting point for action rather than just observation.

Implementation considerations

Event payloads should be typed and documented. Relying on unstructured event data creates brittle integrations that break when the analytics platform updates its event schema.

Test event handling under real conditions – slow networks, partially loaded dashboards, rapid user interactions. Events that fire before the host app's listener is registered are silently lost. Events that fire too frequently (like filter changes during a drag interaction) need debouncing.

Embed events work best when the embed portal architecture supports them natively, with consistent event schemas across dashboard types and visualization components.