Embedding a Dashboard

Embedding is a premium feature and may need to be enabled for your account. Contact support@chartio.com for more information or questions.

Follow the steps below to embed a Chartio dashboard into your application, according to the version of Embedding enabled on your account. Once a dashboard is created, it should not take more than an hour to embed it.

Note: Chartio currently supports two versions of Embedding. If you’re unsure which version is enabled on your account, check if the option to Allow Viewers to Apply Dashboard Variables is available on your Embedding page:

Embedding 2.0 - Apply dashboard variables

  • If this option is not available on the page, follow the steps for Embedding 1.0
  • If this option is available to you, skip to the steps for Embedding 2.0

Embedding 1.0

1. Parameterize your dashboard with Hidden Variables

Before embedding a dashboard into your webpage, you’ll need to parameterize the charts on the dashboard with the use of Hidden Variables.

Upon embedding the dashboard, we will filter the data being displayed by passing values to these hidden variables via a JSON Web Token (JWT).

Add a Hidden Variable from Dashboard

Hidden variable menu

Filter data

2. Retrieve the dashboard embedding example code

Navigate to the dashboard you wish to embed, then open Settings from the sidebar and click Embed on the top right of the page. This will bring you to the Embedding page where you’ll find sample code in four options: Python, Ruby, Javascript, and PHP. In the following examples, we’ll use Python code.

Embedding from dashboard

Embedding Code

3. Retrieve the Embed Secret

All embedding will be encrypted by your org’s unique Embed Secret Key. Find the key by clicking the ellipsis by the top menu search bar and click Embedding. Your Embed Secret will appear here. Keep it handy as we will refer to it in the next steps.

Note: You will need Owner access to view the Embed Secret.

Embed Secret Key

4. Install a third party JWT Library

We accept requests for the embedded dashboard using the JSON Web Token (JWT) standard. JWTs can be generated by following the procedure however using a third party library is recommended to reduce the chance for error.

For example, in Python you can install:

pip install pyjwt

5. Construct a payload

Construct a payload using the previously retrieved dashboard example code.

A payload should include the following:

  • organization: Your Chartio organization id.
  • dashboard: The id of the dashboard to be embedded.
  • env: A mapping of variable names to values which will be passed to the hidden variables on the dashboard.
  • exp (Optional): An expiration value that specifies when the token expires.
  • Any additional values required by the third party JWT library of your choice (e.g. iat).

Python Example:

payload = {
'organization': 16417,
'dashboard': 38727,
'env': {
'ACCT_ID': '1',
'DATE_RANGE': \['2014-02-11','2015-02-11'\],
'USER_ID': '1'
}
}

The values in the env mapping can be sourced from forms submitted to your web application. This allows the embedded dashboard to be filtered based on UI elements native to your application, providing a familiar interface for users. It also allows UI elements different from what Chartio natively offers to be used.

Below is an example of pulling the env values from a Django form object as well as adding an env value based on session data that is unmodifiable by the end user (ACCT_ID).

env = {k.upper(): str(v) for k, v in form.cleaned_data.items()}
env\['ACCT_ID'\] = request.session\['ACCT_ID'\]

payload = {
'organization': 16417,
'dashboard': 38727,
'exp': datetime.utcnow() + timedelta(seconds=30),
'env': env
}

6. Wrap the payload in a JWT

Generate a JWT with the payload as the body using your Embed Secret gathered above and the HMAC256 signature mechanism.

Below is a Python example and examples in Ruby, Javascript, and PHP are available from your embedding page.

ORGANIZATION_SECRET = 'YOUR SECRET HERE'
token = jwt.encode(payload, ORGANIZATION_SECRET)

7. Submit the JWT in an iframe

Insert an iframe element into your HTML with a src URL consisting of the generated JWT appended to the base URL from the dashboard example code.

BASE_URL = 'https://embed.chartio.com/d/38727'
print('<iframe src="%s/%s"></iframe>' % (BASE_URL, token.decode('utf-8')))

8. Test the results

Test the results by requesting the application page with the embedded iframe. A “Loading” message should appear each time an embedding request includes a brand new JWT. The dashboard will be cached on Chartio’s servers for all subsequent requests until the JWT expires.

Embedding Loading

Embedding Example Tested

If the dashboards aren’t loading as fast as you’d like, take a look at our documentation on optimizing embedding loading times.


Embedding 2.0

1. Retrieve the dashboard embedding example code

Navigate to a dashboard you wish to embed, then from the sidebar select Settings, and click the Embed button.

From there you can see the dashboard example code in Python, Ruby, Javascript, and PHP. We will use the Python code as an example in the next step.

By default, viewers of embedded dashboards cannot change dashboard filters. To allow changing dashboard filters, check the Allow Viewers to Apply Dashboard Variables checkbox.

2. Retrieve the Embed Secret

All embedding will be encrypted by your organization’s unique Embed Secret Key. To find your key, select the ellipsis (…) from the top Chartio navigation and choose Embedding, then find your Embed Secret. Keep this handy as we will refer to it in the next step. Owner access is required to view the Embed Secret.

3. Install a third party JWT Library

We accept requests for the embedded dashboard using the JSON Web Token (JWT) standard. JWTs can be generated by following the procedure here, however, using a third party library is recommended to reduce the chance for error.

In Python, for example, you can simply install using:

pip install pyjwt

4. Construct a Payload

Construct a payload using the dashboard example code as a reference.

A payload should include the following:

  • organization: Your Chartio organization id.
  • dashboard: The id of the dashboard to be embedded.
  • env: A mapping of variable names to values which will be passed to the hidden variables on the dashboard.
  • exp (required): An expiration value that specifies when the token expires. Maximum value is 24 hours.

Example

payload = {
'dashboard': 1,
'organization': 1,
'exp': datetime.utcnow() + timedelta(seconds=30),
'env': {'MYVAR': 42}
}

5. Wrap the payload in a JWT

Generate a JWT with the payload as the body using your organization secret gathered above and the HMAC256 signature mechanism.

ORGANIZATION_SECRET = 'YOUR SECRET HERE'
token = jwt.encode(payload, ORGANIZATION_SECRET)

6. Submit the JWT in an iframe

Insert an iframe element into your HTML with a src URL consisting of the generated JWT appended to the base URL from the dashboard example code.

BASE_URL = 'https://embed.chartio.com/d/org-slug/dashboard-slug'
print('<iframe src="%s/%s"></iframe>' % (BASE_URL, token.decode('utf-8')))

7. Test the Results

Test the results by requesting the application page with the embedded iframe.

Switching from 1.0 to 2.0

In order for you to upgrade your dashboards to Embedding 2.0, Chartio support will need to enable it for your account. Contact us at support@chartio.com for more information.

Once 2.0 is enabled, your existing embedded dashboards using 1.0 will continue to work until 1.0 is deprecated in 2020.

Testing note: Once you have viewed a 2.0 dashboard, a cookie is set in your browser that will cause any 1.0 embedded dashboards to redirect to chartio.com in your current browser session. If you reset your cookies or open a new browser session, the 1.0 dashboard will be viewable as normal.

Dashboard variables

Chartio’s Embedding 2.0 supports using our native dashboard filters. If you would like to enable this for your users, enable the Allow Viewers to Apply Dashboard Variables setting in the dashboard’s embed settings.

If the Allow Viewers to Apply Dashboard Variables setting is enabled, including variables in the payload is optional.

If you would prefer to use your own UI elements linked to hidden variables for dashboard filtering, you may continue to do so.

Update embed URL generation script/embed URL

If you are using a script to generate the embed URL, retrieve the example code as described in the setup instructions and update your script to match the functionality. Ensure the JWT token is a GET parameter instead of part of the URL. Additionally, verify your payload contains a JWT expiration value of 24 hours or less.

If you are using the embed URL directly, ensure your URL matches the new format.

For additional FAQs about transitioning to Embedding 2.0, please take a look at our Transitioning to Embedding 2.0 page.