Embedding a Dashboard

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 support@chartio.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:

Add a Hidden Variable from Dashboard

Hidden variable menu

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

Filter data

3. Retrieve dashboard example code

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

Embedding Dashboard Button

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

Embedding Code

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.

Embed Secret Key

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:

pip install pyjwt

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. 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 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 (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 organization secret gathered above and the HMAC256 signature mechanism.

A Python example is below 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 documenation on optimizing embedding loading times.