Skip to content

About

Reference applications for common web frameworks showing how to embed Metabase charts

Topics

Resources

Stars

171 stars

Watchers

51 watching

Forks

Repository files navigation

Metabase guest embeds: reference web apps

This repo contains example applications for common web frameworks that show how to embed Metabase dashboards in your application with guest embeds.

With a guest embed, your server signs a token, and your page passes the token to a Metabase component like <metabase-dashboard>. People who view the embed don't need a Metabase account.

If your customers need to explore data themselves, with drill-through, the query builder, or AI chat, check out modular embedding with SSO or full app embedding, and these resources:

If you're unsure which way to embed is best for you, check out our live demos and the embedding introduction.

About this repo

This README walks you through getting Metabase up and running, as well as a simple web app, to show you a live example of an embedded dashboard.

Here's a Metabase dashboard embedded in the Node app:

Metabase dashboard embedded in the Node application as a guest embed

The apps

Each app does the same thing in a different framework: it shows one dashboard as a guest embed, with a token that the app signs on the server. For comparison, each app's home page also shows a public embed.

App Where the embedding code is
Node index.js
Django user_stats/views.py
Rails app/controllers/analytics_controller.rb
Laravel app/Http/Controllers/AnalyticsController.php

If you're not sure which one to try, check out the Node app.

There are also minimal, single-file examples, without a login:

Guest embeds and the "Powered by Metabase" banner

Guest embeds are available on every Metabase plan. On the Open Source and Starter plans, guest embeds show a "Powered by Metabase" banner.

To remove the banner, upgrade to a Pro or Enterprise plan. On those plans, you can also customize the colors and fonts of your embeds and hide the download buttons. On the Open Source and Starter plans, you can pick a light or dark theme.

Prerequisites

Set up Metabase

We'll first need to set up a running instance of Metabase to serve the embedded dashboards. The metabase directory of this repo has an application database with the dashboards that the apps embed.

  1. Shut down Metabase if you already have it running on your machine.
  2. Download the JAR file for Metabase OSS. The application database was last saved with Metabase 65, so use that version or a later one.
  3. Open up a terminal and clone this repo to your machine.
  4. Move the metabase.jar file from your downloads to the static-embedding-reference-apps/metabase directory.
  5. cd into static-embedding-reference-apps/metabase.
  6. Run the JAR file:
    java -jar metabase.jar
    
  7. Run any example depending on the programming language you choose.

Check that embedding is enabled

Once you've got Metabase running (on port 3000 by default):

  1. Go to localhost:3000 in your browser.
  2. Log into Metabase.
  3. Click the grid icon in the upper right and select Embedding hub.
  4. Go to Security and check that Enable embedding is on. On Pro and Enterprise plans, the toggle is called Modular embedding.

What's in the demo Metabase

  • Customer overview (dashboard 3): the dashboard that the apps embed. It's published as a guest embed, and shows data from the Sample Database's Invoices and Analytic Events tables.
  • A Public Dashboard (dashboard 1) and Number of Orders (question 1): items with public links. The apps' home pages show both as public embeds, and the HTML example embeds the question.

To see how a guest embed is set up, open the Customer overview dashboard, click the Share icon, and select Embed.

Running the apps

To see an embedded Metabase dashboard in action, set up Metabase, and follow the instructions in the README for one of the apps.

Embedding charts or dashboards

There are different ways to embed Metabase charts or dashboards in web applications.

Public embeds

The public embedding method is to simply use the public URLs inside of an iframe, or really anywhere you can insert HTML. A public link only opens that one question or dashboard, so people can't use it to get to anything else in your Metabase. But public embeds don't involve any authentication, so anyone with the URL can view the data, and anyone can change the filters in the URL. Don't use public embeds to restrict data.

Guest embeds

With guest embeds, embedded questions and dashboards are signed using a secret key that your server shares with your Metabase. Metabase only loads the embed if the token is valid. This allows you to build dynamic dashboards with a parameter that can be locked down. You should sign the tokens on your server, which allows you to embed dashboards accessible to specific organizations, accounts, or users.

The web applications go into more detail about embedding, and provide examples. Start up the Node app and explore the app.

Static embeds (deprecated)

Static embedding puts the same signed token in an iframe URL, like /embed/dashboard/YOUR_JWT_TOKEN. Existing static embeds keep working, but use guest embeds for new work. The apps in this repo used static embedding before, and now use guest embeds.

Modular embedding with SSO, and full app embedding

On Pro and Enterprise plans, your customers' users can sign in to Metabase with SSO. Metabase then knows who's viewing, so permissions restrict the data, and you can offer drill-through, the query builder, and more. To keep each customer's data separate, see tenants. These kinds of embedding aren't covered in this repo.

Docs and articles

Run into trouble?

Check out the Metabase discussion forum and search for your issue. If you don't find any answers, please create an issue for this repository.

About

Reference applications for common web frameworks showing how to embed Metabase charts

Topics

Resources

Stars

171 stars

Watchers

51 watching

Forks

Releases

Packages

Used by

Contributors

Languages