Embed a single Illuminate chart with runtime filters
This guide shows you how to embed one Illuminate chart in your portal and filter it for a specific context. Complete Embed the Illuminate UI in your portal first, so you have an access token.
Embed a single chart when you want to show one metric visualization in your app without the full Dashboards UI. For example, show a Dashboard chart filtered to a specific channel or customer.
To embed a chart, use the charts/<chart-id> resource path:
1<iframe src="https://oem.pubnub.com/embed/charts/<chart-id>?embed=true&token=<token>" width="100%" height="600" style="border: 0" loading="lazy"></iframe>
Find the chart and dimension IDs
A dimension is a text field from a Business Object that a metric groups or filters by, such as a channel name. You need the chart ID to embed the chart and the dimension IDs to filter it.
Retrieve the Dashboard that contains the chart with the List dashboards endpoint. This call requires an Admin API key with read permission for Illuminate. To create one, see the Admin API introduction.
In the response:
- Use
charts[].idas<chart-id>. - Use
charts[].nameto confirm you selected the correct chart. - Use
charts[].dimensionIdsfor the dimensions currently configured on that chart. - Use
charts[].metric.dimensionIdsandcharts[].metric.dimensions[](each withidandname) to find valid dimension IDs and their display names.
Example response shape:
1{
2 "id": "8f1d3a48-2b5d-49eb-a792-9531c59afcda",
3 "name": "Customer dashboard",
4 "charts": [
5 {
6 "id": "chart-123",
7 "name": "Events by region",
8 "dimensionIds": ["dimension-region"],
9 "metric": {
10 "id": "metric-123",
11 "name": "Events",
12 "dimensionIds": ["dimension-channel"],
13 "dimensions": [
14 { "id": "dimension-channel", "name": "channel" }
15 ]
show all 19 linesAdd runtime filters
Runtime filters limit the chart to specific dimension values when the iframe loads, without changing the chart configuration in the Dashboard. Pass them in the filters query parameter. The value is a URL-encoded JSON array of dimension ID and value pairs:
1[
2 { "dimensionId": "dimension-channel", "dimensionValue": "web12345" }
3]
URL-encoded, the iframe src looks like this:
1<iframe src="https://oem.pubnub.com/embed/charts/<chart-id>?embed=true&token=<token>&filters=%5B%7B%22dimensionId%22%3A%22dimension-channel%22%2C%22dimensionValue%22%3A%22web12345%22%7D%5D" width="100%" height="600" style="border: 0" loading="lazy"></iframe>
If you pass more than one filter, the chart applies all of them together. Omit filters when you don't need runtime filtering.
To hide the decisions section and the Manage decisions dialog in a chart embed, add hideDecisions=true to the query parameters. This applies only to single-chart embeds.