Embedded analytics SDK quickstart guide
⚠️ This feature is in beta. Feel free to play around with it, but be aware that things might change (and may not work as expected).
Embedded analytics SDK is only available on Pro and Enterprise plans (both self-hosted and on Metabase Cloud).
This guide sets up the embedded analytics SDK with the sample React app, but you can follow along with your own application.
Prerequisites
- Node.js 18.x LTS or higher (for the sample application).
Overview of the quickstart
We’re going to do some setup in Metabase, and in the sample application.
Set up Metabase for embedding
- Set up Metabase Enterprise Edition (if you haven’t already)
- Enable embedding
- Enable SSO with JWT
Start up the sample application
- Get the sample application.
- Set up the application environment.
- Run the app server to handle authentication with JWT and server the embedded Metabase components.
- Run the client application that will contain Metabase components built with the SDK.
And then fiddle around with styling.
Let’s go.
Set up Metabase for embedding
- Run Metabase Pro on a Cloud plan (with a free trial)
- Run Metabase Enterprise Edition locally. This sample app is compatible with Metabase version v1.50 or higher. When running locally, you’ll need to activate your license to enable SSO with JWT.
You can also use your existing Metabase, if you prefer.
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
.
You’re .env
will look something like:
# FRONTEND
PORT=3100
REACT_APP_METABASE_INSTANCE_URL="http://localhost:3000"
REACT_APP_JWT_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.
Read docs for other versions of Metabase.