交互式嵌入

仅需一小时，构建一个可行的概念验证（POC）。

加入我们的下一次交互式嵌入工作坊。

立即注册

如果您想提供多租户自助分析，**交互式嵌入**是您的理想选择。

交互式嵌入是唯一一种与您的权限和SSO集成的嵌入方式，以便为用户提供适当级别的访问权限，从而对数据进行查询和钻取。

交互式嵌入演示

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

要查看查询构建器的实际操作，请点击 Reports > + New > Question。

快速开始

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

交互式嵌入的先决条件

1. 确保您拥有 Pro 或 Enterprise 计划的许可证令牌。
2. 将人员组织到 Metabase 组中。
3. 为每个组设置权限。
4. 设置SSO，以便在用户登录时自动应用权限并显示正确的数据。通常情况下，**我们推荐使用SSO with JWT**。

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

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

在 Metabase 中启用交互式嵌入

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

在您的网站上设置嵌入

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

准备好推出交互式嵌入后，请确保用户**允许**来自 Metabase 的浏览器 Cookie，否则他们将无法登录。

将 iframe 指向 Metabase URL

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

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

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

要嵌入特定的 Metabase 仪表盘，您需要使用仪表盘的实体 ID URL /dashboard/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结构：/[项目类型]/entity/[实体ID]。示例

• /collection/entity/[实体ID]
• /model/entity/[实体ID]
• /question/entity/[实体ID]

将 iframe 指向身份验证端点

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

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

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

如果您正在使用 JWT，您可以使用重定向的相对路径（即，您的 Metabase URL，不包含站点 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 (默认值)：允许在用户从外部站点导航到源站点时发送 cookie（例如点击链接时）。
• None：允许所有跨站请求。与大多数 Safari 和 iOS 浏览器（如 iOS 上的 Chrome）不兼容。如果将此环境变量设置为“None”，则必须在 Metabase 中使用 HTTPS，以防止浏览器拒绝请求。
• Strict (不推荐)：绝不允许在跨站请求中发送 cookie。警告：这将阻止用户通过外部链接访问 Metabase。

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

如果您使用的是 Safari，您需要允许跨站跟踪。根据浏览器的不同，在隐私/无痕标签页中查看嵌入项时也可能会遇到问题。

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

保护交互式嵌入

Metabase 使用 HTTP cookies 来验证用户身份并使他们保持登录到您嵌入的 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 组件

参考应用

要构建一个使用 SSO with JWT 的示例交互式嵌入，请参阅我们的参考应用

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

延伸阅读

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