# 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:

```javascript
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:**

```javascript
{
  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:**

```javascript
{
  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:**

```javascript
{
  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:**

```javascript
{
  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:**

```javascript
{
  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:**

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

### Common Use Cases

#### Close Modal on Demo Completion

```javascript
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

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

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

#### Build a Custom Progress Bar

```javascript
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

```javascript
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

```javascript
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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.supademo.com/share/embed/embed-events-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.