Embedded Analytics

Embedding overview

Available on plans: Pro, Business, Enterprise

Cluvio offers powerful options for embedding of full dashboards or individual reports on websites or within web applications to support wide range of scenarios:

  • simply make any dashboard part of your website (Pro or Business plan)
  • embed dashboard with different sets of filters applied (Business plan)
  • embed dashboard with values specific for a logged-in user of your web application (Business plan)

In all of these cases, whether the embedded dashboard is interactive or not, it is live, and always displays the current data or any changes made to the dashboard (i.e. behaves the same way as viewer accessing the dashboard inside the regular Cluvio account).

 tickit-embed.png

 

Here is a rundown of possible embedding options, in increased level of complexity / functionality:

 

1. Simple non-interactive dashboard embedding (Pro or Business plan)

The basic embedding is accomplished by creating a sharing link and using the embed code (which you can see by clicking on the Embed link of the sharing link in Cluvio) like the following:

<iframe 
  frameborder="0" 
  allowfullscreen 
  height="800" 
  width="100%" 
  src="https://dashboards.cluvio.com/dashboards/jvre-px0w-p1z2/shared?sharingToken=1c1d9827-bbd6-4d08-af81-2f68baacd81d"
/>

The iframe contains a link to the sharing link with the same set of options supported either on the sharing link itself or the iframe src URL parameters. Via the options you can fine tune the behavior of the embedded dashboard (toolbar, dark/light mode, grid behavior, etc.).

To share a single report, just add the

reportId=...

to the iframe src URL, e.g. like this:

<iframe 
  frameborder="0" 
  allowfullscreen 
  height="800" 
  width="100%" 
  src="https://dashboards.cluvio.com/dashboards/7wo6-vmdx-6x40/shared?sharingToken=524ea7d6-8957-4fe0-aad0-b7f3629c7654&reportId=govm-x00l-1m6q&reportOnly&noBorder=true&backgroundColor=FFF" 
/>

You can see these embeds in action at our website.

 

2. Embedding a non-interactive dashboard with different filters applied (Business plan)

With the Business plan, you can make use of the sharing link with parameters to create different sharing links for the same dashboard and use those as embeds. In this case, you could, for instance, create a set of sharing links for each of your customers and render them depending on which of your customers is logged in.

Note: Although this approach is straightforward to setup, it can become hard to manage with more than a handful of links, so see #3 and #8 below for an approach that uses single sharing link but still allows to have the dashboard display data customized for the user accessing it.

 

3. Passing in filters via url parameters (Business plan)

The Business plan also allows to change the filters on sharing link by passing URL parameters. This would not make the dashboard interactive for the user via the UI, but would allow to render non-interactive dashboard with different filters applies.

Note that the user who has access to the sharing link can also make these URL parameter modifications himself, so this is not a full implementation of separating access to different users (as below covered in #6, #7, #8) 

Here are details on the possible URL parameters:

aggregation: 
value type: String
possible values: minute, hour, day, week, month, quarter, year

timerange:
value type: String
possible values: 

  • absolute timerange as 2 unix timestamps separated with tilde (e.g. 1483228800~1485907199), either side of the timerange missing would have the before/after meaning - i.e. "~1485907199" means before Jan/31 2017
  • relative timerange as 2 values separated with
    • Last: <number><unit> - e.g. 7_days
    • This: this_<unit> - e.g. this_day
    • Previous: previous_<unit> - e.g. previous_month

filters:
value type: Object that maps filter variable to array of string values:

{ <filter_variable>: ["value1", "value2"] }

in the URL this object is stringified and URL encoded via encodeURIComponent function

All of these can be seen in the regular dashboard URL, so for instance for this dashboard link with modified filters: 

if you run in your console:

decodeURIComponent('%7B"day_of_week"%3A%5B"1"%5D%2C"origin_airports"%3A%5B"IAH"%2C"LAX"%5D%7D')

you will see that the encoded value is a stringified JSON object:

"{"day_of_week":["1"],"origin_airports":["IAH","LAX"]}"

 

4. Embedding interactive dashboard (Business plan)

With the Business plan, the embedded dashboard/report can have the same full interactive filter bar as regular dashboard. You can see an example here.

By default this option is only available for sharing links that are secured via additional sharingSecret token to make sure you have access to the interactive dashboard under full control. To enable this for any of your regular sharing links, please contact our support.

 

5. Embedding interactive dashboard with your own controls for interactivity (Business plan)

There are many use-cases for embedded analytics that require showing different dashboards, reports or applying filters based on changes in your web application. This can be accomplished easily by replacing the iframe with a different link (different sharing token or changing the URL parameters as in #3). But if you have a SPA (single-page application), you can achieve much better and fluid results by driving the iframe using postMessages instead of replacing the iframes (which always causes it to completely reload). Using postMessages, you can:

  • smoothly switch between full-screen (within the iframe) reports on the dashboard
  • change any filters of the dashboard/report
  • change other parameters of the embedded dashboard/report

You can see an example of some of these on our sample Tickit application here: https://tickit.cluvio.com, with the source code being available on Github (coming soon).

The View By filter on top of the page works exactly this way - these are controls within your application that trigger Javascript postMessage to the embedded iframe:

<script>
  function changeParam(param, value) {
  var message = { params: {} };
  message.params[param] = value;
  document.getElementById("embed-1").contentWindow.postMessage(JSON.stringify(message), '*');
  }
</script>
<ul>
  <li><a href="#" onclick="changeParam('aggregation', 'week')">Week</a></li>
  <li><a href="#" onclick="changeParam('aggregation', 'month')">Month</a></li>
  <li><a href="#" onclick="changeParam('aggregation', 'quarter')">Quarter</a></li>
  <li><a href="#" onclick="changeParam('aggregation', 'year')">Year</a></li>
 </ul>

The available messages are:

  • { action: 'downloadImage' }
  • { action: 'downloadImage' , params: { reportId: 'abcd-efgh-1234' }}
  • { action: 'downloadPDF' }
  • { action: 'downloadPDF', params: { reportId: 'abcd-efgh-1234' }}
  • { action: 'downloadExcel' }
  • { action: 'switchReport', params: { reportId: '' }}
  • { action: 'applyFilters', params: { aggregation: '', timerange: '', filters: '' }}

 

6. Further securing of embeds or sharing links (Business plan)

If you turn on the 'Requires secret' flag for a sharing link, the dashboard will now require an additional URL parameter sharingSecret, which is a JWT token you have to generate on your backend. This enhances the security of the sharing link and allows you to generate short-lived links on-the-fly to have access under full control.

The JWT token is a hash encoded with the secret for your account (you can get it in the Secrets section on the Organization admin page) with the following basic attributes:

{
  "sharing_token": "<sharing_token value from the sharing link>",
  "exp": "<expiration unix timestamp"
}

Both sharing_token and expiration are required to be present.

The JWT library is available for most programming languages, but always make sure to generate the token on backend, never in browser. 

Here is an example code in Ruby/Rails to generate the sharingSecret value:

require 'JWT'
hash = {
  sharing_token: 'fc77dd26-1b9d-417d-9489-518bc4ab7431', # value from sharing link
  exp: (Time.now + 10.years).to_i # should be short
}
secret='d880b5e74cea82a4e8998ae0e8775176fb440a4569eb097505f7e08e555b17b5aad78b5fa1f47acd1fbfbd876631dfdd' # value from Organization settings
JWT.encode(hash, secret)

Running this produces this value: 

eyJhbGciOiJIUzI1NiJ9.eyJzaGFyaW5nX3Rva2VuIjoiZmM3N2RkMjYtMWI5ZC00MTdkLTk0ODktNTE4YmM0YWI3NDMxIiwiZXhwIjoxODMzMDE5MDM5fQ.UrwXZo7w2Dxf9a_2wrr3_wGQ4umRZYTmATXfaQ7npQI

And when used in a sharing link, the full URL is:

https://dashboards.cluvio.com/dashboards/wm73-peg8-y0qv/shared?sharingToken=fc77dd26-1b9d-417d-9489-518bc4ab7431&sharingSecret=eyJhbGciOiJIUzI1NiJ9.eyJzaGFyaW5nX3Rva2VuIjoiZmM3N2RkMjYtMWI5ZC00MTdkLTk0ODktNTE4YmM0YWI3NDMxIiwiZXhwIjoxODMzMDE5MDM5fQ.UrwXZo7w2Dxf9a_2wrr3_wGQ4umRZYTmATXfaQ7npQI 

 

7. Embedding interactive dashboards with only subset of filters interactive (Business plan)

There are several use-cases where it is important to render a dashboard where the user is prevented from tampering with the filters and see data that he should not have access to:

  • secure non-interactive dashboards shown to different users/clients/etc.
  • secure interactive dashboards where only some of the filters are interactive/changeable by the user

Building on the secured sharing links (#6), we can achieve both of these, by passing an additional parameter to the JWT token:

fixed_parameters: { param1: value1, param2: [ value2, value 3 ] }

Here are couple fully working examples:

hash = {
  sharing_token: 'fc77dd26-1b9d-417d-9489-518bc4ab7431', # value from sharing link
  exp: (Time.now + 10.years).to_i, # should be short,
  fixed_parameters: {
    aggregation: 'month',
    countries: 'Germany'
  }
}

Result dashboard - Germany by month 

hash = {
  sharing_token: 'fc77dd26-1b9d-417d-9489-518bc4ab7431', # value from sharing link
  exp: (Time.now + 10.years).to_i, # should be short,
  fixed_parameters: {
    aggregation: 'quarter',
    day_of_week: [1,2,3],
    countries: ['Canada', 'United States']
  }
}

Result: US and Canada by quarter, with only Monday and Tuesday flights

 

Note: The value of each of the fixed_parameters keys for custom filters can be either a single value or an array of values.

8. Embedding dashboard for logged-in users (Business plan)

Building on #7, it is now easy to build dashboard based on logged in users.

You can use something like user_id, project_id, user_email, etc to identify what the user should see and then add this to the WHERE clause of your report queries:

SELECT SUM(price) from sales WHERE {salesrep_id=user_id}

and when generating the JWT token, fix the user_id filter to the value of the logged-in user:

hash = {
  sharing_token: '<token>',
  exp: (Time.now + 1.hour).to_i,
  fixed_parameters: {
    user_id: <logged-in user id>
  }
}

With sharingSecret generated from this, all of the queries with {salesrep_id=user_id} in the WHERE clauses will be restricted to the passed in user_id

 

Related articles