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.

Prerequisites

• Node.js 18.x LTS or higher (for the sample application).
• Metabase version v1.51 or higher.

Overview of the quickstart

We’re going to do some setup in Metabase, and in the sample application.

Set up Metabase for embedding

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

Start up the sample application

1. Get the sample application.
2. Set up the application environment.
3. Run the app server to handle authentication with JWT and server 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.

Install Metabase Enterprise Edition

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

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

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

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

If you get stuck, check out our installation docs.

Activate your license

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.

Enable embedding in Metabase

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.

Enable SSO with JWT

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.

JWT Identity provider URI

In JWT IDENTITY PROVIDER URI field, paste

localhost:9090/sso/metabase

Or substitute your Cloud URL for /localhost.

String used by the JWT signing key

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.

Save and enable JWT

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

Set up the sample application

Clone the Metabase Node JS React SDK embedding sample app.

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

Set up the application environment

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

cp .env.example .env

In .env, make sure REACT_APP_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
PORT=3100
REACT_APP_METABASE_INSTANCE_URL="http://localhost:3000"
REACT_APP_AUTH_PROVIDER_URI="http://localhost:9090/sso/metabase"

# BACKEND
BACKEND_PORT=9090
METABASE_INSTANCE_URL="http://localhost:3000"
METABASE_JWT_SHARED_SECRET="TODO"

Set up the application server

Change into the server directory:

cd server

Install packages:

npm install

Start the server:

npm start

Set up the client application

Change into the client directory.

Install packages:

npm install

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

Start the client

In a different terminal, change into the client directory:

cd client

Install dependencies:

npm install

Start the client app:

npm start

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

At this point, you should be up and running

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

<MetabaseProvider config={config} theme={theme}>
  <InteractiveQuestion questionId={questionId} />
</MetabaseProvider>

Try changing some of the theme options in the client app to style the components.