Embeddable Events Embed Core and above

Embeddables emit browser events via window.postMessage. You can listen for these messages to track learner progress, react to authoring actions, and handle lifecycle events such as ready or error states.

How it works

Coassemble sends messages from inside the embedded iframe to your host application. Each embeddable page in this docs site includes an Emitted Events table listing the events that can be sent for that embeddable.

In your host app, add one message listener on window, then filter events by iframe source and origin before handling the payload.

Listener example

const iframe = document.getElementById('your-iframe-id');
const expectedOrigin = new URL(iframe.src).origin;

function onEmbedMessage(event) {
    if (event.origin !== expectedOrigin) return;
    if (event.source !== iframe?.contentWindow) return;
    if (!event.data || typeof event.data !== 'object') return;

    const payload = event.data;

    if (payload.type === 'session') {
        if (payload.event === 'ready') {
            console.log('Embeddable ready');
        }
    } else if (payload.type === 'course') {
        if (payload.event === 'progress') {
            console.log('Progress update', payload);
        }
    } else if (payload.type === 'back') {
        console.log('Back clicked');
    }
}

window.addEventListener('message', onEmbedMessage);

Payload shape

Field	Type	Description
`type`	`string`	Event group, such as `session`, `course`, `screen`, or `back`.
`event`	`string` (optional)	Event name within the group, such as `ready`, `progress`, or `completed`.
`data`	`object`	Some events include extra metadata. Handle payloads defensively and check fields before use.

Best practices

Verify event.origin is as expected before handling data.
Verify event.source is your iframe to ignore unrelated messages.
Use the type and event fields to route logic in your app.
Remove listeners on unmount / cleanup to avoid duplicate handlers.