> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usedatabrain.com/llms.txt
> Use this file to discover all available pages before exploring further.
# 5-Minute Embedding Tutorial
> Get your first DataBrain dashboard embedded in 5 minutes
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
```bash npm theme={"dark"}
npm install @databrainhq/plugin
```
```bash yarn theme={"dark"}
yarn add @databrainhq/plugin
```
```bash pnpm theme={"dark"}
pnpm add @databrainhq/plugin
```
## Step 2: Import the Plugin
Add this import to your component or main file:
```javascript React theme={"dark"}
import '@databrainhq/plugin/web';
function Dashboard() {
return (
);
}
export default Dashboard;
```
```javascript Vue theme={"dark"}
```
```javascript Vanilla JS theme={"dark"}
import '@databrainhq/plugin/web';
// In your HTML
document.body.innerHTML = `
`;
```
```html HTML theme={"dark"}
```
## Step 3: Run and View
Start your development server and you should see the sample dashboard! 🎉
```bash theme={"dark"}
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
```html theme={"dark"}
```
### 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](https://app.usedatabrain.com/users/sign-up)
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)
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)
```javascript theme={"dark"}
// 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)
```javascript theme={"dark"}
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 Loading...
;
return (
);
}
```
Complete token generation API docs
### 3. Customize the Dashboard
Add options to customize appearance and behavior:
```html theme={"dark"}
```
Explore all customization options
## Embed a Single Metric
You can also embed individual metrics instead of full dashboards:
```html theme={"dark"}
```
## Common Customizations
```html theme={"dark"}
```
```html theme={"dark"}
```
```javascript theme={"dark"}
const theme = {
general: {
primaryColor: '#FF6B6B',
backgroundColor: '#F8F9FA',
fontFamily: 'Inter'
},
chart: {
colors: ['#FF6B6B', '#4ECDC4', '#45B7D1']
}
};
```
```javascript theme={"dark"}
// Define global handler
window.handleDashboardEvent = (event) => {
console.log('Dashboard event:', event);
};
```
## Framework-Specific Guides
Get detailed integration guides for your framework:
React integration guide
Next.js with SSR support
Vue 3 integration
Angular setup guide
Svelte integration
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
Complete troubleshooting reference
## What's Next?
You've successfully embedded a DataBrain dashboard! Here's what to explore next:
Production-ready setup guide
Multi-tenancy and access control
Advanced customization options
Complete API documentation
## Need Help?
Experiment with live examples
Get help from our team