通过 iframe 集成 ChatBI

如果你们希望在自己的系统里最快复用一整页现成的数据问答体验，那么 iframe 是最直接的方式。

建议先看总览

如果你们还没判断清楚运行方式和接入方式的关系，建议先读 Data Agent 集成总览。

iframe 适合什么场景

iframe 适合：

• 希望最快上线一个可用入口
• 前端资源有限，不想自己实现聊天界面
• 接受直接复用衡石完整页面
• 不打算把聊天结果拆成自己页面里的多个局部模块

它的特点很直接：

• 你们只需要嵌一页现成页面
• 聊天界面、历史记录、结果卡片、图表展示都由衡石提供
• 你们自己的前端改动最少

iframe 下要怎么理解运行方式

iframe 解决的是“完整页面如何嵌入”。

运行方式依然存在，只是由嵌入页内部统一承接。

iframe + Agent

如果当前页面使用的是 Agent 模式：

• 这次问答会以 Agent 方式持续推进
• 用户在 iframe 中看到的是完整的 Agent 风格体验
• 你们不需要自己实现这套过程，但在做方案说明或问题定位时，仍然需要知道当前使用的是 Agent 模式

iframe + Workflow

如果当前页面使用的是 Workflow 模式：

• 执行过程主要由衡石后端工作流服务推进
• iframe 页面负责把状态、结果和图表完整展示出来

更容易理解的方式是：

• iframe 负责把完整体验带进来
• Agent / Workflow 决定这套体验在后台是按哪种方式运行

最小可运行示例

<iframe
 src="https://your-hengshi-host/copilot"
 width="100%"
 height="100%"
 style="border: 0;">
</iframe>

只要当前浏览器已经具备衡石登录态，或者你们已经完成了单点登录，页面就可以直接显示 ChatBI。

常用 URL 参数

指定数据来源

1. 与图表所在数据源对话

?appId={应用 ID}&chartId={图表 ID}

2. 与数据包数据模型对话

?dataAppId={数据包 ID}&datasetId={数据集 ID}

3. 与多个数据源对话

?dataSources=[{"dataAppId":{数据包 ID1},"datasetId":{数据集 ID1}},{"dataAppId":{数据包 ID2},"datasetId":{数据集 ID2}}]

提示

dataSources 需要先做 URL encode。

指定图表主题

?chartTheme={仪表盘主题 ID}

只显示指定对话

?conversationId={对话ID1,对话ID2}&chatUid={uid1,uid2}

登录认证

?activeAuth=jwt-param&jwtParam={JWT 参数}

iframe 不适合解决什么问题

• 不适合深度定制聊天窗口内部 UI
• 不适合把问答结果拆成多个业务模块嵌入不同位置
• 不适合只拿后端能力而不复用页面
• 不适合当成标准图表协议输出能力来使用

如果后续需要这些能力，通常意味着应该改看 JS SDK 集成 或 API 集成。

一句话总结

iframe 适合“最快把完整页面嵌进来”。

它能帮你们省掉大部分前端实现工作，但不会改变底层仍然存在 Agent 模式和 Workflow 模式这件事。