# 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