Get Started with the Embedding SDK

On this page

Prerequisites

Procedures
Enable Embedding
Create a Web App
Add Embedding Code to Your App

You can embed a chart or dashboard into a web application with the Embedding SDK, allowing more flexible adjustments of settings and rendering.

Prerequisites

You must be a dashboard Author to enable embedding for a chart.
Create a New Dashboard
Create a Chart

Procedures

Enable Embedding

Select a dashboard.

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

Select a chart.

From the dashboard, click at the top-right of the chart to access its embedding information. Select Embed chart from the dropdown menu.

Note

If a chart is on a dashboard that has embedding enabled, the Embed Chart option is automatically enabled. Therefore, you can't select the Embed chart option for charts within dashboards that have embedding enabled.

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.

Select the Unauthenticated tab in the dialog window.

click to enlarge

Toggle Enable unauthenticated access to On.

(Optional) Specify filterable fields for your chart.

Specify the fields on which chart viewers can filter data. By default, no fields are specified, meaning the chart cannot be filtered until you explicitly allow at least one field.

Alternatively, you can specify all the fields in your chart by selecting Allow all fields in the data source used in this chart.

To learn more about filterable fields, see Specify Filterable Fields.

Select the Javascript SDK panel.

Copy the Charts Base URL and Chart ID.

You'll need the Charts Base URl and Chart ID values in your web application code.

Select a dashboard.

From your dashboard page, select the dashboard containing the chart you wish to embed.

Select a chart.

From the dashboard, click at the top-right of the chart to access its embedding information. Select Embed chart from the dropdown menu.

Note

Enable external sharing on the data source

Select the Authenticated tab in the dialog window.

click to enlarge

Toggle Enable authenticated access to On.

(Optional) Specify a filter function to inject per user.

You can specify a function to inject a MongoDB filter document for each user who views the chart. This is useful for rendering user-specific charts.

Example

The following filter function only renders data where the ownerId field of a document matches the value of the Embedding Authentication Provider's token's sub field:

function getFilter(context) {
  return { ownerId: context.token.sub };
}

(Optional) Specify filterable fields for your chart.

Specify the fields on which chart viewers can filter data. By default, no fields are specified, meaning the chart cannot be filtered until you explicitly allow at least one field.

Copy the Chart Base URL and Chart ID

Use these values in your application code together with your Embedded Authentication Provider attributes to embed your chart.

Configure Embedding Authentication Providers

Go to Charts.

Warning

Navigation Improvements In Progress

We're currently rolling out a new and improved navigation experience. If the following steps don't match your view in the Charts UI, see the preview documentation.

If Atlas Charts is not already displayed, click the Charts tab in the Atlas UI.

Atlas launches an instance of Charts linked to your project.

Go to the Embedding page.

Warning

Navigation Improvements In Progress

We're currently rolling out a new and improved navigation experience. If the following steps don't match your view in the Charts UI, see the preview documentation.

Click Embedding under the Development heading in the sidebar.

The Embedding page displays.

Go to the Authentication Settings view.

Warning

Navigation Improvements In Progress

We're currently rolling out a new and improved navigation experience. If the following steps don't match your view in the Charts UI, see the preview documentation.

Note

You must be a Project Owner to access the Authentication Settings page. As a non-admin user, you can still use embedded charts, but you must get a key from a Project Owner.

Click the Authentication Settings tab.

The Authentication Settings tab displays.

Add the authentication provider.

From the Authentication providers section, click Add.
In the Name field, enter a descriptive name for the provider.
From the Provider list, select the type of provider you want to add.

Configure Charts to verify tokens from the provider.

The values you must enter differ based on the provider you selected:

Provider

Fields

Custom JWT

Provide the following values:

Field

Value

Signing Algorithm

Encryption algorithm with which the JWT signature is encoded.

Must be one of:

Signing Key

Secret or key used to validate the JWT signature. If tokens are not signed, Charts considers them invalid. If you provide an incorrect key, Charts is unable to verify token signatures and considers them invalid.

The value you must provide depends on the Signing Algorithm:

HS256: enter the secret key used to sign the JWT.

RS256: Select either JWK or JWKS URL or PEM Public Key.

If you select JWK or JWKS URL, Charts retrieves the key from the JWK or JWKS file at the specified URL. Charts then uses the key to validate the JSON web token. If there are multiple keys in the file, Charts tries each key until it finds a match. Enter the URL that contains the JWK or JWKS file.

If you choose PEM Public Key, Charts uses the specified public key to verify the JSON web token. Enter the public key of the key pair used to sign the JWT. The public key must be in PEM format, as shown in the following example:

Audience (Optional)

Audience claim that must be present in the JWT for Charts to consider it valid.

Google

In the Client ID field, enter your application's Google Client ID, in the following format:

<prefix>.apps.googleusercontent.com

Atlas App Services

Provide the following values:

Field	Value
Project	Project that contains your app service.
App Service	App service that's issuing the user token.
Fetch data using Atlas App Services (Optional)	Toggle to enable Charts to fetch user data and rules from an app service. If enabled, Charts retrieves data from the service you specify in the App Service Name field. Enabling this option allows you to define rules in Atlas App Services to control the data that Charts displays for specific collections or users. For more information, see Filter Incoming Queries in the App Services documentation.
App Service Name	The name of the service in your app service that Charts uses to retrieve the data for your chart. For example, `mongodb-atlas`.

Click Save.

Select a dashboard.

From your dashboard page, select the dashboard to embed.

Select Embed.

From the dashboard, click at the top-right of the dashboard to access its embedding information. Select Embed from the dropdown menu.

Enable external sharing on the data source.

If you have already enabled external sharing on the data source that this dashboard uses, skip this step. If you haven't yet enabled embedding on the data source, you can do so now. Click the Configure link.

Select the Unauthenticated tab in the dialog window.

Toggle Enable unauthenticated access to On.

(Optional) Specify filterable fields for your dashboard.

Specify the fields on which dashboard viewers can filter data. By default, no fields are specified, meaning the dashboard cannot be filtered until you explicitly allow at least one field.

Alternatively, you can specify all the fields in your dashboard by selecting Allow all fields in the data source used in this dashboard.

To learn more about filterable fields, see Specify Filterable Fields.

Select the Javascript SDK panel.

Copy and save the base URL.

Copy and save the dashboard ID.

Select a dashboard.

From your dashboard page, select the dashboard to embed.

Select Embed.

From the dashboard, click at the top-right of the dashboard to access its embedding information. Select Embed from the dropdown menu.

Enable external sharing on the data source.

Select the Authenticated tab in the dialog window.

Toggle Enable authenticated access to On.

Add authentication providers.

If you have already set up authentication providers, skip this step. If you haven't yet set up authentication providers, you can do so now.

To learn more, see Configure Embedding Authentication Providers.

Click Add.
Specify a name for the authentication integration.
Select a provider and specify the provider settings.
Click Save.
Click Back to Embed Dashboard.

(Optional) Specify a filter function to inject per user.

You can specify a function to inject a MongoDB filter document for each user who views the dashboard. This is useful for rendering user-specific dashboards.

Example

The following filter function only renders data where the ownerId field of a document matches the value of the Embedding Authentication Provider's token's sub field:

function getFilter(context) {
  return { ownerId: context.token.sub };
}

(Optional) Specify filterable fields for your dashboard.

Specify the fields on which dashboard viewers can filter data. By default, no fields are specified, meaning the dashboard cannot be filtered until you explicitly allow at least one field.

Alternatively, you can specify all the fields in your dashboard by selecting Allow all fields in the data source used in this dashboard.

To learn more about filterable fields, see Specify Filterable Fields.

Copy and save the base URL.

Copy and save the dashboard ID.

Create a Web App

Proceed with the remaining steps to create a new app in which to display your chart.

Note

MongoDB offers a pre-built example app in the GitHub repository that shows how to use the Embedding SDK to display an unauthenticated embedded chart.

Proceed with the remaining steps to create a new app in which to display your chart.

Note

MongoDB offers a pre-built example in the GitHub repository that shows you how to use the Embedding SDK to authenticate an embedded chart using your authentication provider.

Proceed with the remaining steps to create a new app in which to display your dashboard.

Note

MongoDB offers a pre-built example of an unauthenticated embedded dashboard in the GitHub Repository. This example shows how to use the Embedding SDK to display an unauthenticated embedded dashboard.

Proceed with the remaining steps to create a new app in which to display your dasbhoard.

Note

MongoDB offers examples of authenticated embedded dashboards in the GitHub Repository. These examples show you how to use the Embedding SDK to authenticate an embedded dashboard using Atlas App Services, Google, or JWT authentication providers.

Add Embedding Code to Your App

To learn how to install the Embedding SDK into your app, see Install the Embedding SDK.

Add the following code to your web app to execute where you want your chart to render:

Note

Replace the existing Charts Base URL and chart ID with the values for the chart that you want to display. Your Charts Base URL and chart ID are visible in the embedding options modal window.

import ChartsEmbedSDK from "@mongodb-js/charts-embed-dom";
const sdk = new ChartsEmbedSDK({
  baseUrl: "https://charts.mongodb.com/charts-embedding-examples-wgffp", // ~REPLACE~ with the Base URL from your Embed Chart dialog.
});
const chart = sdk.createChart({
  chartId: "735cfa75-15b8-483a-bc2e-7c6659511c7c", // ~REPLACE~ with the Chart ID from your Embed Chart dialog.
  height: "700px",
  // Additional options go here
});
chart.render(document.getElementById("chart"));

Add the following code to your web app to execute where you want your chart to render. The following example authenticates with Atlas App Services.

Note

Replace the existing App ID with your App ID, which you can find in the Atlas App Services UI. Replace the existing Charts Base URL and chart ID with the values for the chart that you want to display. Your Charts Base URL and chart ID are visible in the embedding options modal window.

import ChartsEmbedSDK from "@mongodb-js/charts-embed-dom";
// Needed only if you are using the Atlas App Services authentication provider
const client = Stitch.initializeAppClient(
  'authentication-sample-eibkj', // ~REPLACE~ with your App ID
});
const sdk = new ChartsEmbedSDK({
  baseUrl: "https://charts.mongodb.com/charts-embedding-examples-wgffp", // ~REPLACE~ with the Base URL from your Embed Chart dialog.
  getUserToken: () => getRealmUserToken(client),
  // getUserToken is a callback to provide the auth token to the SDK.
  // Use the getRealmUserToken helper when using the Atlas App Services auth provider.
  // If using Custom JWT or Google providers, provide your own code to retrieve the JWT
});
const chart = sdk.createChart({
  chartId: "735cfa75-15b8-483a-bc2e-7c6659511c7c", // ~REPLACE~ with the Chart ID from your Embed Chart dialog.
  height: "700px",
  // Additional options go here
});
chart.render(document.getElementById("chart"));

Add the following code to your web app to execute where you want your dashboard to render.

Note

Replace the existing Dashboards Base URL and dashboard ID with the values for the dashboard that you want to display. Your Dashboards Base URL and dashboard ID are visible in the embedding options modal window.

import ChartsEmbedSDK from "@mongodb-js/charts-embed-dom";
const sdk = new ChartsEmbedSDK({
   baseUrl: "https://charts.mongodb.com/charts-embedding-examples-wgffp", // ~REPLACE~ with the Base URL from your Embed Dashboard dialog.
});
const dashboard = sdk.createDashboard({
   dashboardId: "735cfa75-15b8-483a-bc2e-7c6659511c7c", // ~REPLACE~ with the Dashboard ID from your Embed Dashboard dialog.
   height: "700px",
   widthMode: "scale",
   heightMode: "fixed"
   // Additional options go here
});
dashboard.render(document.getElementById("dashboard"));

Add the following code to your web app to run it where you want your dashboard to render. The following example authenticates with Atlas App Services.

Note

Replace the existing App ID with your App ID. You can find your App ID in the Atlas App Services UI. Replace the existing Dashboards Base URL and dashboard ID with the values for the dashboard that you want to display. Your Dashboards Base URL and dashboard ID are visible in the embedding options modal window.

import ChartsEmbedSDK from "@mongodb-js/charts-embed-dom";
// Needed only if you are using the Atlas App Services authentication provider
const client = Stitch.initializeAppClient(
   'authentication-sample-eibkj', // ~REPLACE~ with your App ID
});
const sdk = new ChartsEmbedSDK({
   baseUrl: "https://charts.mongodb.com/charts-embedding-examples-wgffp", // ~REPLACE~ with the Base URL from your Embed Dashboard dialog.
   getUserToken: () => getRealmUserToken(client),
   // getUserToken is a callback to provide the auth token to the SDK.
   // Use the getRealmUserToken helper when using the Atlas App Services auth provider.
   // If using Custom JWT or Google providers, provide your own code to retrieve the JWT
});
const dashboard = sdk.createDashboard({
  dashboardId: "735cfa75-15b8-483a-bc2e-7c6659511c7c", // ~REPLACE~ with the Dashboard ID from your Embed Dashboard dialog.
  height: "700px",
  widthMode: "scale",
  heightMode: "fixed"
  // Additional options go here
});
dashboard.render(document.getElementById("dashboard"));

Back

Embedding SDK

Configure Authentication Providers