Skip to main content

Quickstart

In this guide, you'll embed a live Holistics dashboard into your web app. There is a single setup for every embedding use case: generate one set of embed credentials, describe what to show in a signed embed payload, and load it in an iframe. Later, when you want exploration, user-built dashboards, or Ask AI, you add a few keys to the same payload.

How it works​

Before writing any code, here's the shape of what you're building:

  1. Holistics holds the content and one credential. Your dashboards and datasets live in Holistics. You generate a single Key ID and Secret for all your embeds.
  2. Your backend describes each view in a signed payload. The payload names the dashboards (and optionally datasets) to show, who the viewer is, and what they can see and do. You sign it with the Secret to produce a token.
  3. Your frontend loads an iframe. The iframe URL combines your Key ID and the token. Holistics verifies the token and renders exactly what the payload allows, filtered to that viewer's data.
How embedded analytics works
  • 1. Embed credential
  • 3. Frontend
  • 2. Backend
  • iframe-box — The path carries the Key ID from your shared credential. There is no per-dashboard embed code.
  • [HTML node]
  • embed_key_id — The Key ID from your shared embed credential.
  • [HTML node]
  • token — The signed JWT your back end just produced.
  • [HTML node]
  • [HTML node]
  • Payload — One payload describes what to show, who is viewing, and what they may do.
  • Content: Dashboards, Datasets
  • Permissions
  • User settings
  • and more
  • jwt-box — Sign the payload with the Secret from your shared embed credential.
  • JWT.encode(
  • payload
  • ,
  • secret_key
  • , 'HS256')
  • token — A short-lived JWT. It goes in the embed URL as _token.
  • Key ID
  • Secret
  • payload-box → chip-payload
  • jwt-box → token-box
  • token-box → chip-token
  • node-2 → chip-secret
  • node-1 → chip-key

Because the payload carries everything, adding capabilities later (exploration, user workspaces, Ask AI) means editing the payload, not changing how you embed.

Prerequisites​

Before you begin, make sure you have:

  • A Holistics account with at least one dashboard built
  • A web app to embed into (any stack: Rails, Express, Django, etc.)
  • Admin access in Holistics, to enable Embedded Analytics and generate credentials

Step 1: Enable Embedded Analytics and generate credentials​

By default, Embedded Analytics is not enabled. Go to Tools → Embedded Analytics and turn on the features you need.

Then generate your embed credentials from the same page. Click Generate embed credentials and note the two values:

  • Key ID: identifies your Holistics workspace in the embed URL
  • Secret: signs the embed payload. Keep it on your backend and never expose it to the browser.
One credential for everything

You only do this once. The same Key ID and Secret work for every dashboard, dataset, and feature you embed. What each viewer sees is decided by the payload, not by the credential.

Step 2: Build and sign the embed payload (backend)​

On your server, build a payload that lists the dashboards to show, then sign it as a JWT with your Secret. Here's a minimal example: one dashboard, no permissions, just enough to get it on screen.

Dashboards are referenced by their unique name in AML (for example, sales_overview). You can copy the exact name, along with a ready-made payload, from the Embed Builder on the Embedded Analytics page.

const jwt = require('jsonwebtoken');

const embedSecret = '382fXXXXXXXX';   // Secret from Step 1

const payload = {
  objects: {
    dashboards: ['sales_overview'],   // dashboard unique name(s)
  },
  exp: Math.floor(Date.now() / 1000) + 24 * 60 * 60,  // expires in 24 hours
};

const token = jwt.sign(payload, embedSecret, { algorithm: 'HS256' });

Set exp so the token expires. We recommend 24 hours or less. See Token expiration for why this matters.

Set up row-level permissions before going live

The minimal payload above shows every viewer the full dashboard. If you serve more than one customer, add row-level permissions before you ship. They filter every query to the viewer's own rows and are enforced at the dataset level, so users cannot work around them by changing filters or tampering with the URL.

Step 3: Load the iframe (frontend)​

Build the embed URL on your backend from your Key ID and the signed token, then drop it into an iframe. Use the app domain for your Holistics data center. If you use a custom domain, replace the full host with it.

App domain

<iframe
  src="https://secure.holistics.io/embed/{embed_key_id}?_token={token}"
  style="width: 100%; height: 600px;"
  frameborder="0"
  allowfullscreen>
</iframe>

That's it. You should see your dashboard rendered inside your app.

Next: Add more features for your users​

Beyond viewing dashboards, your users can explore data, ask AI, subscribe by email, and more. You can enable and configure these features in the embed payload:

FeatureHow to enable
① View multiple dashboardsList the dashboard names in objects.dashboards
② Self-serve exploration: explore data, drill down, view underlying dataAdd dataset names to objects.datasets
③ See only their own dataAdd rules to permissions.row_based, or pass the viewer's user_attributes for dataset rules
④ User-built dashboards (personal + shared)Identify the user with embed_user_id and embed_org_id, then grant workspace access in permissions
⑤ Email subscriptionsAdd the user's embed_user_email and turn on settings.allow_dashboard_export and settings.allow_data_subscribe
⑥ Ask AITurn on settings.ai.enabled and include at least one dataset

Here's how those keys fit together in a payload with every feature turned on:

Each embed feature maps to a few keys in the same embed payload: dashboards, datasets, row-level permissions, user-built dashboards, email subscriptions, and Ask AI.
  • f-view → a-view
  • f-explore → a-explore
  • f-rlp → a-rlp
  • f-build → a-build
  • f-subscribe → a-subscribe
  • f-ai → a-ai

Preview your embed with the Embed Builder​

You don't need a web app to see what your embed users will get. The Embed Builder lets you set up an embed and preview it right inside Holistics, then generates the matching payload for you.

  1. Open the dashboard you want to embed, click the dashboard menu, and choose Embed. The Embed Builder opens with that dashboard already added.
  2. Add more dashboards and datasets, set row-level permissions, and turn on features such as Ask AI, user-built dashboards, and email subscriptions.
  3. Click Preview to see the embed exactly as your users will.
  4. Switch the panel from UI to JSON to copy the payload for your backend.

Optional: Manage embedded objects in Holistics with an Embed Portal​

Your payload lists each dashboard and dataset by name, so every embedded object must be kept in sync between your Holistics project and your backend. When the two don't match, your embed breaks and your users see an error.

An Embed Portal fixes this. It moves the list of embedded objects into an AML file in your Holistics project, and your payload only references the portal by name. You can then add, remove, or rename embedded objects in Holistics without redeploying your backend.

Before: the embed payload in your app backend lists every dashboard and dataset. After: the payload references one Embed Portal, and the portal lists the objects inside your Holistics project.
  • How an Embed Portal solves the sync problem
  • Before: Your payload lists every object
  • Embed payload objects: { dashboards: ['sales_overview'], datasets: ['ecommerce'], }
  • Holistics project
  • Your app backend
  • Dashboards & datasets sales_overview dashboard ecommerce dataset
  • After: Your payload references one Embed Portal
  • Holistics project
  • Your app backend
  • Embed payload + embed_portal: 'customer_portal' - objects: { ... }
  • Embed Portal (customer_portal.embed.aml) EmbedPortal customer_portal { objects: [ sales_overview, ecommerce, ] }
  • Dashboards & datasets sales_overview dashboard ecommerce dataset
  • bp-sales → bo-sales (references)
  • bp-ecommerce → bo-ecommerce
  • at-sales → ao-sales
  • at-ecommerce → ao-ecommerce
  • ap-portal → at-portal (references)

Next steps​

Open Markdown
Let us know what you think about this document :)