Embedding

As an added service, Chartio provides the ability to embed dashboards into existing web applications.

This powerful feature allows you to provide personalized analytics to your customers, increasing the overall value of your product offering with minimal development effort.

If you’re interested in seeing a demo or enabling this for your account, please contact sales@chartio.com.

Embedding Version

Chartio currently supports two versions of Embedding: 1.0 and 2.0.

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 the option is not available, see instructions for Embedding 1.0;
  • If the option is available, see instructions for Embedding 2.0.

Technologies Used

Integrating embedded dashboards into your application involves two open and easy-to-use technologies: JSON web tokens (JWT) and HTML iframes.

JWTs allow you to, in a tamper-proof manner from your end user’s perspective, pass Chartio the dashboard id you would like to embed as well as the values to apply to any dashboard variables.

Depending on the version of Embedding enabled for your organization, these values can be controlled either by your application’s native UI elements or by using Chartio’s dashboard variables. You can also choose whether or not your users can update the dashboard variables for each embedded dashboard.

HTML iframes are a common technology used for embedding third party widgets into a webpage.

Plugging everything together is as simple as placing an iframe in your HTML that references in its src attribute a Chartio endpoint appended with a JWT.

Embedding Security

Organization Secret

Your organization secret is used during the JWT generation to secure the JWT from tampering using the HMAC256 signature mechanism. The secret is unique for your organization and needs to be kept secret to assure that embedding requests cannot be tampered with or spoofed. The organization secret can be viewed by organization owners by navigating to Settings > Embedding. It can also be reset from this page if it is ever leaked.

Sensitive Data

The payload, though obscured via the JWT base64 encoding, is not cryptographically secure. While payload data cannot be tampered with without access to the organization secret, sensitive data (e.g. SSNs) should not be included in the payload.

Revoking End User Access

To revoke end user access to embedded dashboards at any time, reset your organization secret. To do this, visit the Embedding settings page and click the Reset Secret button. Please note, this will immediately invalidate embedding requests encoded with the old secret for all dashboards across your entire organization.

JWT Expiration

By default, we expire JWTs at 24 hours from the iat (issued at) value. Your third party JWT library may generate the iat value for you or require you to include it in your payload. You can lower the expiration time using the exp JWT value however we will always cap the upper bound at 24 hours. This is to limit the downside of an end user looking at your HTML source in the browser and distributing the iframe src url outside of your application; at most they could only get away with this for 24 hours.

Limitations

URL Length

The URL length of the payload cannot exceed that which browsers support, which is 2,038 characters for Internet Explorer. This means there are roughly 1,700 characters available for dashboard variable definitions, which is more than enough for most applications.

Chartio’s Native UI Elements (Embedding 1.0)

Native UI elements (Date Sliders, Dropdowns, etc.) and dashboard Drilldowns are disabled for embedded dashboards using Embedding 1.0. This functionality is instead replaced with the more flexible env variables in the JWT payload which allows robust filter and drill capabilities based on UI elements native to the embedding application.

Number of Dashboards per Page

We can allow for 1 iframe, or embedded dashboard, per site page. If you’d like to embed multiple dashboards within your site, dashboards should be embedded within different pages. These can then be linked within dashboards or on your page via a menu or toggle.

Optimizing Load

Usage Statistics

On your dashboard’s embedding settings page, organization owners can see the number of times each dashboard has been embedded. This number corresponds to the number of times a dashboard has been requested for embedding with a completely new JWT and represents the number of times the queries associated with a dashboard have been sent to your database. If this number seems high, you may want to look into caching to avoid unnecessary load on your database.

Caching

Embedding 1.0

Queries relating to an embedded dashboard are only run when the iframe src url is requested with a brand new JWT. The results are cached for all subsequent requests until the JWT expires allowing an opportunity to pre-populate a cache with common iframe src urls by requesting them server side before end users ever request the urls. This will eliminate any loading time end users would have had to endure waiting for the queries to complete. This is not required however, and the mechanism you choose to build this cache is entirely up to you (e.g. lazy load, batch job, etc.).

Embedding 2.0

Embedding 2.0 embeds the native Chartio dashboard, so the embedded dashboard uses the cache settings for that dashboard in Chartio.