Holistics Docs - End-to-End Business Intelligence Platform

Holistics Documentation

Welcome to the Holistics Documentation page. 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!

Get Started

Embedded Analytics

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

What is Embedded Analytics

Holistics Embedded Analytics helps 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 Dashboards

From your Dashboard, select Settings > Dashboard Preferences > Embedded Analytics.

After generating the unique embed link for the Dashboard, you will see Embed Code and Secret Key.

  • Embed Code: Unique code of your embed link
  • Secret Key: Unique secret key used to encode/decode data

Then click Preview to go to Embed Analytics Sandbox.

3. Configure Embedded Analytics Sandbox

3.1. Embed Setting

3.1.1. Permission Settings

Permission Settings can be used as access restrictions for some particular user groups when viewing your Embedded Dashboard. For example, you don't want your dashboard viewers from Vietnam to see data from Singapore, that's when Permission Settings jump in and help control it.

Our permission is currently Row-based/horizontal data access meaning that you can control which records a user can retrieve from your organization's database.

Each permission setting comprises of path, operator, values and modifier

The combination of Operator, Values, and Modifier constructs the condition that will be applied to restrict data of a particular field.

The Path will help define the exact field on which the condition will be applied. Since the field name could be identical in 2 different models so the path will include dataset uname, model name, and field name.

permissions = {
  "row_based": [
    {
      "path": "ecommerce.ecommerce_cities.name",
      "operator": "is",
      "values": [
        "Ho Chi Minh",
        "Ha Noi"
      ],
      "modifier": null
    },
    {
      "path": "ecommerce.ecommerce_orders.status",
      "operator": "is",
      "values": [
        "delivered"
      ],
      "modifier": null
    },
    {
      "path": "orders_master.orders_master.status",
      "operator": "is",
      "values": [
        "cancelled",
        "refunded"
      ],
      "modifier": null
    }
  ]
}

Some notes

  • Row-based data access need to be applied to all the datasets that need restriction
  • If the widget does not reach the field in the path (due to lack of necessary relationship), the condition will not be applied to that widget

Let us take a quick example, your dashboard is using data from 2 different datasets Sales and Product.

  • Sales dataset includes: deals, organizations, and country
  • Product dataset includes: features, users, and country

If you want to apply restriction on country_name field in country model, remember to do that in both Sales and Product datasets.

3.1.2. Filter Settings

You can pre-define the default filter value that will be automatically applied to the embedded dashboard.

If there are any dashboard filters that you don't want your users to see or change, you could easily hide them using the syntax "hidden": true, .

filters = {
  "gender": {
    "hidden": false,
    "default_value": {
      "operator": "is",
      "values": [
        "f"
      ],
      "modifier": null
    }
  },
  "country": {
    "hidden": true,
    "default_value": {
      "operator": "is",
      "values": [
        "Vietnam"
      ],
      "modifier": null
    }
  }
}

3.2. Generated Code

The code that generated from your Embed Settings and will be then used to add to your own application

It includes embed code, secret key, permission and dashboard's filter

4. Run and Preview your Generated Code

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

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.

Note: To send multiple values to your multi-select dropdown, just put an array in your payload. Example:

payload = { 
  brands: ['singarore', 'india', 'usa'],
  exp: expired_time
}

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>

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

For security purpose, it's recommended to use HTTPS when embedding Holistics in your side.

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

Issue: ActionController::InvalidAuthenticityToken

There are 2 reasons

  • Make sure your site has https
  • Enable 3rd-party cookies in your browsers

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

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

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

Updated 4 days ago

Embedded Analytics


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

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.