Embedding 5X BI Dashboards

Overview

This guide provides detailed instructions for embedding 5X Business Intelligence (5X BI) dashboards into your applications. 5X BI, powered by Apache Superset, enables you to seamlessly integrate powerful data visualization capabilities into your applications using our secure embedding framework.

Prerequisites

Required Access

Active paid subscription to 5X platform
BI module enabled for your account
API key from the 5X team

Technical Requirements

Backend server to handle API calls
Frontend web application
Secure HTTPS environment
Modern web browser

Quick Start

Follow these steps to quickly embed a dashboard:
Enable embedding for your dashboard in 5X BI
Implement the backend endpoint for guest token generation
Add the embedding code to your frontend
Test the implementation

Detailed Implementation Guide

1️⃣ Dashboard Configuration

Enable Embedding

Navigate to your dashboard in 5X BI
Click "..." (three dots) in the top right
Select "Embed Dashboard"
Configure allowed domains
Enable embedding toggle
Save changes

Domain Configuration

Add specific domains where embedding is allowed
Format: https://app.yourcompany.com
Wildcard supported: *.yourcompany.com
Always use HTTPS URLs

2️⃣ Backend Implementation

The BI embed capability used guest tokens to authenticate into the BI instance. A server side flow for fetching the guest token from 5X needs to be implemented. From your server, a call needs to be made to the POST API end point to fetch the guest token that can be used for authenticating the dashboard embed.
The API Key needs to be passed in the ‘Authorization’ Header.
Request Body:
{
// Pass the list of dashboard ids for the dashboards that needs to be embedded.
"dashboardIds": [
"1",
"2",
"3"
]
}
Response Body:
{
"status": "SUCCESS",
"message": "Guest token fetched successfully.",
"data": {
"guestToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyIjp7Imxhc3RfbmFtZSI6IkFkbWluIiwiZmlyc3RfbmFtZSI6IlBsYXRmb3JtIiwidXNlcm5hbWUiOiJhZG1pbiJ9LCJyZXNvdXJjZXMiOlt7InR5cGUiOiJkYXNoYm9hcmQiLCJpZCI6IjEifSx7InR5cGUiOiJkYXNoYm9hcmQiLCJpZCI6IjIifSx7InR5cGUiOiJkYXNoYm9hcmQiLCJpZCI6IjMifV0sInJsc19ydWxlcyI6W10sImlhdCI6MTcyOTUzOTQzNC4zODA2NzU2LCJleHAiOjE3Mjk1Mzk3MzQuMzgwNjc1NiwiYXVkIjoiaHR0cDovLzAuMC4wLjA6ODA4MC8iLCJ0eXBlIjoiZ3Vlc3QifQ.VcpXMS2LJe4IhTlK-NMnWBA1CiD0QRFK1bJcgHFm3Ac",
"host": "https://myhsiw.superset.platform.5x.co"
}
}

API Endpoint Setup Sample(Node.js/Express Example)

Create an endpoint in your app’s backend server to generate guest tokens:
// Node.js/Express Example
const express = require('express');
const app = express();

app.post('/api/guest-token', async (req, res) => {
try {
const response = await fetch('https://api-v1.5x.co/business-intelligence/v1/guest-token', {
method: 'POST',
headers: {
'Authorization': `${process.env.FIVEX_API_KEY}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({
dashboardIds: req.body.dashboardIds
})
});

const data = await response.json();
res.json({
status: 'success',
guestToken: data.data.guestToken
});
} catch (error) {
res.status(500).json({
status: 'error',
message: 'Failed to generate guest token'
});
}
});

Security Best Practices

Store API key securely
Use environment variables
Never commit API keys to source control
Implement key rotation mechanism
Implement rate limiting
Add request validation
Use HTTPS only
Set up proper CORS policies

3️⃣ Frontend Implementation

Basic Setup

Create your HTML structure:
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>5X BI Dashboard</title>
<style>
.dashboard-container {
width: 100%;
height: 800px;
border: 1px solid #ccc;
border-radius: 4px;
margin: 20px 0;
}
.error-message {
color: #721c24;
background-color: #f8d7da;
padding: 12px;
border-radius: 4px;
display: none;
}
.loading-indicator {
text-align: center;
padding: 20px;
display: none;
}
</style>
</head>
<body>
<div class="error-message" id="errorMessage"></div>
<div class="loading-indicator" id="loadingIndicator">Loading dashboard...</div>
<div class="dashboard-container" id="dashboardContainer"></div>

<script src="https://unpkg.com/@superset-ui/embedded-sdk"></script>
<script src="dashboard.js"></script>
</body>
</html>

Implementation Code

Create dashboard.js:
// Configuration
const config = {
dashboardIds: ['your-dashboard-id'], // Replace with your dashboard ID
apiEndpoint: '/api/guest-token',
supersetDomain: 'https://yourcompany.5x.co' // Your 5X BI domain
};

// Token Management
class TokenManager {
constructor() {
this.token = null;
this.tokenExpiry = null;
}

async getToken() {
if (!this.token || Date.now() > (this.tokenExpiry - 30000)) {
await this.refreshToken();
}
return this.token;
}

async refreshToken() {
const response = await fetch(config.apiEndpoint, {
method: 'POST',
headers: {
'Content-Type': 'application/json'
},
body: JSON.stringify({
dashboardIds: config.dashboardIds
})
});

if (!response.ok) {
throw new Error('Failed to fetch guest token');
}

const data = await response.json();
this.token = data.guestToken;
this.tokenExpiry = Date.now() + (5 * 60 * 1000); // 5 minutes
}
}

// Dashboard Embedding
async function initializeDashboard() {
const tokenManager = new TokenManager();
const loadingIndicator = document.getElementById('loadingIndicator');
const errorMessage = document.getElementById('errorMessage');
const container = document.getElementById('dashboardContainer');

try {
loadingIndicator.style.display = 'block';
errorMessage.style.display = 'none';

const dashboard = await supersetEmbeddedSdk.embedDashboard({
id: config.dashboardIds[0],
supersetDomain: config.supersetDomain,
mountPoint: container,
fetchGuestToken: () => tokenManager.getToken(),
dashboardUiConfig: {
hideTitle: false,
filters: {
expanded: true
}
}
});

dashboard.on('render', () => {
loadingIndicator.style.display = 'none';
});

dashboard.on('error', (error) => {
errorMessage.textContent = `Error: ${error.message}`;
errorMessage.style.display = 'block';
loadingIndicator.style.display = 'none';
});

} catch (error) {
errorMessage.textContent = `Failed to load dashboard: ${error.message}`;
errorMessage.style.display = 'block';
loadingIndicator.style.display = 'none';
}
}

document.addEventListener('DOMContentLoaded', initializeDashboard);

Token Management

Guest Token Lifecycle

Tokens expire after 5 minutes
Request new token before expiration
Implement automatic refresh
Handle failed refresh attempts

Token Refresh Strategy

Check token expiration before use
Refresh if within 30 seconds of expiry
Queue requests during refresh
Handle refresh failures gracefully

Security Guidelines

API Key Protection

✅ Store in environment variables
✅ Use secrets management
❌ Never expose in client code
❌ Never commit to version control

Domain Security

Configure allowed domains precisely
Use exact matches when possible
Regularly audit domain settings
Always use HTTPS

Troubleshooting

Common Issues

Dashboard Not Loading

Check guest token validity
Verify domain configuration
Confirm dashboard ID
Check browser console errors

Authentication Errors

Verify API key format
Check domain allowlist
Confirm token refresh flow

Rendering Issues

Check container dimensions
Verify browser compatibility
Monitor network requests

Debug Steps

Check browser console
Verify network requests
Validate guest token
Confirm domain settings

Support

Need help? Contact us:
Email:
Live Support: Intercom (in 5X platform)
When reporting issues, include:
Dashboard ID
Error messages
Browser information
Network logs

FAQ

Q: How often do guest tokens expire? A: Guest tokens expire after 5 minutes. Implement automatic refresh before expiration.
Q: Can I embed multiple dashboards? A: Yes, provide multiple dashboard IDs when requesting guest tokens.
Q: Is there a size limit for embedded dashboards? A: No specific size limits, but consider performance for large dashboards.
Q: How do I handle mobile responsiveness? A: The container is responsive by default. Adjust container dimensions as needed.

Best Practices

Implement proper error handling
Use automatic token refresh
Monitor dashboard performance
Provide loading indicators
Handle network failures gracefully
Test across different browsers
Implement proper security measures
Want to print your doc?
This is not the way.
Try clicking the ⋯ next to your doc name or using a keyboard shortcut (
CtrlP
) instead.