Embed Charts in Your Web Application

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

How to Choose an Access Level

If you want strict control over who can share your charts, use the Verified Signature Required option. If your data is non-sensitive and you prefer a simpler external sharing solution, use the Unauthenticated External Sharing option.

Note

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

Procedure

• Unauthenticated External Sharing
• 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 ellipsis icon at the top-right of the chart to access its embedding information. Select Embed Chart from the dropdown menu.

3

Enable external sharing on the data source

If you have already enabled external sharing on the data source this chart uses, skip this step. If you haven’t yet enabled embedding on the data source, you can do so now. Click the Configure external sharing 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. 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 ellipsis icon at the top-right of the chart to access its external sharing information. Select Embed Chart from the dropdown menu.

3

Enable External Sharing on the data source.

If you have already enabled external sharing on the data source this chart uses, you can skip this step. If you haven’t yet enabled external sharing on the data source, you can do so now. Click the Enable external sharing 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 share 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 MongoDB 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 shared 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 shared 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:

• Node.js
• C#
• Java
• Python
• MongoDB Stitch

Embedded Charts Error Codes

If an shared 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. When filtering an Unauthenticated embedded chart, the fields used in the filter must be present in the filter whitelist. Additionally, filters on both Unauthenticated and Verified Signature embedded charts cannot use non-logical operators before a field name (e.g., $expr, $where, or $text).
8	Filter not valid. A filter parameter contains an invalid value.

• Embedded Chart Options

←   Geospatial Heatmap Embedded Chart Options  →

© MongoDB, Inc 2008-present. MongoDB, Mongo, and the leaf logo are registered trademarks of MongoDB, Inc.