Embedding a Dashboard (old)

Once a dashboard is created, it shouldn’t take too long to embed it into your application. Follow the instructions below to embed dashboards using our old version of Embedding:

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 settings modal

Filter data with Hidden Variables

2. Retrieve the dashboard embedding example code

Navigate to the dashboard you wish to embed, then open Settings from the dashboard sidebar and click the Embed button at the top-right of the modal.

Click the Embed button from the dashboard settings to access the embed code

This will bring you to the dashboard’s Embedding page, where you can see the dashboard example code in four languages:

  • Python
  • Ruby
  • Javascript
  • PHP

For the following examples, we’ll use Python code.

Embedding example code for the Executive Summary dashboard

3. Retrieve the Embed Secret

All embedding will be encrypted by your organization’s unique Embed Secret. Find the Embed Secret by clicking the ellipsis (…) from the top navigation bar and choosing Embedding; your Embed Secret will appear here. Keep it handy as we will refer to it in the next steps.

Note: Owner access is required to view the Embed Secret.

Access the Embedding page from the ellipses dropdown in the top nav bar

Get the Embed Secret Key from your org's Embedding page

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 defined 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

5. 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 (Optional): An expiration value that specifies when the token expires. The default (and max) value is 24 hours, but it can be set lower;
  • Any additional values required by the third party JWT library of your choice (e.g., iat).

Example Python payload:

payload = {
'dashboard': 38727,
'organization': 16417,
'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 the use of UI elements different from what Chartio natively offers.

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 = {
'dashboard': 38727,  
'organization': 16417,
'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 organization Embed Secret (see Step 3) and the HMAC256 signature mechanism.

Example Python payload:

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.

"Loading" message that appears when an embedding request includes a new JWT

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.