Embedded Analytics

Definition

In Holistics, Embedded Analytics helps you embed a Holistics dashboard inside your own web application so that your customers/users can view the data.

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

Benefits

• Your Engineers don't have to waste time building the dashboard for your application from scratch.
• Your Viewers/Users don't need to login inside Holistics to view your Dashboard.
• Prevent data leakage: your viewers can only see data that you allow them to see.
• White-labeling: Remove Holistics’ logo so you can keep your brand consistent in your applications.

Video Guide

Watch the below video to understand how we set up embedded dashboards step-by-step.

Setting Up Embedded

This section will show you the overall steps to embed your Holistics dashboard into your application

1. Enable Embedded Analytics Embed Link Manager
2. Create Embed Link for your Dashboard
3. Configure Permission Settings (optional)
4. Configure Filter Display Settings (optional)
5. Configure Other Settings (optional)
6. Configure Embed Drill Through (optional)
7. Generate Embed Tokens
8. Generate Embed URL and Integrate into your application

Mechanism

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.

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.

Security

For security purpose, it's recommended to use HTTPS when embedding Holistics in your side. Please refer to our doc here about Security in Embedded Analytics for more information

FAQs

For all the common questions about Holistics Embedded Analytics, please refer to our Document here for more information.

Sample Code

Below is the sample code of Holistics Embedded Analytics, and we use Ruby as the example.

# Example code below uses JWT for encoding
# Execute 'gem install jwt' (or add gem 'jwt' to your GemFile) to install it first

embed_code = 'your_embed_code'
secret_key = 'your_secret_key'

# Will expire after 1 day, change it to the value you want.
expired_time = Time.now.to_i + 24 * 60 * 60
settings = {
  "enable_export_data": false/true
}

# Row-level Permission Settings
permissions = {
  "row_based": [
    # permission rule 1
    {
      "path": "data_set_name.data_model_name.field_name",
      "operator": "expected_operator",
      "modifier": nil,
      "values": [
      "your_expected_value"
      ]
    },

    # permission rule 2
    {
      "path": "data_set_name.data_model_name.field_name",
      "operator": "expected_operator",
      "modifier": nil,
      "values": [
      "your_expected_value"
      ]
    }

  ]
}

# Filter Display Settings
filters = {
    "your_filter_name": {
      "hidden": false/true,
      "default_condition": {
        "operator": "THE_OPERATOR",
        "values": ["your default value"],
        "modifier": "THE_MODIFIER"
    }
  }
}

# Enable Drill-Through for your Embedded Dashboard
drillthroughs = {
  "destination_dashboard_id_1": {
    # other settings of this destination dashboard go here
  },

  "destination_dashboard_id_2": {
    # other settings of this destination dashboard go here
  }
}

# Add all above settings to the payload
payload = {
  settings: settings,
  permissions: permissions,
  filters: filters,
  drillthroughs: drillthroughs,
  exp: expired_time,
}

# Generate Embed Token
token = JWT.encode(payload, secret_key, 'HS256')

After that, you need to include the HTML iframe in your application:

<!-- Embedded Ruby(erb) template -->
<iframe
  src="https://secure.holistics.io/embed/<%= embed_code %>?_token=<%= token %>"
  style="width: 100%; height: 600px;"
  frameborder="0"
  allowfullscreen
>
</iframe>