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 email@example.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.
All variables (hidden or not) should be wired to control your charts.
3. Retrieve dashboard example 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.
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:
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.
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 (
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.
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 documentation on optimizing embedding loading times.