The following are the steps to embed a Chartio dashboard into your application. Once a dashboard is created it should not take more than an hour to fully embed your dashboard. If you have any quesitons do contact email@example.com
1. Create a Dashboard (or use an existing)
Using the same Chartio interface you’re used to, add a dashboard or pick an existing dashboard to be embedded.
2. Parameterize your Dashboard
You can control your embedded dashboard with dasbhoard variables. Upon embedding the dashboard, the JSON Web Token (JWT) you create will control these variables which will then filter all queries and charts displayed.
Paramaters you don’t want the user to be able to control need to be implemented as hidden variables. They can be simply added from the sidebar of any dashboard:
Your variables (hidden or not) should be wired to control your charts.
3. Retrieve dashboard example code
From the dashboard’s sidebar, select Settings, then click the Embed button.
4. Retrieve 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. There you will see your Embed Secret. Keep this handy as we will refer to it in the next step. You’ll need Owner access to view the Embed Secret.
5. Install a 3rd 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:
6. Construct a Payload
Construct a payload using as a reference 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.
The values included in the
env mapping can be sourced from forms that are 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 your end users. Additionally, it allows UI elements vastly 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 (
7. 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.
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.
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.
If the dashboards aren’t loading as fast as you’d like, take a look at our documenation on optimizing embedding loading times.