嵌入式分析 SDK - 示例应用程序快速入门

本指南通过 示例 React 应用程序 设置嵌入式分析 SDK，您也可以使用自己的应用程序。

先决条件

• Node.js 20.x LTS 或更高版本（用于示例应用程序）。
• Metabase 版本 v1.52 或更高.
• Metabase 专业版或企业版许可证（如果您没有许可证，请查看此 快速入门，该入门不包含付费 JWT SSO 设置）
• （可选）：Docker

两种使用 Metabase 设置示例应用程序的方法

• 使用 Docker 快速设置（包含一个示例 Metabase）
• 逐步设置（使用您自己的 Metabase，或启动一个新的）

使用 Docker 快速设置

此快速设置将运行一个 Docker 容器，其中包含示例应用程序和示例 Metabase。

1. 将 .env.docker.example 复制到 .env.docker。
2. 在 .env.docker 文件中，将 <your_enterprise_token> 替换为您的高级嵌入令牌。
3. 在顶层目录中，运行

   yarn start
   

此脚本将

• 拉取 Metabase Docker 镜像并在容器中运行。
• 在 Metabase 中设置 JWT SSO。
• 构建并运行包含嵌入式交互式问题的示例应用程序。

应用程序将在 http://localhost:4400 启动。

就这样！您应该已经 启动并运行 了。

如果您想登录此命令设置的示例 Metabase，请访问 http://localhost:4300。您可以使用 Rene Descartes 的电子邮件和密码登录

• 电子邮件：rene@example.com
• 密码：foobarbaz

逐步设置

我们将在 Metabase 中进行一些设置，然后是示例应用程序。您也可以使用自己的 Metabase，在这种情况下，您可以跳过安装步骤。

以下是您将要执行操作的快速概述

设置 Metabase 以进行嵌入

1. 安装 Metabase 企业版（如果您尚未安装）
2. 激活您的许可证
3. 启用嵌入
4. 使用 JWT 启用 SSO

启动示例应用程序

1. 获取示例应用程序.
2. 设置应用程序环境.
3. 运行应用程序服务器 以处理 JWT 身份验证并提供嵌入式 Metabase 组件。
4. 运行客户端应用程序，其中将包含使用 SDK 构建的 Metabase 组件。

然后调整样式。

开始吧。

安装 Metabase 企业版

您可以通过 免费试用 在云计划上运行 Metabase 专业版。

或者在本地运行。这是一个 Docker 一行命令

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

您也可以 下载 JAR，然后像这样运行它

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

默认情况下，Metabase 将在 http://localhost:3000 运行。

如果您遇到困难，请查看我们的安装文档。

激活您的许可证

要在自托管时使用 JWT 启用 SSO，您需要激活您的许可证。Metabase 云上的专业版计划会为您处理此问题。

在 Metabase 中启用嵌入

从任何 Metabase 页面，单击右上角的齿轮图标，然后选择管理设置 > 设置 > 嵌入。

打开

• 嵌入式分析 SDK
• 静态嵌入

否则，这一切都将毫无意义。

使用 JWT 启用 SSO

我们还需要更新 Metabase 中的 JWT 提供程序 URI。默认情况下，此 URI 是 SDK 将重定向登录请求的位置。

从任何 Metabase 页面，单击右上角的齿轮图标，然后选择管理设置 > 设置 > 身份验证。

在标有 JWT 的卡片上，单击设置按钮。

JWT 身份提供程序 URI

在 JWT IDENTITY PROVIDER URI 字段中，粘贴

localhost:9090/sso/metabase

或将您的云 URL 替换 localhost。

JWT 签名密钥使用的字符串

单击生成密钥按钮。

复制密钥并将其粘贴到您的 .env 文件中，作为环境变量 METABASE_JWT_SHARED_SECRET 的值。

应用程序服务器将使用此密钥对令牌进行签名，以便 Metabase 知道应用程序的内容请求已获得授权。

保存并启用 JWT

务必点击保存并启用按钮，否则一切都将无效。

设置示例应用程序

克隆 Metabase Node JS React SDK 嵌入式示例应用程序。

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

检出与您的 Metabase 版本对应的分支

检出 metabase-nodejs-react-sdk-embedding-sample 仓库中与您的 Metabase 版本对应的分支。

例如，如果您运行的是 Metabase 1.53，请确保示例应用程序仓库在 53-stable 分支上。您可以通过单击 Metabase UI 右上角的齿轮图标并选择关于 Metabase 来找到您的 Metabase 版本。

要切换到另一个分支，请运行 git checkout <branch-name>，例如

git checkout 52-stable

设置应用程序环境

在示例应用程序的主目录中，将 .env.example 模板复制到 .env。

cp .env.example .env

在 .env 中，确保 VITE_METABASE_INSTANCE_URL 和 METABASE_INSTANCE_URL 指向您的 Metabase 实例 URL，例如 http://localhost:3000。

您的 .env 将看起来像这样

# FRONTEND
CLIENT_PORT=3100
VITE_METABASE_INSTANCE_URL="http://localhost:3000"

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

设置应用程序服务器

切换到 server 目录

cd server

安装包

npm install

启动服务器

npm start

设置客户端应用程序

在另一个终端中，切换到 client 目录

cd client

安装依赖项

npm install

此命令将安装 Metabase 嵌入式分析 SDK，以及应用程序的其他依赖项。

您也可以安装 不同版本的 SDK。只需确保 SDK 的主要版本与您正在使用的 Metabase 的主要版本匹配。

启动客户端应用程序

npm start

您的浏览器应该会自动打开应用程序。默认情况下，应用程序在 http://localhost:3100 运行。

至此，您应该已启动并运行

在您的应用程序中，您将看到一个嵌入的 InteractiveQuestion 组件。

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

后续步骤

要设置组件样式，请尝试在 client/src/App.jsx 中的客户端应用程序中更改一些 theme 选项。有关主题的更多信息，请查看外观。