Embedding a Dashboard

Follow these steps to embed a Chartio dashboard into your application. Once a dashboard is created, it should not take more than an hour to embed it. Contact support@chartio.com with any questions.

1. Create a dashboard (or use an existing).

Add a dashboard or pick an existing dashboard to be embedded.

2. Parameterize your dashboard with variables.

Control your embedded dashboard with dashboard variables. Upon embedding the dashboard, the JSON Web Token (JWT) that are created will control these variables which will then filter the queries and charts.

Any dashboard variables that you do not want users to be able to control need to be added as hidden variables from the dashboard sidebar.

Add a Hidden Variable from Dashboard

Hidden variable menu

All variables (hidden or not) should be wired to control your charts.

Filter data

3. Retrieve dashboard example code.

Open the dashboard Settings from the sidebar and click Embed. This opens the code in three options, Python, Ruby, Javascript, and PHP.

Embedding Dashboard Button

Embedding Code

4. Retrieve the Embed Secret.

All embedding will encrypted by your org’s unique Embed Secret Key. Find the key by clicking the ellipsis by the search bar and choose Embedding. Your Embed Secret will appear there. Note: You will need Owner access to view the Embed Secret.

Embed Secret Key

5. 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

6. 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). See the example code above for Ruby and Javascript.

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
}

7. 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)

8. 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')))

9. 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.