Skip to main content
This tutorial will get you up and running with a working embedded dashboard in just 5 minutes. We’ll use a sample token and dashboard so you can see results immediately.

​
What You’ll Build

By the end of this tutorial, you’ll have:
  • ✅ A working embedded DataBrain dashboard
  • ✅ Understanding of the core embedding concepts
  • ✅ A foundation to build upon for production

​
Prerequisites

  • Node.js 14+ installed
  • A React, Vue, or vanilla JavaScript project
  • 5 minutes of your time ⏱️

​
Step 1: Install the Package

npm install @databrainhq/plugin

​
Step 2: Import the Plugin

Add this import to your component or main file: 
import '@databrainhq/plugin/web';

function Dashboard() {
  return (
    <dbn-dashboard 
      token="3affda8b-7bd4-4a88-9687-105a94cfffab" 
      dashboard-id="ex-demo" 
    />
  );
}

export default Dashboard;

​
Step 3: Run and View

Start your development server and you should see the sample dashboard! 🎉 
npm run dev
# or
npm start
Congratulations! You’ve embedded your first DataBrain dashboard. The dashboard you’re seeing is a sample with demo data.

​
Understanding What You Built

Let’s break down the code:

​
The Component

<dbn-dashboard token="..." dashboard-id="..." />

​
The Token

token="3affda8b-7bd4-4a88-9687-105a94cfffab"
This is a guest token - a temporary access token that allows viewing the dashboard. In production, you’ll generate these from your backend.

​
The Dashboard ID

dashboard-id="ex-demo"
This identifies which dashboard to display. Each dashboard in DataBrain has a unique ID.

​
Next: Make It Production-Ready

The sample above works great for testing, but for production you need to:

​
1. Create Your Own Dashboard

  1. Create your own dashboard at app.usedatabrain.com
  2. Connect your database as a data source
  3. Build your metrics and dashboards
  4. Create a Data App for embedding
  5. Generate tokens from your backend (see below)

Complete Setup Guide

Follow the full setup process

​
2. Generate Tokens from Your Backend

Security First: Never expose your API token in frontend code. Always generate guest tokens from your backend.
Here’s how token generation works: Token Flow: 
1. User accesses dashboard
   ↓
2. Frontend → Backend (request guest token)
   ↓
3. Backend → DataBrain API (POST /guest-token/create)
   ↓
4. DataBrain API → Backend (return guest token)
   ↓
5. Backend → Frontend (return guest token)
   ↓
6. Frontend → Dashboard component (render with token)

​
Backend Example (Node.js)

// backend/api/get-token.js
import fetch from 'node-fetch';

export async function getGuestToken(userId) {
  const response = await fetch(
    'https://api.usedatabrain.com/api/v2/guest-token/create',
    {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${process.env.DATABRAIN_API_TOKEN}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        clientId: userId,
        dataAppName: 'your-data-app-name'
      })
    }
  );
  
  const data = await response.json();
  return data.token;
}

​
Frontend Example (React)

import { useEffect, useState } from 'react';
import '@databrainhq/plugin/web';

function Dashboard({ userId }) {
  const [token, setToken] = useState(null);

  useEffect(() => {
    // Fetch token from YOUR backend
    fetch('/api/get-databrain-token', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ userId })
    })
      .then(res => res.json())
      .then(data => setToken(data.token));
  }, [userId]);

  if (!token) return <div>Loading...</div>;

  return (
    <dbn-dashboard 
      token={token} 
      dashboard-id="your-dashboard-id" 
    />
  );
}

Guest Token API

Complete token generation API docs

​
3. Customize the Dashboard

Add options to customize appearance and behavior: 
<dbn-dashboard 
  token={token}
  dashboard-id="your-dashboard-id"
  enable-download-csv
  enable-email-csv
  custom-messages={JSON.stringify({
    tokenExpiry: "Your session has expired. Please refresh.",
  })}
  theme={JSON.stringify({
    general: {
      primaryColor: '#0066CC',
      backgroundColor: '#FFFFFF'
    }
  })}
/>

Component Options

Explore all customization options

​
Embed a Single Metric

You can also embed individual metrics instead of full dashboards: 
<dbn-metric 
  token={token}
  metric-id="your-metric-id"
/>

​
Common Customizations

  • Hide Elements
  • Enable Downloads
  • Custom Theme
  • Event Handlers
<dbn-dashboard 
  token={token}
  dashboard-id="dashboard-id"
  is-hide-chart-settings
  is-hide-table-preview
/>

​
Framework-Specific Guides

Get detailed integration guides for your framework:

React

React integration guide

Next.js

Next.js with SSR support

Vue

Vue 3 integration

Angular

Angular setup guide

Svelte

Svelte integration

Vanilla JS

Plain JavaScript

​
Troubleshooting

Check:
  • Plugin is imported before component renders
  • Token is valid and not expired
  • Dashboard ID is correct
  • No console errors
Solution: Generate a fresh token from your backend. Guest tokens can be set to expire after a certain time.
Fix: Ensure your domain is whitelisted in the Data App settings. Or generate tokens from your backend instead of frontend.
Try:
  • Check for CSS conflicts
  • Use custom theme options
  • Wrap in a container div
  • Check z-index values

Troubleshooting Guide

Complete troubleshooting reference

​
What’s Next?

You’ve successfully embedded a DataBrain dashboard! Here’s what to explore next:

Complete Setup

Production-ready setup guide

Security & Auth

Multi-tenancy and access control

Customization

Advanced customization options

API Reference

Complete API documentation

​
Need Help?

Interactive Playground

Experiment with live examples

Community & Support

Get help from our team