互 互客鱼 返回主站
/

嵌入小部件

安装代码片段

小部件是单个 <script> 标签。将其放在任何页面上， 传入智能体 ID，即可上线。包压缩后 ≤50KB，在 Shadow DOM 中运行， 因此您的网站无法对其进行样式设置，并且永远不会阻塞页面加载（使用 async）。

代码片段

将此代码粘贴到 </body> 之前： 

<script
    src="https://your-app.test/widget/widget.js?v=ab12cd34"
    data-agent-id="01HXY..."
    async></script>

完整的代码片段（包含您的智能体 ID 和当前的缓存清除哈希）在每个智能体的 设置 页面，旁边有一个复制按钮。

URL 中的内容

  • src — 指向您互客鱼部署上的 /widget/widget.js。?v=<hash> 后缀是包的内容哈希；每当小部件重建时都会变化，因此客户不会卡在 CDN 缓存的过时版本上。
  • data-agent-id — 已发布智能体的 ULID。小部件的加载器读取此属性，并在每次 /v1/widget/init 调用中使用它。
  • async — 非阻塞。小部件在包下载完成后出现；您页面的加载指标不受影响。

它注入什么

启动时，加载器：

  1. 在 <body> 底部创建一个 <div> 并为其附加 Shadow DOM。
  2. 在 shadow root 内渲染启动器（小按钮）。
  3. 调用 POST /v1/widget/init 获取智能体配置 + JWT + 最近的历史记录。
  4. 根据智能体的行为规则连接触发监听器（滚动、空闲、退出意图）。
  5. 在 localStorage 中持久化一个小的 anon_id，以便同一浏览器在重新加载时保持相同的对话。

自定义启动器

主题完全由智能体驱动——详见 角色设定、主题和提示词。 小部件从 init 响应中读取 theme.position、theme.primary、 theme.accent、theme.radius 和 theme.launcher_label 并相应渲染。

没有每页自定义——启动器始终从智能体读取。如果您需要在不同页面上有不同的外观， 请嵌入两个不同的智能体。

编程控制

小部件公开一个全局变量 window.hukeyu.mount()， 加载器用它来启动。脚本标签的 async 属性和自动挂载处理了 常见情况，因此您通常不需要直接调用它。 

// 将小部件挂载到自定义宿主元素（罕见）。
window.hukeyu.mount(document.getElementById('chat-host'));

目前还没有公共的 open / close / send / on API —— 这些功能被推迟了。如果 您今天需要在捕获潜在客户时触发转化分析，请订阅 lead.captured webhook（详见 出站 webhook）。

单页应用

小部件每次页面加载时加载一次，但只要脚本标签保留在 DOM 中， 对话就会跨应用内导航持续存在。当路由器更改路由时，您不需要重新挂载它—— Shadow DOM 和 JWT 会保持不变。

如果您的 SPA 在路由更改时完全重新挂载（例如，您拆除了 body）， 小部件将重新初始化并从过去 24 小时的历史记录中恢复访客的对话。

每次 init 发送的内容

POST /v1/widget/init 包括：

  • agent_id — 来自 data-agent-id 的值。
  • page_url — 当前的 location.href，用于检索中的"当前页面"提升。
  • anon_id — 访客在首次访问时生成的 localStorage 中的持久 ID。

服务器还会读取 Origin、Referer 和 Accept-Language 头——Origin 用于 允许来源检查， Accept-Language 用于默认语言检测。

版本控制和缓存

包 URL 进行了内容哈希（?v=<hash>）。在每次新部署时， 哈希都会变化，因此包上的 Cache-Control: max-age 头可以很激进 （一年），而不会让客户卡在旧版本上。

客户不应手动固定哈希——重新安装时始终从智能体设置页面复制最新的代码片段。