Embed Charts in Your Web Application¶

On this page

Overview
Procedure
Embedded Charts Error Codes

Overview¶

As a dashboard Author, you can enable embedding on your charts, allowing your visualizations to be embedded in external web sites. You can either require a verified signature to accompany each data request, or allow anyone with the chart’s identifying information to embed it in a web page.

If you want strict control over who can embed your charts, use the Verified Signature Required option. If your data is non-sensitive and you prefer a simpler embedding solution, use the Unauthenticated Access option.

Note

You can enable chart embedding with the verified signature required option even if you don’t currently have an embedding key, but you’ll need a key to generate a verified signature. If you are a Project Owner for your Atlas project, you can generate an embedding key on the Admin Settings page. Otherwise, you must contact the Atlas Project Owner and ask for an embedding key.

Procedure¶

Unauthenticated Access
Verified Signature Required

1

Select a dashboard.¶

From your dashboard tab, select the dashboard containing the chart you wish to make embeddable.

2

Select a chart.¶

From the dashboard, click the ellipsis (…) button at the top-right of the chart to access its embedding information. Select Embed Chart from the dropdown menu.

3

Enable embedding on the data source¶

If you have already enabled embedding on the data source this chart uses, you can skip this step. If you haven’t yet enabled embedding on the data source, you can do so now. Click the Enable embedding options link.

4

Select the Unauthenticated tab in the dialog window.¶

5

Toggle the switch marked Enable unauthenticated access to On.¶

The HTML code necessary to embed the chart appears in the modal window. This HTML snippet is ready to copy and paste into an external web page.

1

Select a dashboard.¶

From your dashboard tab, select the dashboard containing the chart you wish to make embeddable.

2

Select a chart.¶

From the dashboard, click the ellipsis (…) button at the top-right of the chart to access its embedding information. Select Embed Chart from the dropdown menu.

3

Enable embedding on the data source¶

If you have already enabled embedding on the data source this chart uses, you can skip this step. If you haven’t yet enabled embedding on the data source, you can do so now. Click the Enable embedding options link.

4

Select the Verified Signature tab in the dialog window.¶

5

Toggle the switch marked Enable signed authentication access to On.¶

The HTML code which appears in the modal window shows the parameters which are required to embed a chart with authentication enabled, but it is not usable as-is. Continue with the subsequent steps to enable authenticated access.

6

Go to Admin Settings to acquire an embedding key.¶

Click the Admin Settings link below the HTML code snippet in the modal window.

Note

You must be a Project Owner to access the Admin Settings page. For users with the Project Owner role, the Admin Settings link appears in the top right corner of the charts UI. As a non-admin user, you can still use embedded charts, but you will need to ask a Project Owner for a key.

7

Generate an embedding key.¶

Click the Generate New Key button to create a new embedding key. Store the key in a safe place.

Warning

If you generate a new key, any previous keys become invalid. Ensure that all the existing embedded charts that use the old key are updated to use the new key.

8

Create the server-side code necessary for a verified signature.¶

Generating a verified signature to accompany data requests from embedded charts with authentication enabled requires server-side code. The verified signature creates a payload by generating a HMAC from your embedding key, a timestamp, and identifying data from your chart. The verified signature is valid for a limited time period specified in your server-side code.

Code examples demonstrating how to generate a verified signature are available for the following languages and platforms:

Embedded Charts Error Codes¶

If an embedded chart fails to render, an error code is displayed:

Error Code	Error Cause
`-1`	Unknown error.
`1`	Invalid tenant ID. Check the `tenant` field in the iframe HTML and make sure it matches what you see in the Embed Chart modal window.
`2`	Item not found. Check the `id` field in the iframe HTML and make sure it matches what you see in the Embed Chart modal window.
`3`	Embedding not enabled. Check the settings in your chart’s Embed Chart modal window.
`4`	Embedding not allowed. Check the embedding settings in your chart’s data source.
`5`	Invalid payload. Your application server is not creating a usable signature.
`6`	Invalid `autorefresh` value specified. The `autorefresh` value must be an integer greater than 0.
`7`	Filter not allowed. A `filter` parameter was specified for a chart using anonymous embedding. Filters can only be used with verified signatures.
`8`	Filter not valid. A `filter` parameter contains an invalid value.

← Geospatial Heatmap Embedded Chart Options →