Skip to main content
To embed a DataBrain dashboard into your application, we offer a straightforward approach using the DataBrain npm package. Simply install this package, and then bring it into your application to access a range of components. These components enable you to display full dashboards or specific metrics as needed.

​
Multi-Tenancy Support

DataBrain supports embedding for different levels of tenancy based on how your client data is organized. Whether you separate data at the table level (rows identified by a client ID), schema level, database level, or across multiple datasources, DataBrain can handle your tenancy model. Common tenancy models include:
  • Single Table Tenancy: All client data in one table, separated by a client_id column
  • Multi-Level Tenancy: Combining multiple layers (e.g., schema + table, database + schema)
Choose the right tenancy model based on your data architecture. Learn more about choosing the right tenancy model and how to configure tenants.
We’ve got you covered with a step-by-step guide here to help you integrate DataBrain dashboards into your user interface seamlessly.

​
Step-by-Step Guide to Embed DataBrain Dashboard

1

Install DataBrain NPM Package

npm install @databrainhq/plugin
2

Import the Plugin

import '@databrainhq/plugin/web';
3

Use the Components in Your Application

For embedding a Dashboard
<dbn-dashboard token="token" dashboard-id="dashboardId" />
orFor embedding a Metric Card
<dbn-metric token="token" metric-id="metricId" />
Finding Your IDs
  • Dashboard ID: In your Data App, navigate to Embed Info > Add New Embed. Select workspace name, choose embed type as dashboard, and select the dashboard. The Embed ID displayed is your dashboard ID. See detailed guide here.
  • Metric ID: In your Data App, go to Embed Info > Add New Embed. Provide the workspace name, select embed type as metric, choose the dashboard containing your metric, then select the metric. The Embed ID shown is your metric ID. See detailed guide here.
TokenThe token should be a guest token generated from your backend using DataBrain’s REST API. Each guest token is unique and ensures secure access control.Generating a Guest Token:Make a POST request from your backend to generate the guest token:Cloud DataBrain:
POST https://api.usedatabrain.com/api/v2/guest-token/create
Self-hosted DataBrain:
POST <SELF_HOSTED_URL>/api/v2/guest-token/create
Request Headers:
{
  "Authorization": "Bearer [API_TOKEN]"
}
Minimum Request Body:
{
  "clientId": "id",           // Use "None" if no tenancy selected
  "dataAppName": "dataappname"
}
The API will return a token that you pass to your frontend. The token can include additional parameters like appFilters, dashboardAppFilters, and permissions for fine-grained control. If expiryTime is not specified, the token won’t expire.Learn more about token generation and advanced options here.Example for Embedding Dashboard:Here is an example with a sample token and dashboardId that you can use in your frontend app to get started without a backend:
<dbn-dashboard token="3affda8b-7bd4-4a88-9687-105a94cfffab" dashboard-id="ex-demo" />

​
Additional Resources and Customization

  • Customizing the Look and Feel:
    • For further customizations related to the appearance of the embedded elements, refer here.
  • Understanding the Overall Architecture:
    • For a comprehensive understanding of the overarching architecture and how embedding fits into it, refer here.
With these steps, embedding DataBrain dashboards or metrics into your application can be done efficiently, offering a dynamic and insightful data visualization component to your users.