Tutorial: How to Embed your Holistics Dashboard
Introduction
Embedded Analytics is the integration of analytical capabilities within your business platform to serve multiple purposes: build dashboards for your clients, your investors, or your managers, to deliver analytics right from within your own applications. For example:
- 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
- The target audience for this guide is Developers.
- We will use Ruby for this entire demo. The basic concepts will be the same no matter what language you use for your websites/applications.
Working example
Context
Company A (an eCommerce company) operates in 3 countries (Vietnam, China, Singapore). Each branch is only allowed to see data from their branch. All the transactional data of 3 countries are consolidated in one single Data Warehouse.
A Data Analyst builds a dashboard to visualize Business Performance for each client/branch so they can view their reports inside their web app/mobile app.
We have a setup as follow:
// Models and dataset definitions in AML
Model orders {...}
Model order_items {...}
Model products {...}
Model categories {...}
Model users {...}
Model countries {...}
Model cities {...}
Model merchants {...}
Dataset ecommerce {
label: 'Ecommerce Dataset'
description: ''
data_source_name: 'demodb'
models: [
orders,
order_items,
products,
categories,
users,
countries,
cities,
merchants
]
relationships: [
relationship(order_items.order_id > orders.id, true),
relationship(order_items.product_id > products.id, true),
relationship(orders.user_id > users.id, true),
relationship(products.category_id > categories.id, true),
relationship(products.merchant_id > merchants.id, true),
relationship(cities.country_code > countries.code, true),
relationship(users.city_id > ecommerce_cities.id, true)
]
owner: '[email protected]'
}
Expected result
When users log in your admin page and view dashboard, you would expect the following behaviors:
- General Manager: can see revenue of all stores
- Vietnam Manager: can see revenue of all stores in Vietnam
- HCMC Manager: can see revenue of stores in HCMC
- External consultant: can have access to Vietnam stores and a store in Singapore
How to Embed the dashboard into your application
1. Enable Embedded Analytics
On the header, click on Tools (the wrench icon) -> Embedded Analytics to open the Embedded Analytics manager
From here you can toggle Embedded Analytics feature on or off, or set the amount of Embed Workers that you want to employ:
For more information, please refer to the Embed Workers documentation.
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 the 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 Embedded Analytics Sandbox.
3. Generate Embed code with Embedded Analytics Sandbox
The purpose of permission and filter settings in the Embedded Analytics Sandbox is to generate a basic embed code interactively. You will need to customize it to suit your business needs before adding it to your websites / applications.
3.1. General Settings
3.2. Permission Settings
Our permission system for embedded links allows Row-based/horizontal data access . This means you can control which records a user can retrieve from your organization’s database.
For example, to create a rule so that only data from Vietnam is shown, click Add Permission, select the dataset ecommerce -> model countries -> field name, and choose Vietnam as value.
The following code snippet will be generated:
permissions = {
"row_based": [
{
"path": {
"dataset": "ecommerce",
"model": "countries",
"field": "name"
},
"operator": "is",
"modifier": nil,
"values": [
"Vietnam"
]
}
]
}
...
3.3. Controls Settings
Here you can set the default value for your Dashboard’s filters, or hide them to prevent your Dashboard’s viewers from adjusting the filter’s values.
Let's say you want to show the data of the last 6 months by default when presenting the embedded dashboard. You can set the filter as below:
The following code snippet will be generated:
filters = {
"created_at": {
"hidden": false,
"default_condition": {
"operator": "matches",
"values": [
"last 6 months"
],
"modifier": nil
}
},
...
# Other controls settings
}
...
4. Generate Embed Token
After configuring general settings, permissions and controls settings, you need to generate a token. The payload of the token should refer to the settings, permissions, filters that we have generated above, and an expired time, which specifies a time to expire your issued token.
Example:
# Will expire after 1 day, change it to the value you want.
# Note that expired_time is of type Unix Time. E.g 1498795702
expired_time = Time.now.to_i + 24 - 60
payload = {
settings: settings,
permissions: permissions,
filters: filters,
exp: expired_time
}
We use JWT (JSON Web Token) as a mechanism to authenticate the code.
token = JWT.encode(payload, secret_key, 'HS256')
You can get the secret_key of the embed link by opening Embedded Analytics Sandbox and looking for secret_key in the Embed code section
5. Customize the Embed code
You will need to modify the sample code generated from the Embedded Analytics Sandbox above to fit your business needs.
To achieve the expected result mentioned earlier, we configured so that each user (logged in with a unique email) is associated with a different set of values for country, city and store:
var country = []
var city = []
var store = []
var filters_country = []
// current_user() is to get the current user logged in
if (current_user().email == "[email protected]") {
country = []
city = []
store = []
} else if (current_user().email == "[email protected]") {
country = ['Vietnam']
city = ['Hanoi', 'HCMC']
store = ['6', '7', '8']
} else if (current_user().email == "[email protected]") {
country = ['Vietnam']
city = ['HCMC']
store = ['7', '8']
} else if (current_user().email == "[email protected]") {
country = ['Vietnam', 'Singapore']
city = ['Hanoi', 'HCMC', 'Singapore']
store = ['6', '7', '8', '31']
}
var permissions
var filters
var payload
permissions = {
row_based: [
{
path: "ecommerce.ecommerce_countries.name",
operator: 'is',
values: country
},
{
path: "ecommerce.ecommerce_cities.name",
operator: 'is',
values: city
},
{
path: "ecommerce.ecommerce_merchants.id",
operator: 'is',
values: store
}
]
}
filters = {
"city_name": {
"hidden": false,
"default_condition": {
"operator": "is",
"values": [],
"modifier": null
}
},
"country": {
"hidden": false,
"default_condition": {
"operator": "is",
"values": [],
"modifier": null
}
},
"merchant_id": {
"hidden": false,
"default_condition": {
"operator": "is",
"values": [],
"modifier": null
}
},
"order_date": {
"hidden": false,
"default_condition": {
"operator": "matches",
"values": [
"last 6 months"
],
"modifier": null
}
},
"order_status": {
"hidden": true,
"default_condition": {
"operator": "is",
"values": [
"delivered"
],
"modifier": null
}
}
}
payload = {
permissions: permissions,
filters: filters,
exp: expired_time
}
token = JWT.encode(payload, secret_key, 'HS256')
With this, we have brought all of the ingredients together
6. Add the Embed code to your websites / applications
Finally, you need to 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 according to the permissions of that user.
<!-- Embedded Ruby(erb) template -->
<iframe src="https://secure.holistics.io/embed/<%= embed_code %>?_token=<%= token %>"
style="width: 100%; height: 600px;"
frameborder="0"
allowfullscreen>
</iframe>
The embed_code value can be found in the Embed code section in the Sandbox:
