Embedded analytics SDK - quickstart

This guide walks you through how to set up the Embedded analytics SDK in your application with your Metabase using API keys.

This setup:

• Is only for evaluation (so you can see how the SDK works).
• Only works on localhost when developing your app (though your Metabase doesn’t need to be running locally).
• Works with both the Enterprise and Open Source editions of Metabase, both self-hosted and on Metabase Cloud.

If you want to use the SDK in production, however, you’ll also need to set up JWT SSO authentication, which requires a Pro or Enterprise plan. To enable JWT SSO when you’re self-hosting Metabase, you’ll need to run the Enterprise Edition Docker image or JAR, and activate your license.

Prerequisites

• Metabase version 52 or higher (OSS or EE). See Installing Metabase.
• Make sure your React version is compatible. (You could also use the sample React app.)

If you don’t have a Metabase up and running, check out the Quickstart CLI.

If you don’t want to use your own application code, check out our quickstart with a sample app.

Overview

To embed a dashboard in your app using the SDK, you’ll need to:

1. Enable the SDK in Metabase
2. Create an API key in Metabase
3. Install the SDK in your app
4. Embed SDK components in your app
5. View your embedded Metabase dashboard

1. Enable the SDK in Metabase

In Metabase, click on the gear icon in the upper right and navigate to Admin Settings > Embedding > Modular and enable the SDK for React.

2. Create an API key in Metabase

Still in the Admin console, go to Settings > Authentication and click on the API keys tab. Create a new API key.

• Key name: “Embedded analytics SDK” (just to make the key easy to identify).
• Group: select “Admin” (since this is only for local testing).

3. Install the SDK in your app

When installing the npm package, it’s critical to use the npm dist-tag that corresponds to the major version of your Metabase. For example, if your Metabase is version 1.56.x, you’d run 56-stable. See SDK versioning.

Via npm:

npm install @metabase/embedding-sdk-react@53-stable

Via Yarn:

yarn add @metabase/embedding-sdk-react@53-stable

4. Embed SDK components in your app

In your app, import the SDK components, like so:

import {
  InteractiveDashboard,
  MetabaseProvider,
  defineMetabaseAuthConfig,
} from "@metabase/embedding-sdk-react";

/**
 * This creates an auth config to pass to the `MetabaseProvider` component.
 * You'll need to replace the `metabaseInstanceUrl` and the `apiKey` values.
 */
const authConfig = defineMetabaseAuthConfig({
  metabaseInstanceUrl: "https://metabase.example.com",
  apiKey: "YOUR_API_KEY",
});

/**
 * Now embed your first dashboard. In this case, we're embedding the dashboard with ID 1.
 * On new Metabases, ID 1 will be the example dashboard, but feel free to use a different dashboard ID.
 */
export default function App() {
  return (
    <MetabaseProvider authConfig={authConfig}>
      <InteractiveDashboard dashboardId={1} />
    </MetabaseProvider>
  );
}

5. View your embedded Metabase dashboard

Run your app and visit the page with the embedded dashboard.

Next steps

• Explore theming to change the look and feel.
• Continue by setting up JWT SSO in Metabase and your app to sign people in, manage permissions, and deploy your app in production.