Embedded analytics SDK - quickstart with sample app
⚠️ 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). You can, however, play around with the SDK on your local machine without a license by using API keys to authenticate your embeds.
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
- Install Metabase Enterprise Edition (if you haven’t already)
- Activate your license
- 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.
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 -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.
Read docs for other versions of Metabase.