嵌入式分析 JS

嵌入式分析 JS 允许您使用可自定义的组件，将 Metabase 实体（例如问题、仪表板，甚至查询生成器）嵌入到您自己的应用程序中。

仅需 30 分钟即可嵌入一个真实的仪表板。

加入我们下一次的嵌入式分析研讨会

嵌入式分析 JS 是一个基于 Metabase 的 嵌入式分析 React SDK 构建的 JavaScript 库。但它不需要使用 React 或进行完整的 SDK 嵌入设置。与嵌入整个 Metabase 应用到 iframe 中的 交互式嵌入 不同，嵌入式分析 JS 允许您从预定义组件的集合中进行选择，例如单个图表、带有可选钻取功能的仪表板或查询生成器，并自定义这些组件。

嵌入式分析 JS 使用 JWT 或 SAML 进行用户身份验证，并自动应用正确的权限。

当前您可以选择嵌入

• 一个仪表板
• 一个问题（图表）。您可以嵌入使用查询生成器创建的问题以及使用 SQL 创建的问题。
• 完整的图形化 查询生成器，让用户能够创建自己的图表和探索。
• 一个浏览器，用于浏览集合并打开仪表板或问题。
• AI 聊天界面.

快速入门

您也可以直接在 Metabase 中按照设置指南进行操作，路径为 管理员设置 > 嵌入 > 设置指南。我们在此记录这些步骤以供方便查阅。

1. 启用嵌入式分析 JS

1. 在 Metabase 中，转到 管理员设置 > 嵌入 > 模块化嵌入。
2. 切换 嵌入式分析 JS 为开启状态。
3. 在 跨域资源共享 (CORS) 下，添加您希望嵌入 Metabase 的网站的 URL（例如 https://*.example.com）。为了测试嵌入，您可以使用 localhost，它始终包含在 CORS 策略中。
4. 如果您在与 Metabase 域不同的域中嵌入 Metabase 组件（包括在本地测试应用但使用 Metabase Cloud 时），请转到 管理员设置 > 嵌入 > 安全性，并将 SameSite cookie 设置为 None。

2. 创建新的嵌入

1. 在 Metabase 中，转到 管理员 > 嵌入 > 模块化嵌入，然后点击 嵌入式分析 JS 旁边的 新建嵌入。

   如果您计划嵌入现有问题或仪表板，则可以直接转到该问题或仪表板，点击 分享 按钮，然后选择 嵌入式分析 JS。

2. 选择要嵌入的实体 *类型*

   • 仪表盘
   • 图表
   • 探索（这将嵌入 Metabase 查询生成器）
   • 浏览器
   • Metabot 问题（这将嵌入 AI 聊天）

3. 接下来，选择您要嵌入的实体。对于浏览器，选择用户应开始的集合。

选择好要嵌入的内容后，点击“下一步”来自定义您的嵌入。

3. 自定义您的嵌入

您看到的具体自定义选项将取决于您嵌入的实体类型。您将看到嵌入在所选选项下的实时预览。有关自定义选项的更多详细信息，请参阅 自定义嵌入。

您还可以选择所有嵌入使用的品牌、文本和背景颜色。要配置其他颜色（例如次要颜色、查询生成器颜色等）以及字体，您可以在嵌入代码片段中指定一个 主题。

在此交互式流程中选择的所有自定义选项都将反映在嵌入代码的参数值中，因此您以后可以通过编辑嵌入片段来调整它们。

完成嵌入自定义后，点击“下一步”。

4. 选择身份验证方法

您可以在“现有 Metabase 会话”和“单点登录 (SSO)”之间进行选择。

• 如果选择 现有 Metabase 会话，您将能够以当前登录 Metabase 的用户身份预览您的嵌入，并且仅限于您当前会话的同一浏览器。并非所有浏览器都支持 - 我们建议使用 Google Chrome。要测试其他上下文中的嵌入，您可以改用 API 密钥。对于生产使用，请使用 SSO。

• 如果您在 Metabase 实例中设置了 JWT，则可以选择 单点登录 (SSO)，请参阅 设置 SSO。

5. 将嵌入脚本添加到您的应用中

Metabase 将生成一个代码片段，您可以将其复制并粘贴到您的应用中，有关示例，请参阅 嵌入代码片段。稍后您可以修改此代码片段来指定其他外观选项或更改某些组件的行为。

将代码片段添加到您的应用中，然后刷新页面。

每个最终用户都应该拥有自己的 Metabase 账户

每个最终用户都必须拥有自己的 Metabase 账户。

让最终用户共享一个 Metabase 账户的问题在于，即使您通过嵌入式分析 JS 在客户端过滤数据，所有最终用户仍然可以访问会话令牌，他们可以使用该令牌直接通过 API 访问 Metabase，从而获取他们不应该看到的数据。

但是，如果每个最终用户都有自己的 Metabase 账户，您可以在 Metabase 中配置权限，每个人都只能访问他们应该访问的数据。

此外，我们认为共享账户属于不公平使用。公平使用嵌入式分析 JS 需要为嵌入式分析的每个最终用户提供自己的 Metabase 账户。

嵌入代码片段

使用嵌入式分析 JS 嵌入 Metabase 实体的代码片段应包含三个部分

1. 从您的 Metabase 实例加载嵌入式分析 JS 库。
2. 全局配置设置，将应用于页面上的所有嵌入，例如您的 Metabase 实例的 URL、外观主题等。请参阅 配置嵌入。
3. 用于嵌入 Metabase 实体的组件及其参数。请参阅 组件。

以下是一个脚本示例

<!-- Load embedding library -->
<!-- REPLACE WITH YOUR METABASE URL HERE -->
<script defer src="https://your-metabase-url/app/embed.js"></script>
<script>
  function defineMetabaseConfig(config) {
    window.metabaseConfig = config;
  }
</script>

<!-- Embedding configuration -->
<script>
  defineMetabaseConfig({
    instanceUrl: "https://your-metabase-url",
    theme: {
      colors: {
        background: "#ffffff",
      },
    },
  });
</script>

<!--Embedded entities -->
<metabase-question question-id="1"></metabase-question>

<metabase-dashboard dashboard-id="2" with-title="false"></metabase-dashboard>

注意加载 embed.js 库的脚本中的 defer 属性以及对您的 Metabase URL 的引用。

如果您在一个页面中嵌入了多个实体，则只需在全局范围内包含一次 <script> 标签即可。

您也可以在 Metabase 中通过 管理员 > 嵌入 > 设置指南 > 嵌入到您的代码中 交互式地生成嵌入式分析 JS 的代码片段。请参阅 快速入门。

自定义嵌入

您看到的具体自定义选项将取决于您嵌入的实体类型。

当您使用 管理员 > 嵌入 > 设置指南 > 嵌入到您的代码中 创建新嵌入时，您将在交互式创建流程中看到以下自定义选项。这些选项对应于 组件 中的参数。

• 允许用户钻取数据点：确定用户是否可以与图表（或仪表板上的图表）进行交互。交互性包括从汇总问题中 向下钻取 到单个记录、单击时过滤、缩放等。禁用嵌入式 *问题* 的钻取功能也会禁用用户添加过滤器和摘要的功能。

• 允许下载：确定用户是否可以下载问题结果并将仪表板保存为 PDF。

• 允许用户保存新问题。如果您嵌入了查询生成器但禁用了此选项，用户仍然可以进行自己的探索，只是无法保存它们。

• 参数：对于仪表板过滤器、SQL 变量和时间分组参数，您可以添加默认值。此处设置的默认值将覆盖仪表板或问题级别设置的默认值。对于仪表板过滤器和参数，您可以选择是否隐藏参数。

• 显示标题：顾名思义。

• 允许编辑仪表板和问题：允许用户在当前集合中创建和编辑仪表板或问题。禁用时，他们仍然可以执行过滤、摘要和钻取等操作，但无法保存结果。

配置嵌入

要定义适用于页面上每个嵌入的配置，请使用 defineMetabaseConfig() 函数。其参数包括

• instanceUrl: "https://your-metabase-url"（必需）：您的 Metabase 实例的 URL，例如 https://youlooknicetoday.metabaseapp.com

• theme: {...}（可选）：嵌入的外观选项。

• useExistingUserSession: true|false（可选，仅用于开发）- 允许您使用您的 Metabase 管理员账户会话在本地预览嵌入。仅在 Google Chrome 中支持。

• apiKey: mb_YourAPIKey（可选，仅用于开发）- 另一种在本地预览嵌入的方式，使用 API 密钥。

• fetchRequestToken: () => Promise<{ jwt: string }>（可选）- 您可以通过指定 fetchRequestToken 函数来定制 SDK 如何获取 JWT 身份验证的刷新令牌。请参阅 定制 JWT 身份验证。

主题

您可以使用嵌入配置中的 theme 参数来指定颜色、字体、间距和其他外观选项。

例如，此代码定义了文本的字体、颜色和大小，以及背景颜色和用于过滤器和摘要的颜色

<script>
  defineMetabaseConfig({
    instanceUrl: "https://your-metabase-url",
    theme: {
      fontFamily: "Lato",
      fontSize: "16px",
      colors: {
        background: "#11123d",
        "text-primary": "#f9f9fc",
        brand: "#50e397",
        filter: "#7172AD",
        summarize: "#88BF4D",
      },
    },
  });
</script>

请参阅 外观。

身份验证

使用现有用户会话测试嵌入

现有会话只能用于在本地测试嵌入。要使您的嵌入可用于生产环境，您需要实现 SSO。

如果您已登录 Metabase，则可以使用该现有的会话 cookie 来预览和测试您的嵌入。这仅在您用于 Metabase 会话的同一浏览器（我们推荐 Chrome）中有效（因此在隐身模式下无效）。

在您的嵌入代码中，将 useExistingUserSession: true 添加到 defineMetabaseConfig() 中。请参阅 配置嵌入。

<script>
  defineMetabaseConfig({
    instanceUrl: "https://your-metabase-url",
    useExistingUserSession: true,
  });
</script>

请注意，这在某些浏览器中或在隐身模式下无效。如果您想使用现有的 Metabase 会话来测试您的嵌入，我们建议使用 Chrome。

使用 API 密钥测试嵌入

API 密钥只能在本地测试嵌入。要使您的嵌入可用于生产环境或将其部署到其他域，您需要实现 SSO。

要使用 API 密钥测试您的嵌入

1. 创建一个 API 密钥
2. 将 apiKey: "YOUR_API_KEY" 添加到 defineMetabaseConfig() 中

<script>
  defineMetabaseConfig({
    instanceUrl: "https://your-metabase-url",
    apiKey: "mb_hopeyouhaveaniceday",
  });
</script>

API 密钥仅应用于与受信任的人进行测试。任何能够访问前端的人都可以获取 API 密钥并将其用于对 Metabase API 发出请求。因此，我们只允许在 localhost 上使用 API 密钥。

设置 SSO

在 localhost 以外的域中嵌入需要 SSO。您可以使用 JWT 或 SAML SSO。要配置 SAML，请参阅 使用 SAML 进行身份验证。要配置 JWT，请按照以下步骤操作。

1. 在 Metabase 中，配置 JWT SSO。

2. 在您的应用后端，添加一个新端点来处理身份验证。

您需要在后端添加一个库来签名您的 JSON Web Tokens。

对于 Node.js，我们推荐 jsonwebtoken

npm install jsonwebtoken --save

接下来，在您的后端设置一个端点（例如 /sso/metabase），该端点使用您的 Metabase JWT 共享密钥为经过身份验证的用户生成 JWT。此端点必须返回一个 JSON 对象，其中包含一个 jwt 属性，其中包含签名后的 JWT。 例如：{ "jwt": "your-signed-jwt" }。

此 Node.js 示例代码使用 Express 设置了一个端点

import express from "express";
import cors from "cors";
import session from "express-session";
import jwt from "jsonwebtoken";
import fetch from "node-fetch";

// Replace this with your Metabase URL
const METABASE_INSTANCE_URL = "YOUR_METABASE_URL_HERE";
// Replace this with the JWT signing secret you generated when enabling
// JWT SSO in your Metabase.
const METABASE_JWT_SHARED_SECRET = "YOUR_SECRET_HERE";

const app = express();

app.get("/sso/metabase", async (req, res) => {
  // Usually, you'd grab the user from the current session
  // Here it's hardcoded for demonstration purposes
  // Example:
  // const { user } = req.session;
  const user = {
    email: "rene@example.com",
    firstName: "Rene",
    lastName: "Descartes",
    group: "Customer",
  };

  if (!user) {
    console.log("no user");
    res.status(401).json({
      status: "error",
      message: "not authenticated",
    });

    return;
  }

  const token = jwt.sign(
    {
      email: user.email,
      first_name: user.firstName,
      last_name: user.lastName,
      groups: [user.group],
      exp: Math.round(Date.now() / 1000) + 60 * 10, // 10 minutes expiration
    },
    METABASE_JWT_SHARED_SECRET,
  );
  // The user backend should return a JSON object with the JWT.
  res.status(200).json({ jwt: token });
});

在 嵌入式 SDK 文档 中查看更多示例。

3. 嵌入默认会自动使用 SSO

默认情况下，Metabase 使用 JWT SSO，但您可以指定其他身份验证方法。要启用 SSO，请确保 *不要* 将您的配置设置为 apiKey 或 useExistingUserSession。

组件

有不同的组件可用于实现不同的最终用户体验。

虽然您可以使用组件参数来显示或隐藏嵌入组件的某些部分，但这些参数*不能*替代权限。即使您隐藏了某些内容，用户仍然可以从前端获取其令牌并使用它来查询 Metabase API。

仪表盘

渲染仪表板

<metabase-dashboard dashboard-id="1" with-title="true" with-downloads="false">
</metabase-dashboard>

必需参数

• dashboard-id - 这可以是常规 ID 或实体 ID。在嵌入中使用 实体 ID 可确保 ID 在从一个 Metabase 导出并导入到另一个 Metabase 时保持稳定。

可选参数

• with-title（默认为 true）- 在嵌入中显示仪表板标题
• with-downloads（默认为 false）- 显示将仪表板下载为 PDF 和下载问题结果的按钮
• drills（默认为 true）- 允许您钻取仪表板

• initial-parameters - 仪表板过滤器的默认值，例如 { 'productId': '42' }。

  如果您用双引号包围属性值，请确保使用单引号

  <metabase-dashboard
    dashboard-id="1"
    initial-parameters="{ 'productId': '42' }"
  ></metabase-dashboard>
  

• hidden-parameters - 要从仪表板隐藏的过滤器名称列表，例如 ['productId']

  如果您用双引号包围属性值，请确保使用单引号

  <metabase-dashboard
    dashboard-id="1"
    hidden-parameters="['productId']"
  ></metabase-dashboard>
  

问题

渲染问题（图表）

<metabase-question question-id="1"></metabase-question>

必需参数

• question-id - 这可以是常规 ID 或实体 ID。在嵌入中使用 实体 ID 可确保 ID 在从一个 Metabase 导出并导入到另一个 Metabase 时保持稳定。

  使用 question-id="new" 来嵌入查询生成器探索界面。

可选参数

• drills (默认为 true) - 允许您深入问题
• with-title (默认为 true) - 显示标题
• with-downloads (默认为 false) - 显示下载
• initial-sql-parameters - SQL 参数的默认值，仅适用于原生 SQL 问题，例如 { "productId": "42" }
• is-save-enabled (默认为 false)
• target-collection - 此选项用于强制将内容保存到特定集合。 值：常规 ID、实体 ID、"personal”、"root”

浏览器

用于渲染集合浏览器，以便用户可以浏览集合并打开仪表板或问题

<metabase-browser initial-collection="14" read-only="false"></metabase-browser>

必需参数

• initial-collection - 这可以是集合 ID 或 root。 使用集合 ID（例如 14）从特定集合开始。 使用 root 从顶级“我们的分析”集合开始。

可选参数

• read-only (默认为 true) – 如果为 true，用户可以与项目进行交互（过滤、汇总、钻取），但无法保存。 如果为 false，他们可以创建和编辑集合中的项目。

Metabot

用于渲染 AI 聊天界面

<metabase-metabot></metabase-metabot>

必需参数

无。

可选参数

• layout (默认为 auto) – 浏览器应如何定位可视化内容与聊天界面。 可能的值为
  • auto (默认): Metabot 在移动屏幕上使用 stacked 布局，在较大屏幕上使用 sidebar 布局。
  • stacked: 问题可视化内容堆叠在聊天界面之上。
  • sidebar: 问题可视化内容显示在聊天界面的左侧，聊天界面位于右侧边栏。

将 Metabase 嵌入到不同的域

如果您想将 Metabase 嵌入到另一个域（例如，如果 Metabase 托管在 metabase.yourcompany.com，但您想将 Metabase 嵌入到 yourcompany.github.io），您可以告诉 Metabase 将会话 cookie 的 SameSite 值设置为“none”。

您可以在 **管理员设置** > **嵌入** > **安全** > **SameSite Cookie 设置** 中设置会话 cookie 的 SameSite 值。

SameSite 值包括

• Lax (默认): 允许 Metabase 会话 cookie 在同一域上共享。 用于同一域上的生产实例。
• None (需要 HTTPS): 当您的应用程序和 Metabase 托管在不同域上时，请使用“None”。 与 Safari 和基于 iOS 的浏览器不兼容。
• Strict (不推荐): 不允许 Metabase 会话 cookie 与嵌入式实例共享。 如果您不想启用会话共享进行嵌入，请使用此选项。

您还可以设置 MB_SESSION_COOKIE_SAMESITE 环境变量。

如果您使用 Safari，您需要 允许跨站跟踪。 根据浏览器，您也可能在隐私/隐身标签页中查看嵌入式内容时遇到问题。

了解更多关于 SameSite cookies 的信息。