Embedded analytics SDK - quickstart with sample app

This guide sets up the embedded analytics SDK with a sample React app, but you can follow along with your own application.

• Node.js 20.x LTS or higher (for the sample application).
• Metabase version v1.52 or higher.
• A Metabase Pro or Enterprise license (If you don’t have a license, check out this quickstart that lacks the paid JWT SSO setup)
• (Optional): Docker

• Quick setup with Docker (includes a sample Metabase)
• Walkthrough setup (bring your own Metabase, or spin up a new one)

This quick setup will run a Docker container with the sample app and a sample Metabase.

1. Copy .env.docker.example to .env.docker.
2. In the .env.docker file, replace <your_enterprise_token> with your premium embedding token.
3. In the top-level directory, run:

    yarn start
       
                   
   Copy
       
       
                   
   Copied
       

This script will:

• Pull a Metabase Docker image and run it in a container.
• Set up JWT SSO in Metabase.
• Build and run the sample application with an embedded interactive question.

The app will start on http://localhost:4400.

That’s it! You should be up and running.

If you want to log in to the sample Metabase this command set up, visit http://localhost:4300. You can log in with email and password as Rene Descartes:

• email: rene@example.com
• password: foobarbaz

We’re going to do some setup in Metabase, and then in the sample application. You can also bring your own Metabase, in which case you can skip the installation step.

Here’s a quick overview of what you’ll be doing:

1. Install Metabase Enterprise Edition (if you haven’t already)
2. Activate your license
3. Enable embedding
4. Enable SSO with JWT

1. Get the sample application.
2. Set up the application environment.
3. Run the app server to handle authentication with JWT and serve the embedded Metabase components.
4. Run the client application that will contain Metabase components built with the SDK.

And then fiddle around with styling.

Let’s go.

You can run Metabase Pro on a Cloud plan with a free trial.

Or run it locally. Here’s a docker one-liner:

docker run -d -p 3000:3000 --name metabase metabase/metabase-enterprise:latest
    
                
Copy
    
    
                
Copied
    

You can also download the JAR, and run it like so:

java --add-opens java.base/java.nio=ALL-UNNAMED -jar metabase.jar
    
                
Copy
    
    
                
Copied
    

By default, Metabase will run at http://localhost:3000.

If you get stuck, check out our installation docs.

To enable SSO with JWT when self-hosting, you’ll need to activate your license. Metabase Pro plans on Cloud take care of this for you.

From any Metabase page, click on the gear icon in the upper right and select Admin Settings > Settings > Embedding.

Turn on:

• Embedded analytics SDK
• Static embedding

Otherwise, this whole thing is hopeless.

From any Metabase page, click on the gear icon in the upper right and select Admin Settings > Settings > Authentication.

On the card that says JWT, click the Setup button.

In JWT IDENTITY PROVIDER URI field, paste

localhost:9090/sso/metabase
    
                
Copy
    
    
                
Copied
    

Or substitute your Cloud URL for localhost.

Click the Generate key button.

Copy the key and paste it in your .env file into the env var METABASE_JWT_SHARED_SECRET.

The application server will use this key to sign tokens so Metabase knows the application’s requests for content are authorized.

Be sure to hit the Save and enable button, or all is void.

Clone the Metabase Node JS React SDK embedding sample app.

git clone git@github.com:metabase/metabase-nodejs-react-sdk-embedding-sample.git
    
                
Copy
    
    
                
Copied
    

Check out the branch in the metabase-nodejs-react-sdk-embedding-sample repo that corresponds to your Metabase version.

E.g., if you’re running Metabase 1.53, make sure the sample app repo is on the 53-stable branch. You can find your Metabase version in the Metabase UI by clicking on the gears icon in the upper right and selecting About Metabase.

To switch to another branch, run git checkout <branch-name>, e.g.:

git checkout 52-stable
    
                
Copy
    
    
                
Copied
    

In the sample app’s main directory, copy the .env.example template to .env.

cp .env.example .env
    
                
Copy
    
    
                
Copied
    

In .env, make sure VITE_METABASE_INSTANCE_URL and METABASE_INSTANCE_URL point to your Metabase instance URL, e.g., http://localhost:3000.

Your .env will look something like:

# FRONTEND
CLIENT_PORT=3100
VITE_METABASE_INSTANCE_URL="http://localhost:3000"
VITE_AUTH_PROVIDER_URI="http://localhost:9090/sso/metabase"

# BACKEND
AUTH_PROVIDER_PORT=9090
METABASE_INSTANCE_URL="http://localhost:3000"
METABASE_JWT_SHARED_SECRET="TODO"
    
                
Copy
    
    
                
Copied
    

Change into the server directory:

cd server
    
                
Copy
    
    
                
Copied
    

Install packages:

npm install
    
                
Copy
    
    
                
Copied
    

Start the server:

npm start
    
                
Copy
    
    
                
Copied
    

In a different terminal, change into the client directory:

cd client
    
                
Copy
    
    
                
Copied
    

Install dependencies:

npm install
    
                
Copy
    
    
                
Copied
    

This command will install the Metabase embedded analytics SDK, in addition to the application’s other dependencies.

You can also install a different version of the SDK. Just make sure that the major version of the SDK matches the major version of the Metabase you’re using.

Start the client app:

npm start
    
                
Copy
    
    
                
Copied
    

Your browser should automatically open the app. By default, the app runs on http://localhost:3100.

In your app, you’ll see an embedded InteractiveQuestion component.

<MetabaseProvider authConfig={authConfig} theme={theme}>
  <InteractiveQuestion questionId={questionId} />
</MetabaseProvider>
    
                
Copy
    
    
                
Copied
    

To style the components, try changing some of the theme options in the client app at client/src/App.jsx. For more on theming, check out Appearance.