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:

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)
    }
    ...
  }
}

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)
     }
     ...
    }
  }
}

TABLE_ON_CLICK

This event is triggered with this structural data payload when table row is clicked.

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

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
}

Note

You can request additional custom events from us if your use case requires them.

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);
  }
});