Holistics Docs - End-to-End Business Intelligence Platform

The Holistics Documentation

Welcome to the Holistics Documentation. You'll find comprehensive guides and documentation to help you start working with Holistics as quickly as possible, as well as support if you get stuck. Let's jump right in!

Guides    Get Started

Embedded Analytics

Help you embed a Holistics dashboard inside your own web application so that your customers/users can view the data.

Sample Use-cases

  • Embed inside your CRM Application, set up the right dashboards for the right customers
  • E-commerce/Retails: Embed dashboards into Web/Mobile App to deliver insights to each merchant
  • Include your Dashboard or Report publicly on your website

How to use

1. Enable Embedded Analytics

Go to Embed Link Manager, click Configure button and enable it.

2. Create Embed Link for Reports/Dashboards

From any Dashboard/Report, select Settings > Embed Links.

Then click on New Embed Link to generate new link.

3. Configure Embed Link

Embed link includes:

  • Internal Note (optional): Simple note for reference purpose
  • Advanced Filter Display: Make the filters changeable or static
  • Embed Code: Unique code of your embed link
  • Secret Key: Unique secret key used to encode/decode data
  • Client Identifier Variables: Embed filters which is hard set in code and couldm't be changed by viewers

To add new embed filter, you could click on Add button in client identifier variables section.

Then choose embed filter you want to add.

Note: In the new embedded analytics, you could add multiple embed filters as you want.

Finally, click Save to update link.

4. Test Your Link

To check out your embed link present, you could click on Preview.

After Embedded Sandbox is loaded, you could customize params and click on Run to view simulated dashboard on your app.

5. 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.

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:

erbruby
<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>

Advanced Filters

Advanced filters allow you to override default value or lock / unlock dynamic filters.

Legacy Embed Links

We also support legacy embed links (require Customer ID as default embed filter), it means that your previous embed links works well in new embedded analytics system.

Note: To change or add more filters, you should generate new embed link.

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 the 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 an 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

  1. Please open Chrome settings, type "third" in the search box, click the Content Settings button and view the fourth item under Cookies.
  2. 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.