# 把问数窗口嵌进网页

将问数窗口嵌入业务页面，并通过绑定角色控制访客的数据权限。

嵌入把一个数据智能体变成一条公开地址，用 iframe 放进你自己的页面。访客不登录 AskTable，也不用选数据源或角色；每个地址绑定一个固定角色，所有访客都在这个角色的数据范围内提问。

企业微信和 WPS 在这里只是 iframe 的宿主页面，不是 AskTable 的消息频道，也不等于企业微信/WPS 登录——那两种登录走的是[企业微信与 WPS 身份接入](https://docs.asktable.com/admin/identity)。

## 开始前

- 权限：项目角色需要是「项目负责人」或「项目管理员」。
- 前置：一个配好的数据智能体，见[创建并配置数据智能体](https://docs.asktable.com/agent/overview)。
- 先选好角色：这个角色的数据范围会对所有访客公开，绑定前先确认范围适合对外。
- 宿主页面：要嵌入的页面能改 HTML，用来放 `<iframe>`。
- 入口：左侧主导航 → 「更多」 → 打开目标智能体 → 顶部标签「嵌入」。

## 操作步骤

**新建嵌入地址**

「嵌入」标签的区块标题是「嵌入地址」，说明这个区块用来创建可嵌入地址、通过 iframe 把这个智能体嵌入到外部站点。列表为空时显示暂无嵌入地址，并提示可以创建一个嵌入地址、把智能体嵌入到外部站点。点「新建地址」，弹出新建嵌入地址对话框。

**填名称和角色**

- 名称必填，占位符举例是官网嵌入，最多 255 个字符。
- 角色必填，下拉里选一个已有角色。角色带必填变量时，弹窗要求把变量值填完才能提交；这些变量对所有访客固定生效。

所有访客共用这一个角色，看到相同的数据边界。要按访客身份隔离数据，改用支持人员授权的[飞书](https://docs.asktable.com/integrations/feishu)或 [Slack](https://docs.asktable.com/integrations/slack) 频道，或企业身份登录。

**决定是否打开可信域名**

表单里有个可信域名开关，默认关闭。关闭时下方说明任何网站都可嵌入此地址、不校验来源域名，也就是任何站点都能嵌这段 iframe。

打开后出现允许域名输入框，占位符举例是 example.com 或 \*.example.com。填外层嵌入站点（iframe 所在页面）的域名，不是 AskTable 自己的域名；填域名即可，不用带 `http://` 或 `https://`，用 `*.example.com` 覆盖所有子域。开了校验但白名单留空，等于谁都嵌不了，所以至少要填一个。

**保存并复制嵌入代码**

点「保存」，成功后提示创建成功。地址新建即启用，列表项右侧的状态文字是已启用。

在列表项右侧「更多」菜单里点「复制嵌入代码」，复制成功后会给出提示。把代码贴进宿主页面：

```html
<iframe src="https://<你的 AskTable 站点>/embed/emb_xxxx" referrerpolicy="strict-origin-when-cross-origin" style="width:100%;height:600px;border:0" />
```

`referrerpolicy` 这一项不要删。Firefox 读不到 iframe 的父页面来源，靠它兜底；删掉后如果宿主页又设了全局 `no-referrer`，开着可信域名校验会直接 403。

**核对列表项上的状态**

每条地址在列表里显示：名称、角色徽标、域名徽标（开了校验显示域名个数，没开显示任意域名）、使用统计（近 7 天的活跃对话数）与最近活跃时间（没有对话时显示暂无对话），最右侧是状态文字加开关。

关掉开关，状态变成已禁用，正在进行的访客会话立即断开。重新打开后，访客刷新页面即可继续。

**用一个真实宿主域名验收**

至少验证四件事：正常来源能打开页面并完成一次提问；不在白名单的来源被拒；访客的追问范围不超过绑定角色；停用地址后现有会话断开。

## 关键约束

| 项目         | 值或默认                               | 在哪里改                |
| ---------- | ---------------------------------- | ------------------- |
| 名称         | 必填，最多 255 个字符                      | 智能体 → 「嵌入」 → 「新建地址」 |
| 角色         | 必填，一条地址绑一个角色                       | 智能体 → 「嵌入」 → 「新建地址」 |
| 可信域名       | 默认关（不校验来源）                         | 智能体 → 「嵌入」 → 「新建地址」 |
| 允许域名       | 只在开关打开后可填；存裸主机名，支持 `*.example.com` | 智能体 → 「嵌入」 → 「新建地址」 |
| 启用状态       | 新建即启用                              | 「嵌入」列表项右侧开关         |
| 访客会话令牌有效期  | 24 小时                              | 无界面开关               |
| 访客页的快速模式   | 新建对话初始为开（走快速回答）；访客可关掉换更长的推理        | 访客页输入框下方工具栏         |
| 白名单收紧的生效时间 | 最迟在下次换发令牌或 24 小时到期后                | 无界面开关               |

## 出问题怎么判断

| 现象                  | 判定条件                                                                       | 处理                                         |
| ------------------- | -------------------------------------------------------------------------- | ------------------------------------------ |
| 访客页提示该嵌入暂不可用        | 请求返回 `EMBED_DISABLED`（HTTP 403），地址开关是已禁用状态                                 | 到智能体「嵌入」列表把开关打开                            |
| 访客页提示来源不被允许         | 请求返回 `EMBED_ORIGIN_NOT_ALLOWED`（HTTP 403）                                  | 把宿主页域名加进允许域名；确认 iframe 没删 `referrerpolicy` |
| 访客页提示资源不存在          | 请求返回 `RESOURCE_NOT_FOUND`（HTTP 404）                                        | 地址已被删除，或 iframe 里的 `emb_` 标识写错             |
| 访客页没有「新对话」按钮        | 错误码是 `EMBED_DISABLED`、`EMBED_ORIGIN_NOT_ALLOWED` 或 `RESOURCE_NOT_FOUND` 之一 | 这三类新建对话也一样失败，按上面三行分别处理                     |
| 改完白名单后旧页面仍能打开       | 访客手里的会话令牌还没到期                                                              | 等下次换发令牌或 24 小时到期；紧急时先停用地址                  |
| 访客只能问到一部分数据         | 绑定角色的数据范围就是这么划的                                                            | 换一个角色，或到「角色」里改范围                           |
| 访客想继续上次的对话，刷新后却从头开始 | 距离上次超过 24 小时，令牌已过期                                                         | 这是预期行为；同一个浏览器内 24 小时以内刷新会接回同一对话            |

## 下一步

- 按访客身份隔离数据，而不是共用一个公开地址：[控制飞书渠道用户的数据权限](https://docs.asktable.com/permissions/feishu)、[企业微信与 WPS 身份接入](https://docs.asktable.com/admin/identity)
- 用「角色」和「策略」把公开范围收窄：[权限与数据安全](https://docs.asktable.com/permissions)
- 不用访客来问，改成到点推送：[定时分析报告](https://docs.asktable.com/integrations/scheduled-reports)