Embedding Dashboards

Business

Integrate MongoDash dashboards into your applications, websites, and internal tools through flexible embedding options.

Overview

Dashboard embedding lets you display live MongoDB visualizations in external applications while maintaining security through authentication and access controls.

Quick Start

Basic Embed

Get started with iframe embedding:

Example Embed Code

<iframe
  src="https://app.mongodash.com/embed/d/abc123xyz?theme=light"
  width="100%"
  height="600"
  frameborder="0"
  allowtransparency="true"
></iframe>

Embed Methods

Public Embeds

No authentication required:

• Enable public access on dashboard
• Anyone with embed code can view
• No login or credentials needed
• Best for external websites and marketing

Use Cases:

• Public status pages
• Marketing dashboards
• Open data visualizations
• Customer-facing analytics

Authenticated Embeds

Require user authentication:

• Users must be logged into MongoDash
• Respects workspace permissions
• Secure for internal applications
• Maintains audit trail

Use Cases:

• Internal admin panels
• Team collaboration tools
• Customer portals with login
• Employee dashboards

SSO-Protected Embeds

Enterprise

Integrate with your SSO provider:

• Seamless authentication through your IdP
• No separate MongoDash login needed
• Enforces organization security policies
• Full SAML/OAuth support

Use Cases:

• Enterprise applications
• Corporate intranets
• Secure customer portals
• Compliance-required environments

Embed Configuration

URL Parameters

Customize embed behavior with URL parameters:

https://app.mongodash.com/embed/d/abc123xyz?
  theme=light&
  hide_header=true&
  hide_filters=false&
  auto_refresh=1m

Available Parameters

Visual Options:

• theme - light, dark, or auto
• hide_header - true or false (removes dashboard title)
• hide_filters - true or false (removes filter controls)
• hide_refresh - true or false (removes refresh button)

Behavior Options:

• auto_refresh - Refresh interval (30s, 1m, 5m, etc.)
• timezone - Force specific timezone (e.g., America/New_York)
• locale - Display locale (e.g., en-US, fr-FR)

Security Options:

• api_key - Authenticate with API key
• jwt_token - Authenticate with JWT token
• allowed_origin - Restrict embedding to specific domains

Responsive Embeds

Fixed Dimensions

Set specific width and height:

<iframe
  src="https://app.mongodash.com/embed/d/abc123xyz"
  width="1200"
  height="800"
  frameborder="0"
></iframe>

Responsive Container

Embed that adapts to container size:

<div style="position: relative; padding-bottom: 56.25%; height: 0; overflow: hidden;">
  <iframe
    src="https://app.mongodash.com/embed/d/abc123xyz"
    style="position: absolute; top: 0; left: 0; width: 100%; height: 100%;"
    frameborder="0"
  ></iframe>
</div>

This creates a 16:9 aspect ratio that scales responsively.

Mobile Optimization

Optimize embeds for mobile:

<iframe
  src="https://app.mongodash.com/embed/d/abc123xyz?mobile=true"
  width="100%"
  height="100vh"
  frameborder="0"
></iframe>

Mobile mode:

• Stacks widgets vertically
• Increases touch target sizes
• Simplifies interactions
• Reduces data usage

Authentication Methods

API Key Authentication

Authenticate embeds with workspace API key:

URL Parameter:

<iframe src="https://app.mongodash.com/embed/d/abc123xyz?api_key=YOUR_API_KEY"></iframe>

HTTP Header (via proxy):

headers: {
  'Authorization': 'Bearer YOUR_API_KEY'
}

JWT Token Authentication

Enterprise

Use signed JWT tokens for secure embedding:

Backend Token Generation (Node.js):

const jwt = require('jsonwebtoken');
 
const token = jwt.sign(
  {
    email: 'user@company.com',
    workspace: 'your-workspace-id',
    dashboardId: 'abc123xyz',
    exp: Math.floor(Date.now() / 1000) + (60 * 60) // 1 hour
  },
  process.env.MONGODASH_EMBED_SECRET
);

Embed with Token:

<iframe src="https://app.mongodash.com/embed/d/abc123xyz?jwt=${token}"></iframe>

Session-Based Authentication

Use existing user session:

• User logs into your application
• Your backend validates session
• Redirect to MongoDash with session token
• MongoDash validates and shows dashboard

Requires custom integration setup.

Security Configuration

Domain Whitelisting

Restrict which domains can embed dashboards:

Dashboards reject embed attempts from unlisted domains.

Content Security Policy

Configure CSP headers:

<meta http-equiv="Content-Security-Policy"
  content="frame-src https://app.mongodash.com;">

Add MongoDash to your CSP frame-src directive.

X-Frame-Options

MongoDash sets appropriate X-Frame-Options:

• ALLOW-FROM - Specified domains for authenticated embeds
• ALLOWALL - Public embeds with domain whitelist
• DENY - Blocks embedding if not configured

Customization Options

Theming

Match your application's design:

Light/Dark Themes:

<iframe src="https://app.mongodash.com/embed/d/abc123xyz?theme=dark"></iframe>

Custom CSS (Enterprise):

Enterprise

Apply custom stylesheets:

<iframe src="https://app.mongodash.com/embed/d/abc123xyz?css_url=https://yoursite.com/custom.css"></iframe>

Define CSS overrides:

/* custom.css */
.dashboard-container {
  --primary-color: #007bff;
  --background-color: #f8f9fa;
  --text-color: #212529;
}
 
.widget-header {
  font-family: 'Your Brand Font', sans-serif;
}

White Labeling

Enterprise

Remove MongoDash branding:

• Hide "Powered by MongoDash" footer
• Custom loading spinner
• Custom error messages
• Your brand colors and logo

Configure in Workspace Settings → White Label.

Interactivity

Enabled by Default

Embedded dashboards support:

• Widget interactions (hover, click)
• Filter controls
• Date range selection
• Drill-down navigation
• Export functions

Disabling Interactivity

Create read-only embeds:

<iframe
  src="https://app.mongodash.com/embed/d/abc123xyz?interactive=false"
  style="pointer-events: none;"
></iframe>

Prevents all user interactions, pure display mode.

Deep Linking

Link to specific dashboard states:

https://app.mongodash.com/embed/d/abc123xyz?
  filter_status=active&
  date_range=last_7_days&
  widget_focus=revenue_chart

URL parameters set initial filter and view state.

Communication with Embeds

PostMessage API

Business

Two-way communication between parent and embed:

Parent sends message to embed:

const iframe = document.getElementById('dashboard-embed');
iframe.contentWindow.postMessage({
  type: 'setFilter',
  data: {
    field: 'status',
    value: 'active'
  }
}, 'https://app.mongodash.com');

Listen for embed events:

window.addEventListener('message', (event) => {
  if (event.origin !== 'https://app.mongodash.com') return;
 
  if (event.data.type === 'widgetClicked') {
    console.log('Widget clicked:', event.data.widgetId);
    // Handle in your app
  }
});

Supported Events

From Parent to Embed:

• setFilter - Update dashboard filters
• refresh - Trigger data refresh
• setDateRange - Change date range
• exportData - Trigger export

From Embed to Parent:

• loaded - Dashboard finished loading
• widgetClicked - User clicked widget
• filterChanged - Filter values updated
• error - Error occurred

Performance Optimization

Lazy Loading

Delay embed loading until visible:

const observer = new IntersectionObserver((entries) => {
  entries.forEach(entry => {
    if (entry.isIntersecting) {
      const iframe = entry.target;
      iframe.src = iframe.dataset.src;
      observer.unobserve(iframe);
    }
  });
});
 
const iframe = document.querySelector('#dashboard-embed');
iframe.dataset.src = 'https://app.mongodash.com/embed/d/abc123xyz';
observer.observe(iframe);

Loads dashboard only when scrolled into view.

Preload Hints

Speed up embed loading:

<link rel="preconnect" href="https://app.mongodash.com">
<link rel="dns-prefetch" href="https://app.mongodash.com">

Caching

Enable aggressive caching:

<iframe src="https://app.mongodash.com/embed/d/abc123xyz?cache=1h"></iframe>

Cache duration options: 5m, 15m, 1h, 24h

Multiple Embeds

Same Page Embeds

Embed multiple dashboards:

<div class="dashboard-grid">
  <iframe src="https://app.mongodash.com/embed/d/dashboard1"></iframe>
  <iframe src="https://app.mongodash.com/embed/d/dashboard2"></iframe>
  <iframe src="https://app.mongodash.com/embed/d/dashboard3"></iframe>
</div>

Performance Considerations:

• Each embed creates separate connection
• Limit to 3-4 embeds per page
• Use lazy loading for below-fold embeds
• Consider combined dashboard instead

Tabbed Embeds

Load embeds only when tab selected:

function showDashboard(dashboardId) {
  const iframe = document.getElementById('dashboard-iframe');
  iframe.src = `https://app.mongodash.com/embed/d/${dashboardId}`;
}

Reduces initial page load and resource usage.

Troubleshooting

Embed Not Displaying

Common causes and solutions:

Check Domain Whitelist:

• Verify your domain in allowed domains list
• Include both www and non-www versions
• Check for typos in domain name

Check Browser Console:

• Look for CSP errors
• Verify CORS headers
• Check for JavaScript errors

Test Authentication:

• Verify API key is valid
• Check JWT signature
• Confirm user has dashboard access

Authentication Errors

If users see "Unauthorized":

1. Verify API key or JWT token
2. Check token expiration time
3. Confirm user workspace membership
4. Review dashboard permissions
5. Check IP whitelist if configured

Performance Issues

If embeds load slowly:

• Reduce number of widgets on dashboard
• Increase refresh intervals
• Enable query caching
• Use CDN for static assets
• Optimize MongoDB indexes
• Consider read replicas for dashboard queries

Display Issues

If layout looks broken:

• Check iframe dimensions match dashboard size
• Verify theme parameter matches your site
• Test in different browsers
• Check browser zoom level
• Review custom CSS conflicts

Best Practices

Security

Protect embedded dashboards:

• Always use HTTPS for embed URLs
• Enable domain whitelisting
• Rotate API keys regularly
• Use short-lived JWT tokens
• Monitor embed access logs
• Implement rate limiting

User Experience

Create seamless embeds:

• Match theme to your application
• Provide loading indicators
• Handle errors gracefully
• Show refresh timestamps
• Enable interactive features
• Test across devices and browsers

Performance

Optimize embed performance:

• Limit widgets per dashboard
• Use appropriate cache durations
• Lazy load below-fold embeds
• Monitor query execution times
• Use read replicas for heavy usage
• Implement connection pooling

Advanced Integration

React Component

Wrap embed in React component:

import React, { useEffect, useRef } from 'react';
 
function MongoDashEmbed({ dashboardId, options = {} }) {
  const iframeRef = useRef(null);
 
  const url = new URL(`https://app.mongodash.com/embed/d/${dashboardId}`);
  Object.entries(options).forEach(([key, value]) => {
    url.searchParams.set(key, value);
  });
 
  useEffect(() => {
    // Setup postMessage listeners
    const handleMessage = (event) => {
      if (event.origin !== 'https://app.mongodash.com') return;
      // Handle events
    };
 
    window.addEventListener('message', handleMessage);
    return () => window.removeEventListener('message', handleMessage);
  }, []);
 
  return (
    <iframe
      ref={iframeRef}
      src={url.toString()}
      width="100%"
      height="600"
      frameBorder="0"
    />
  );
}

Vue Component

Similar pattern for Vue:

<template>
  <iframe
    :src="embedUrl"
    width="100%"
    height="600"
    frameborder="0"
  />
</template>
 
<script>
export default {
  props: ['dashboardId', 'options'],
  computed: {
    embedUrl() {
      const url = new URL(`https://app.mongodash.com/embed/d/${this.dashboardId}`);
      Object.entries(this.options || {}).forEach(([key, value]) => {
        url.searchParams.set(key, value);
      });
      return url.toString();
    }
  }
}
</script>

What's Next?

• Sharing Dashboards
• API Integration
• User Permissions