# Embed events

### Overview

You can embed a Sprinkle Dashboard directly inside your web application using an **iframe.**\
To make the dashboard interactive with your app, Sprinkle provides a **postMessage bridge.**

This bridge allows the dashboard to send real-time events (like chart clicks, table row clicks, or filter changes) to your parent application.\
Your app can **listen to these events** and take appropriate actions — for example, updating UI components or triggering API calls.

### **1. Setting Up the Event Bridge**

The Sprinkle dashboard sends messages from the iframe to the parent page using the standard browser `postMessage` API.

#### **How It Works**

* **Direction:** One-way communication by default — from the iframe → parent page.
* **Extension:** Can be expanded for two-way communication if needed.

#### **Example Setup**

Add this listener to your parent application:

```
// Listen for all events from the dashboard iframe
window.addEventListener("message", (event) => {
  // Optional: validate origin
  // if (event.origin !== "https://sprinkledata_example.com") return;

  const { type, payload, source } = event.data || {};

  if (source !== "SPRINKLE-DASHBOARD") return;

  console.log("Dashboard Event:", type, payload);
});
```

### **2. Event Structure**

Each event sent from the dashboard follows this structure:

```
{
  "source": "SPRINKLE-DASHBOARD",
  "type": "EVENT_TYPE",
  "payload": {
    ...eventData
  }
}
```

#### **Field Descriptions**

| Field     | Description                                               |
| --------- | --------------------------------------------------------- |
| `source`  | Always `"SPRINKLE-DASHBOARD"` — identifies the sender     |
| `type`    | The event type (e.g., `FILTERS_UPDATE`, `CHART_ON_CLICK`) |
| `payload` | JSON object containing event-specific data                |

### 3. Event Types

The dashboard currently emits the following events:

{% tabs %}
{% tab title="FILTERS\_UPDATE" %}
This event is triggered with this structural data payload when the page loads or when filters are applied by clicking the Apply button.

```
{
  data: {
    [filter_id]: {
      ...(specific_filter_full_data)
    }
    ...
  }
}

```

{% endtab %}

{% tab title="FILTER\_ON\_CHANGE" %}
This event is triggered with this structural data payload when any  filter, variable is changed

```
{
  data: {
    filter: {
      id,
      value,
      …
    },
    updatedFilters: {
     [filter_id]: {
      ...(specific_filter_full_data)
     }
     ...
    }
  }
}
```

{% endtab %}

{% tab title="TABLE\_ON\_CLICK" %}
This event is triggered with this structural data payload when table row is clicked.

```
{
  data: {
    tableData: {
      ...(table_all_required_data)
    }
    ...
  }
}
```

{% endtab %}

{% tab title="CHART\_ON\_CLICK" %}
This event is triggered with this structural data payload when chart item is clicked

```
{
  data: {
    chartData: {
      ...(chart_all_required_data)
    }
    ...
  },
  events: chart_events
}
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
You can request additional custom events from us if your use case requires them.
{% endhint %}

### **4. Event Payload Details**

* All payloads are **JSON-safe objects**.
* Only **serializable data** is sent — no raw DOM references or native event objects (for security reasons).
* You can safely log or parse the payload in your app.

### **5. Example: Handling Dashboard Events in Your App**

Here’s a complete example of how to listen for and handle different dashboard events:

```
window.addEventListener("message", (event) => {
  const { type, payload, source } = event.data || {};
  if (source !== "SPRINKLE-DASHBOARD") return;

  switch (type) {
    case "FILTERS_UPDATE":
      console.log("Filters applied or loaded:", payload);
      break;

    case "CHART_ON_CLICK":
      console.log("Chart clicked:", payload.data.activeViz);
      console.log("Chart data:", payload.data.chartData);
      console.log("Event info:", payload.events);
      break;

    default:
      console.warn("Unknown event type:", type);
  }
});

```


---

# 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.sprinkledata.com/product/analysing-your-data/dashboards/embed-events.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.