交互式嵌入

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

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

交互式嵌入 允许您将整个 Metabase 应用嵌入到 iframe 中。交互式嵌入会集成您的 权限 和 SSO，为用户提供正确的访问级别，以便他们能够 查询 和 深入分析 您的数据。

如果您刚开始使用 Metabase 嵌入，请考虑使用 Embedded Analytics JS 而不是交互式嵌入——它是一个改进的、更具可定制性的选项，用于嵌入交互式 Metabase 元素。交互式嵌入仍然完全受支持。

交互式嵌入演示

要了解交互式嵌入的功能，请查看我们的 交互式嵌入演示。

要查看查询构建器，请点击报告 > + 新建 > 问题。

快速开始

查看 交互式嵌入快速入门指南。

交互式嵌入的先决条件

1. 请确保您拥有 Pro 或 Enterprise 计划 的 许可证令牌。
2. 将用户组织到 Metabase 组 中。
3. 为每个组设置 权限。
4. 设置 SSO 以自动应用权限并在用户登录时显示正确的数据。总的来说，我们建议使用 JWT SSO。

如果您正在处理 多租户 情况，请查看我们关于 为不同客户模式配置权限 的建议。

如果您在本地运行应用程序，并且使用 Pro Cloud 版本，或者 Metabase 和您的应用程序托管在不同的域中，您需要将 Metabase 环境的会话 cookie SameSite 选项设置为“none”。

在 Metabase 中启用交互式嵌入

1. 转到管理员 > 嵌入 > 交互式。
2. 点击启用交互式嵌入。
3. 在授权来源下，添加您要嵌入 Metabase 的网站或 Web 应用程序的 URL（例如 https://*.example.com）。

在您的网站上设置嵌入

1. 创建一个 iframe，其 src 属性设置为
   • 您要嵌入的 Metabase 页面的 URL，或者
   • 一个 身份验证端点，该端点将重定向到您的 Metabase URL。
2. 可选：根据您的 Web 应用程序的设置方式，设置 环境变量 以
   • 添加您的许可证令牌.
   • 将 Metabase 嵌入到不同的域.
   • 保护您的交互式嵌入.
3. 可选：启用与嵌入式 Metabase 的通信，使用支持的 postMessage 消息。
   • 从 Metabase 发送
   • 发送到 Metabase
4. 可选：设置参数以 显示或隐藏 Metabase UI 组件。

当您准备好部署交互式嵌入时，请确保用户允许来自 Metabase 的浏览器 cookie，否则他们将无法登录。

将 iframe 指向 Metabase URL

转到您的 Metabase 并找到您要嵌入的页面。

例如，要嵌入您的 Metabase 主页，请将 src 属性设置为您的 站点 URL，例如

src="https://metabase.yourcompany.com/"

要嵌入特定的 Metabase 仪表板，您需要使用仪表板的实体 ID URL /dashboard/entity/[Entity ID]。

src="https://metabase.yourcompany.com/dashboard/entity/[Entity ID]"

要获取仪表板的实体 ID，请访问仪表板并点击信息按钮。在概述选项卡中，复制实体 ID。然后在您的 iframe 的 src 属性中设置为

src=https://metabase.yourcompany.com/dashboard/entity/Dc_7X8N7zf4iDK9Ps1M3b

如果您的仪表板有多个选项卡，请选择您希望用户访问的选项卡并复制选项卡的 ID。将选项卡的 ID 添加到 URL

src=https://metabase.yourcompany.com/dashboard/entity/Dc_7X8N7zf4iDK9Ps1M3b?tab=YLNdEYtzuSMA0lqO7u3FD

您可以使用仪表板的顺序 ID，但应优先使用实体 ID，因为实体 ID 在不同的 Metabase 环境中是稳定的（例如，如果您在暂存环境中进行测试，当 导出数据并导入 到生产环境时，实体 ID 将保持不变）。

如果您想指向问题、集合或模型，请访问该项目，点击其信息，获取项目的实体 ID，然后按照 URL 结构：/[Item type]/entity/[Entity-Id]。示例

• /collection/entity/[Entity ID]
• /model/entity/[Entity ID]
• /question/entity/[Entity ID]

将 iframe 指向身份验证端点

如果您想将用户直接发送到您的 SSO 登录屏幕（即，使用带有 SSO 按钮的 Metabase 登录屏幕），并在身份验证后自动重定向到 Metabase，请使用此选项。

您需要将 src 属性设置为您的身份验证端点，并带有 return_to 参数指向编码后的 Metabase URL。例如，将用户发送到您的 SSO 登录页面并自动重定向到 https://metabase.yourcompany.com/dashboard/1

https://metabase.example.com/auth/sso?return_to=http%3A%2F%2Fmetabase.yourcompany.com%2Fdashboard%2F1

如果您使用 JWT，您可以使用相对路径进行重定向（即，不带 站点 URL 的 Metabase URL）。例如，将用户发送到位于 /dashboard/1 的 Metabase 页面

https://metabase.example.com/auth/sso?jwt=<token>&return_to=%2Fdashboard%2F1

您必须对重定向链接中的所有参数进行 URL 编码（或双重编码，具体取决于您的 Web 设置），包括筛选器参数（例如 filter=value）和 UI 设置（例如 top_nav=true）。例如，如果您在上面的 JWT 示例中添加了两个筛选器参数，则您的 src 链接将变为

https://metabase.example.com/auth/sso?jwt=<token>&redirect=%2Fdashboard%2F1%3Ffilter1%3Dvalue%26filter2%3Dvalue

跨浏览器兼容性

为确保您的嵌入式 Metabase 在所有浏览器中都能正常工作，请将 Metabase 和嵌入式应用程序放在同一顶级域 (TLD) 中。TLD 在网址的最后一部分表示，例如 .com 或 .org。

请注意，您的交互式嵌入必须兼容 Safari 才能在 iOS 上的任何浏览器（例如 iOS 上的 Chrome）上运行。

将 Metabase 嵌入到不同的域

如果您的 Metabase 和嵌入式应用程序已在同一顶级域 (TLD) 中，请跳过此部分。

如果您想将 Metabase 嵌入到另一个域（例如，Metabase 托管在 metabase.yourcompany.com，但您想在 yourcompany.github.io 中嵌入 Metabase），您可以告知 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 cookie 的信息。

保护交互式嵌入

Metabase 使用 HTTP cookie 来验证用户并让他们在嵌入式 Metabase 中保持登录状态，即使关闭浏览器会话也是如此。如果您喜欢流程图式的身份验证流程，请查看 使用 SSO 进行交互式嵌入。

要限制用户登录的时间，请将 MAX_SESSION_AGE 设置为分钟数。默认值为 20,160（两周）。

例如，最多让用户登录 24 小时

MAX_SESSION_AGE=1440

在用户结束浏览器会话时自动清除用户的登录 cookie

MB_SESSION_COOKIES=true

要手动将某人从 Metabase 注销，请加载以下 URL（例如，在您应用程序的注销页面上的隐藏 iframe 中）

https://metabase.yourcompany.com/auth/logout

如果您使用 JWT 进行 SSO，我们建议将 exp（过期时间）属性设置为较短的持续时间（例如 1 分钟）。

支持的从嵌入式 Metabase 发送的 postMessage 消息

要跟上嵌入式 Metabase URL 的更改（例如，当应用筛选器时），请设置您的应用程序以侦听来自嵌入式 Metabase 的“location”消息。如果您想将此消息用于深度链接，请注意“location”镜像“window.location”。

{
  "metabase": {
    "type": "location",
    "location": LOCATION_OBJECT_OR_URL
  }
}

要使嵌入式 Metabase 页面（如问题）填满您应用程序中的整个 iframe，请设置您的应用程序以侦听来自 Metabase 的“normal”模式的“frame”消息。

{
  "metabase": {
    "type": "frame",
    "frame": {
      "mode": "normal"
    }
  }
}

要指定您应用程序中 iframe 的大小，使其与嵌入式 Metabase 页面（如仪表板）匹配，请设置您的应用程序以侦听来自 Metabase 的“fit”模式的“frame”消息。

{
  "metabase": {
    "type": "frame",
    "frame": {
      "mode": "fit",
      "height": HEIGHT_IN_PIXELS
    }
  }
}

发送到嵌入式 Metabase 的 postMessage 消息

要更改嵌入 URL，请从您的应用程序向 Metabase 发送“location”消息。

{
  "metabase": {
    "type": "location",
    "location": LOCATION_OBJECT_OR_URL
  }
}

行和列安全性的分组策略

如果您希望来自单个客户帐户的多个用户协作处理问题和仪表板，您需要为每个客户帐户设置一个 组。

您可以使用单个、独立的组来处理 行和列安全性。例如，每个人都可以属于一个客户组，该组通过适用于您所有客户帐户中每个人的某个属性来设置具有行和列安全性的数据权限。

此外，同一客户帐户中的每个人也可以是该客户帐户特有组的成员。这样，他们就可以与其他组织内的人员协作处理集合，而不会看到其他客户帐户人员创建的内容。

显示或隐藏 Metabase UI 组件

请参阅 交互式 UI 组件。

参考应用程序

要使用 JWT SSO 构建示例交互式嵌入，请参阅我们的参考应用程序。

• Node.js + Express（附带 快速入门指南）
• Node.js + React

延伸阅读

• 交互式嵌入快速入门
• 提供面向客户的分析的策略.
• 权限策略.
• 自定义 Metabase 的外观.