5-Minute Embedding Tutorial

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

yarn add @databrainhq/plugin

pnpm add @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;

<template>
  <dbn-dashboard 
    token="3affda8b-7bd4-4a88-9687-105a94cfffab" 
    dashboard-id="ex-demo" 
  />
</template>

<script>
import '@databrainhq/plugin/web';

export default {
  name: 'Dashboard'
}
</script>

import '@databrainhq/plugin/web';

// In your HTML
document.body.innerHTML = `
  <dbn-dashboard 
    token="3affda8b-7bd4-4a88-9687-105a94cfffab" 
    dashboard-id="ex-demo"
  />
`;

<!DOCTYPE html>
<html>
<head>
  <script type="module">
    import '@databrainhq/plugin/web';
  </script>
</head>
<body>
  <dbn-dashboard 
    token="3affda8b-7bd4-4a88-9687-105a94cfffab" 
    dashboard-id="ex-demo"
  />
</body>
</html>

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

Create your own dashboard at app.usedatabrain.com
Connect your database as a data source
Build your metrics and dashboards
Create a Data App for embedding
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
/>

<dbn-dashboard 
  token={token}
  dashboard-id="dashboard-id"
  enable-download-csv
  enable-download-all-metrics
/>

const theme = {
  general: {
    primaryColor: '#FF6B6B',
    backgroundColor: '#F8F9FA',
    fontFamily: 'Inter'
  },
  chart: {
    colors: ['#FF6B6B', '#4ECDC4', '#45B7D1']
  }
};

<dbn-dashboard 
  token={token}
  dashboard-id="dashboard-id"
  theme={JSON.stringify(theme)}
/>

// Define global handler
window.handleDashboardEvent = (event) => {
  console.log('Dashboard event:', event);
};

<dbn-dashboard 
  token={token}
  dashboard-id="dashboard-id"
  handle-server-event="handleDashboardEvent"
/>

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

Dashboard not rendering

Check:

Plugin is imported before component renders
Token is valid and not expired
Dashboard ID is correct
No console errors

Token expired error

Solution: Generate a fresh token from your backend. Guest tokens can be set to expire after a certain time.

CORS errors

Fix: Ensure your domain is whitelisted in the Data App settings. Or generate tokens from your backend instead of frontend.

Styling issues

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

​What You’ll Build

​Prerequisites

​Step 1: Install the Package

​Step 2: Import the Plugin

​Step 3: Run and View

​Understanding What You Built

​The Component

​The Token

​The Dashboard ID

​Next: Make It Production-Ready

​1. Create Your Own Dashboard

Complete Setup Guide

​2. Generate Tokens from Your Backend

​Backend Example (Node.js)

​Frontend Example (React)

Guest Token API

​3. Customize the Dashboard

Component Options

​Embed a Single Metric

​Common Customizations

​Framework-Specific Guides

React

Next.js

Vue

Angular

Svelte

Vanilla JS

​Troubleshooting

Troubleshooting Guide

​What’s Next?

Complete Setup

Security & Auth

Customization

API Reference

​Need Help?

Interactive Playground

Community & Support

What You’ll Build

Prerequisites

Step 1: Install the Package

Step 2: Import the Plugin

Step 3: Run and View

Understanding What You Built

The Component

The Token

The Dashboard ID

Next: Make It Production-Ready

1. Create Your Own Dashboard

2. Generate Tokens from Your Backend

Backend Example (Node.js)

Frontend Example (React)

3. Customize the Dashboard

Embed a Single Metric

Common Customizations

Framework-Specific Guides

Troubleshooting

What’s Next?

Need Help?