Embedded Analytics

Embedded Analytics is a feature where you can embed a Holistics dashboard inside your own web application so that your customers/users can view the data.

Requirements:

You can embed a code/iframe inside your CRM Application, specify a CustomerID (or HotelID, RestaurantID, UserID, OrganizationID, etc..) and it should load the dashboard/report for that particular customer.
Your customers can only view the report, without being be able to modify that report, so they just consume their own data.

Below is a step by step guide on how you can use Holistics' Embedded Analytics feature

1. Enabled Embedded analytics

Please go to Embed Link Listing, click Configure button and enable it.

Enable Embed

2. Preparing Dashboard Data

First, make sure you have a dashboard with your data in it, which uses a filter to select different customers included. For example, this can be a dropdown filter called "Customer".

3. Generate Embed Code

Then go to the Settings icon -> Embed Links, where you'll be presented with a dialog to generate/get the embed link. Simply follow the instructions in the dialog.

Please note down the following details:

Embed ID: Unique code of your embed link
Secret Key: a unique, secret key used to encode/decode data

4. Integrate Into Your Application

Note that your customers do not have to sign in inside Holistics to see the shared reports. Therefore, you are required to issue an encrypted token for your customer. The token is for us to:

Correctly identify which of your customers is viewing the dashboard.
Prevent your customers from faking their identity by simply changing the parameters inside the url.
Expire the token after a specified period of time.

We use JWT (JSON Web Token) as a mechanism to authenticate the code. This is how it works:

When a customer visits your app that needs embedding Holistics, your backend will take the customer ID and generate a token based on the secret key above.
You then render an iframe pointing to the embed link, with the token baked into it.
Holistics then use this token to authenticate and figure out which Customer is logging in, and display your dashboard with only that customer's data.

Integration Sandbox

Please use our Integration Sandbox to test your embed link, and also get sample code in your preferred language.

Sample Code (In Ruby)

First, install jwt gem. Do this in your gemfile:

gem 'jwt'

In your controller:

SECRET_KEY = "YOUR_SECRET_KEY"
EMBED_CODE = '73hfu41h8ih801mc'
BASE_URL = 'https://secure.holistics.io' 

# E.g: your filter's value is 1 and you want to expire the token after 24 hours
customer_id = 1 # please replace this with the actual customer's ID

# Note that expired_time is of type Unix Time. E.g 1498795702
expired_time = Time.now.to_i + 60 * 60 # expire in 1 hour 

# Symbol customer_id and exp must not be modified.
data = {
  customer_id: customer_id, 
  exp: expired_time
} 

# Encode data, generate token
token = JWT.encode(data, SECRET_KEY, 'HS256') 

# The iframe URL:
iframe_url = BASE_URL + '/embed/' + EMBED_CODE + '?_token=' + token

Then in your view, simply include an iframe with that URL:

<iframe src="<%= iframe_embed %>" 
  frameborder="0" 
  style="width: 100%;height: 600px" 
  allowfullscreen>
</iframe>

The final iframe code would look like:

<iframe src="https://secure.holistics.io/embed/73hfu41h8ih801mc?_token=8bho21nv7gpuiad78tas9gbanp8hv" 
  frameborder="0" 
  style="width: 100%;height: 600px" 
  allowfullscreen>
</iframe>

Security

Here are a few things to note regarding security:

Secret Key

The key we issue you in step 2 is to sign your payload with HMAC 256 signature mechanism. This signature is for us to check the payload's integrity and prevent people from tampering and modifying your payload during the request.

Token Expiration

You must specify a time to expire your issued JWT. The recommended expired time is 24 hours after you issue the token. The reason behind this is to deal with situation when someone steals the JWT of your customer (not difficult to do so) and issue it elsewhere. The stolen token will be expired in a short time so damage is minimized.

Sensitive Data

Note that the JWT only allows us to check the integrity of the received payload. No cryptography is involved in JWT, and your payload's information is not securely concealed from others. Please do not include any sensitive data inside the payload

Reset Secret Key

In case your secret key is leaked, you can go to the embed analytics editing section and click Reset Secret Key.

FAQs

If you have issue showing the embed, please check browser's console log for the error:

Uncaught SecurityError: Failed to read the 'localStorage' property from 'Window': Access is denied for this document:

Please open Chrome settings, type "third" in the search box, click the Content Settings button, and view the fourth item under Cookies.
Make sure that option "Block third-party cookies and site data" is unchecked.

If this setting is checked, third-party scripts cookies are disallowed and access to localStorage may result in thrown SecurityError exceptions.

{{ section.section }}