Embed Events API

When embedding Supademo demos in your application via iframe, you can listen for events to track user progress and trigger actions in your parent application.

Overview

Supademo emits postMessage events to the parent window, allowing you to:

• Detect when a demo starts, progresses, or completes

• Track which slide the user is viewing

• Close modals or trigger navigation when a demo finishes

• Build custom progress indicators

Quick Start

Add this listener to your parent page:

window.addEventListener('message', (event) => {
  // Only handle Supademo events
  if (event.data?.source !== 'Supademo') return;

  console.log('Supademo event:', event.data.type, event.data.payload);
});

Available Events

Supademo:load

Fired when the demo initially loads in the iframe.

Payload:

Field	Type	Description
demoId	string	Unique demo identifier
title	string	Demo title
totalSlides	number	Total number of slides

Example:

{
  source: "Supademo",
  type: "Supademo:load",
  payload: {
    demoId: "abc123",
    title: "Getting Started Guide",
    totalSlides: 5
  }
}

---

Supademo:started

Fired when the user first interacts with the demo (clicks, navigates, etc.).

Payload:

Field	Type	Description
demoId	string	Unique demo identifier
title	string	Demo title

Example:

{
  source: "Supademo",
  type: "Supademo:started",
  payload: {
    demoId: "abc123",
    title: "Getting Started Guide"
  }
}

---

Supademo:slideChange

Fired whenever the user navigates to a different slide.

Payload:

Field	Type	Description
demoId	string	Unique demo identifier
currentSlide	number	Current slide number (1-indexed)
totalSlides	number	Total number of slides
isFirstSlide	boolean	true if on the first slide
isLastSlide	boolean	true if on the last slide

Example:

{
  source: "Supademo",
  type: "Supademo:slideChange",
  payload: {
    demoId: "abc123",
    currentSlide: 3,
    totalSlides: 5,
    isFirstSlide: false,
    isLastSlide: false
  }
}

---

Supademo:progress

Fired alongside slideChange with a percentage value for building progress bars.

Payload:

Field	Type	Description
demoId	string	Unique demo identifier
percentage	number	Completion percentage (0-100)
currentSlide	number	Current slide number (1-indexed)
totalSlides	number	Total number of slides

Example:

{
  source: "Supademo",
  type: "Supademo:progress",
  payload: {
    demoId: "abc123",
    percentage: 60,  // Slide 3 of 5 = 60%
    currentSlide: 3,
    totalSlides: 5
  }
}

---

Supademo:completed

Fired when the user reaches the final slide of the demo.

Payload:

Field	Type	Description
demoId	string	Unique demo identifier
title	string	Demo title
completedAt	string	ISO 8601 timestamp

Example:

{
  source: "Supademo",
  type: "Supademo:completed",
  payload: {
    demoId: "abc123",
    title: "Getting Started Guide",
    completedAt: "2025-01-15T10:30:00.000Z"
  }
}

---

Supademo:close

Fired when the user presses the ESC key while viewing the demo.

Payload: None

Example:

{
  source: "Supademo",
  type: "Supademo:close"
}

Common Use Cases

Close Modal on Demo Completion

window.addEventListener('message', (event) => {
  if (event.data?.source !== 'Supademo') return;

  if (event.data.type === 'Supademo:completed') {
    // Wait 1 second then close the modal
    setTimeout(() => {
      closeModal();
    }, 1000);
  }
});

Close Modal on ESC Key

window.addEventListener('message', (event) => {
  if (event.data?.source !== 'Supademo') return;

  if (event.data.type === 'Supademo:close') {
    closeModal();
  }
});

Build a Custom Progress Bar

window.addEventListener('message', (event) => {
  if (event.data?.source !== 'Supademo') return;

  if (event.data.type === 'Supademo:progress') {
    const { percentage } = event.data.payload;
    document.getElementById('progress-bar').style.width = `${percentage}%`;
  }
});

Track Demo Engagement

window.addEventListener('message', (event) => {
  if (event.data?.source !== 'Supademo') return;

  const { type, payload } = event.data;

  switch (type) {
    case 'Supademo:started':
      analytics.track('Demo Started', { demoId: payload.demoId });
      break;
    case 'Supademo:completed':
      analytics.track('Demo Completed', { demoId: payload.demoId });
      break;
  }
});

Show Slide Counter

window.addEventListener('message', (event) => {
  if (event.data?.source !== 'Supademo') return;

  if (event.data.type === 'Supademo:slideChange') {
    const { currentSlide, totalSlides } = event.data.payload;
    document.getElementById('slide-counter').textContent =
      `Step ${currentSlide} of ${totalSlides}`;
  }
});

Notes

• Events are only emitted when the demo is embedded in an iframe

• The percentage in Supademo:progress represents slides viewed (e.g., slide 3 of 5 = 60%)

• Events are non-blocking and won't affect demo performance