Embedding 2.0

Overview

Integrating embedded dashboards into your application involves two open, simple, 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 default values to apply to any dashboard variables. You can choose whether or not your users can update the dashboard variables.

HTML iframes are a common technology used for embedding third party widgets in 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 a Dashboard

Embedding is a premium feature and may need to be enabled for your account. Contact support@chartio.com for more information.

Retrieve dashboard embedding example code

From the dashboard’s sidebar, select Settings, then click the Embed button.

From there you can see the dashboard example code in Python, Ruby, Javascript and PHP. Keep this handy as we will refer to it in the next step.

By default, embedded viewers cannot change dashboard filters. To allow changing dashboard filters, check the Allow Viewers to Apply Dashboard Variables checkbox.

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, then find your Embed Secret. Keep this handy as we will refer to it in the next step. Owner access is required to view the Embed Secret.

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 using:

pip install pyjwt

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 (required): An expiration value that specifies when the token expires. Maximum value is 24 hours.

Example

payload = {
	'dashboard': 1,
	'organization': 1,
	'exp': datetime.utcnow() + timedelta(seconds=30),
	'env': {'MYVAR': 42}
}

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.

ORGANIZATION_SECRET = 'YOUR SECRET HERE'
token = jwt.encode(payload, ORGANIZATION_SECRET)

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/org-slug/dashboard-slug'
print('<iframe src="%s/%s"></iframe>' % (BASE_URL, token.decode('utf-8')))

Test the Results

Test the results by requesting the application page with the embedded iframe.

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 2.0 embeds the native Chartio dashboard, so the embedded dashboard uses the cache settings for that dashboard in Chartio.

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

We require that payloads contain a JWT expiration within 24 hours, otherwise we will prevent navigating to the embedded dashboard.

Limitations

URL Length

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

Switching from 1.0 to 2.0

In order for you to upgrade your dashboards to Embedding 2.0, Chartio support will need to enable it for your account. Contact us at support@chartio.com for more information.

Once 2.0 is enabled, your existing embedded dashboards using 1.0 will continue to work until 1.0 is deprecated in 2020.

Testing note: Once you have viewed a 2.0 dashboard, a cookie is set in your browser that will cause any 1.0 embedded dashboards to redirect to chartio.com in your current browser session. If you reset your cookies or open a new browser session, the 1.0 dashboard will be viewable as normal.

Dashboard variables

Chartio’s Embedding 2.0 supports using our native dashboard filters. If you would like to enable this for your users, enable the Allow Viewers to Apply Dashboard Variables setting in the dashboard’s embed settings.

If the Allow Viewers to Apply Dashboard Variables setting is enabled, including variables in the payload is optional.

If you would prefer to use your own UI elements linked to hidden variables for dashboard filtering, you may continue to do so.

Update embed url generation script/embed url

If you are using a script to generate the embed url, retrieve the example code as described in the setup instructions and update your script to match the functionality. Ensure the JWT token is a GET parameter instead of part of the url. Additionally, verify your payload contains a JWT expiration value of 24 hours or less.

If you are using the embed url directly, ensure your url matches the new format.