Widget Embed 适用于“能改自己官网/落地页”的团队：入口留在你的页面里，但接待、路由、供给承接与审计仍回到平台接入层。
受控开放 Widget 运行时可公开加载；创建渠道、复制公开嵌入标识与生产使用仍需通过 Console 的正式流程完成。
如果你只是想最快验证需求且暂时不改网站，先看 Hosted Inbox。
- 你能修改目标页面的 HTML、CMS 或前端组件。
- 你已经从 Console 复制了可公开嵌入的 Channel 标识，而不是 API Key。
- 你的 CSP 允许 Widget 脚本与 Console public endpoint 正常工作。
推荐阅读
登录 Console → 创建 → 复制 → 粘贴 → 验证
Hosted Widget 把入口留在你的页面，平台继续负责承接。
完成后，你的页面会拥有一个由平台承接的悬浮咨询入口；访客无需离开当前站点，线索由平台负责接待、路由与后续承接。浏览器只使用可公开嵌入的 Channel 标识，不暴露 API Key 或私有 bearer。
create → copy → paste → verify 快速上线
- create： 打开
https://console.zhenrobot.com/start并完成登录，在https://console.zhenrobot.com/integrations创建或选择渠道。 - copy： 在渠道的 Console 操作中点击复制公开嵌入标识；复制的是可放入浏览器的公开值，不是域名验证结果，也不是 API Key。
- paste： 将下面 snippet 粘贴到目标页面的
</body>前，并把复制的公开嵌入标识原样填入data-channel-id。 - verify： 发布页面；看到悬浮入口，并在 Network 中看到
config请求，即表示入口已加载。
域名验证用于确认你能控制要部署 Widget 的站点；它不会生成、替代或修改 snippet 中的公开嵌入标识。完成域名验证后，仍要回到 Integrations 复制公开嵌入标识并粘贴到页面。
嵌入时该用哪个标识？
复制 Console 的公开嵌入标识，并原样填入 data-channel-id。它不是 API Key，也不是你在管理页面看到的内部渠道主键。
手机上可左右滑动查看完整对照。
| 你看到的名称 | 出现位置 | 用途 | 可以放进浏览器吗？ |
|---|---|---|---|
| 管理 Channel ID | Console 的渠道管理与受控管理接口 | 管理、配置与审计时定位渠道 | 否；不要把管理凭证或内部标识写进页面 |
| 公开嵌入标识 | Console 复制按钮 | Widget snippet 的 data-channel-id 值 | 是；这是唯一需要复制到页面的值 |
channelKey | Core public API：/api/public/channels/{channelKey}/… | Core 协议公开路由中的参数名 | 当前 Widget MVP 中与公开嵌入标识承载同一公开值；仍从 Console 复制，不要自行拼接 |
channelId | Console public proxy：/api/public/widget/{channelId}/… 与 snippet 属性 | Console 代理路由和嵌入脚本的参数名 | 当前 Widget MVP 中与 channelKey 承载同一公开值 |
只记一条： 页面只放 Console 复制的公开嵌入标识；绝不放 API Key、私有 bearer、管理凭证或自行猜测的渠道 ID。
<script
src="https://console.zhenrobot.com/embed/c2ai2x-widget.js"
data-channel-id="<YOUR_PUBLIC_CHANNEL_ID>"
async
></script>
浏览器只使用 Console 复制的公开 Channel 标识。不要在页面、CMS 或前端代码中放入 API Key、私有 bearer 或管理凭证。
你需要准备什么
- 一个要放入口的页面（官网 / 活动落地页 / 产品页）
- 能在页面里插入一段
<script>（或在你的前端框架里动态加载脚本） - 一个已创建的渠道
- 一个从 Console 复制的可公开嵌入 Channel 标识
1) 登录、创建渠道并复制公开标识
从 Console 开始页进入：
- 开始入口：
https://console.zhenrobot.com/start - 渠道管理：
https://console.zhenrobot.com/integrations
完成登录后，在 Integrations 创建渠道，或选择一个已有渠道。复制 Console 提供的公开嵌入标识，并将它保存在部署变量中；不要把 API Key 或私有 bearer 放进浏览器。
如果公开配置请求返回 404，先在 Integrations 确认复制的是当前渠道的公开嵌入标识，再检查脚本属性和 CSP。
2) 用一段脚本完成嵌入
把下面这段放到页面 </body> 之前即可：
<script
src="https://console.zhenrobot.com/embed/c2ai2x-widget.js"
data-channel-id="<YOUR_PUBLIC_CHANNEL_ID>"
async
></script>
说明：
data-channel-id：必填，填从 Console 复制的公开 Channel 标识src：固定指向 console 的 widget 运行时脚本
3) 按页面需要调整入口
<script
src="https://console.zhenrobot.com/embed/c2ai2x-widget.js"
data-channel-id="<YOUR_PUBLIC_CHANNEL_ID>"
data-launcher-label="开始咨询"
data-default-open="false"
async
></script>
data-launcher-label：悬浮按钮文案（默认AI 咨询）data-default-open：是否默认展开（true/false，或1/0）
高级参数（仅在特殊环境需要）：
data-console-origin：当你需要把请求指向非默认 console origin 时使用（默认取脚本src的 origin）
4) 在 React / Next.js 中挂载
AI 接入指令
让 AI 帮你挂载 Widget
复制后交给 Claude Code、Cursor 或 Codex。
请先阅读当前项目，确认技术栈与现有页面结构。
目标：将 C2AI2X Widget 安全挂载到现有站点。
准备：
1. 登录 https://console.zhenrobot.com/start，在 Integrations 创建或选择渠道。
2. 从 Console 复制真实的公开嵌入 Channel 标识；不要使用 API Key、私有 bearer 或管理 Channel ID。
3. 在合适页面只注入一次 https://console.zhenrobot.com/embed/c2ai2x-widget.js，并将公开标识填入 data-channel-id。
4. 若站点使用 CSP，允许 script-src 与 connect-src 访问 https://console.zhenrobot.com。
5. 将真实 chkey_… 公开标识替换到 data-channel-id；<YOUR_PUBLIC_CHANNEL_ID> 仅为示例，绝不能直接发布。
6. 使用无痕窗口访问实际站点，确认悬浮入口出现、config 请求返回 200，并发送一条测试咨询。
7. 若 config 非 200，输出实际状态码、响应体、CSP 控制台报错和脚本注入位置；不得改动现有鉴权、路由或业务逻辑。
请列出修改文件与验证结果。只使用 Console 复制的公开嵌入标识。
原则：只加载一次；路由切换不要重复注入脚本。
import { useEffect } from "react";
export function C2ai2xWidget() {
useEffect(() => {
if (document.querySelector('script[data-zhen-widget-hosted="true"]')) return;
const script = document.createElement("script");
script.src = "https://console.zhenrobot.com/embed/c2ai2x-widget.js";
script.async = true;
script.setAttribute("data-zhen-widget-hosted", "true");
script.setAttribute("data-channel-id", "<YOUR_PUBLIC_CHANNEL_ID>");
script.setAttribute("data-launcher-label", "开始咨询");
document.body.appendChild(script);
return () => script.remove();
}, []);
return null;
}
5) 用 Network 面板验证请求
Widget 运行在你的页面中，但会向 console 的 public 接口发起请求（跨域、无需你自己带 cookie）：
GET /api/public/widget/{publicChannelId}/configPOST /api/public/widget/{publicChannelId}/intake- 部分模式下会使用
EventSource做流式读取（同样走 public endpoint，具体 URL 以 config 返回为准）
如果浏览器 Network 中看不到 config 请求，优先检查脚本地址、公开 Channel 标识和 CSP；如果 config 成功但提交失败，再检查 intake 请求的状态码与响应体。
推荐阅读
排障时按这个顺序检查
6) CSP 与安全配置
如果你的站点启用了严格 CSP，至少需要考虑：
script-src允许https://console.zhenrobot.comconnect-src允许https://console.zhenrobot.com（含fetch与EventSource）- Widget 会动态插入
<style>（Shadow DOM 内），严格策略下style-src可能需要允许 inline（或为该脚本提供 nonce/hash 方案）
注意：Widget 不需要你把 API Key 放到前端，也不应该把任何私有 bearer 暴露给浏览器。
7) 什么时候升级到 Full API
Widget 适合把入口“放回自己页面”并跑通咨询与承接闭环；当你需要把结果、状态、审计或事件写回你的系统，再进入 API 规范与接入评估。
接入辅助服务
卡在接入环节？我们可以协助完成。
¥399 / 站点 / 案例适合需要脚本挂载、公开标识确认或 CSP 基础排错协助的团队。
- 确认接入路径
- 协助生成或挂载入口
- 一次基础联调与上线前检查
- 不包含复杂定制与长期运营
- 不代管私有凭证或生产权限
- 不包含完整 API 项目实施
推荐阅读