Overview – Cluvio

Available on plans: Pro, Business, Enterprise

Cluvio allows embedding of full dashboards or individual reports within web applications at different levels of integration:

Making a dashboard an integral part of your website (available in the Pro or Business plan).
Embedding a dashboard with constrained filters applied (available in the Business plan).
Embedding a dashboard with parameters specific for a particular user of your web application (available in the Business plan).

In all of these cases, whether the embedded dashboard is interactive or not, it is always displaying the latest data as well as reflecting any changes made to the dashboard, i.e. it behaves the same way as for a viewer accessing the dashboard in the context of a regular Cluvio account. The following screenshot gives an idea of how an embedded dashboard may look like.

Embedding Options

Below is a summary of embedding options, in increasing level of complexity and functionality.

1. Non-interactive dashboards (Pro or Business plan)

Embedding a non-interactive dashboard or individual report is accomplished by creating a sharing link and using the provided HTML snippet (which you can see by clicking on Embed for the link in question):

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

This iframe pulls its content from the sharing link, identified by the sharingToken URL parameter, with the fixed dashboard parameters associated with the link. However, some additional URL parameters available for every link can be used to further refine the appearance of the embedded dashboard, as explained on the page about sharing links. E.g. to share a single report, use the reportId parameter:

<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" 
/>

By creating multiple links, each fixed to different dashboard parameters, the same dashboard can be embedded in a non-interactive way in different contexts. For instance, creating a sharing link for the same dashboard for each customer, each time parameterized differently. However, while this approach is straightforward to set up, it can become hard to manage with more than a handful of links. See options #2 and #7 below for approaches that use a single sharing link but still allow the dashboard to display data customized for each user accessing it.

2. Dashboard parameters via URL parameters (Business plan)

With the Business plan, it is possible to change the dashboard parameters through a link by passing them as additional URL parameters. To do so, the link must have the Allow Parameters option enabled. The embedded dashboard need not be interactive for the user via the UI, thus enabling non-interactive dashboards with different dashboard parameters through a single link. Note, however, that the user who has access to the link can change the URL parameters, so the non-interactivity is not strictly enforced. For details on how to encode the URL parameters for the dashboard parameters, see the page on dashboard parameters in URLs.

3. Interactive dashboards with default controls (Business plan)

With the Business plan, by allowing dashboard parameters as URL parameters, the embedded dashboard or report can have the same interactive controls as a regular dashboard. To that end, the sharing link must have been created with the Show Toolbar and Allow Parameters options, so that dashboard parameters can be passed as URL parameters. Additionally, by default, this option is only available for sharing links that are secured via an authenticated JWT sharingSecret, i.e. the Requires Secret option must be set on the link. To enable this feature for any of your regular sharing links without a sharingSecret, please contact our support for your use-case.

4. Interactive dashboards with custom controls (Business plan)

Embedding interactive dashboards with custom controls is very similar to #3, but instead of enabling the Show Toolbar option, the embedded iframe can be updated via postMessage from the parent frame as a result of actions being performed on your own UI controls. Using postMessage, you can e.g.

smoothly switch between full-screen reports (within the iframe) on the dashboard.
change any dashboard/report parameters.

An example of an embedded dashboard with custom controls is the Tickit application at https://tickit.cluvio.com, where changing a parameter works as follows:

<script>
  function changeParam(param, value) {
      var message = { action: 'applyFilters', 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 embedded dashboard supports the following messages:

{ action: 'downloadImage' }
{ action: 'downloadImage' , params: { reportId: '<id>' }}
{ action: 'downloadPDF' }
{ action: 'downloadPDF', params: { reportId: '<id>' }}
{ action: 'downloadExcel' }
{ action: 'switchReport', params: { reportId: '<id>' }}
{ action: 'applyFilters', params: { aggregation: '<value>', timerange: '<value>', filters: '<value>' }}

5. 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 the backend, never in the 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

6. Embedding interactive dashboards with only a 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 a 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.

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

Building on #7, it is now easy to build a 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

Embedded Analytics

Embedding Options

Related articles