网站小部件
将您的 AI 语音代理嵌入任何网站,以便访客可以直接从浏览器开始语音对话。小部件选项卡提供嵌入代码、自定义选项和域安全设置。
在寻找回拨小部件?
回拨小部件与本页面的小部件工作方式截然不同——它不是开始浏览器语音通话,而是收集访客的电话号码并让您的代理回拨他们。请参阅专用的回拨小部件页面。
小部件类型
Hanc.AI 提供四种浏览器内小部件类型,以及一个用于电话回拨的单独回拨小部件:
| 小部件 | 标签名 | 描述 | 最适合 |
|---|---|---|---|
| 浮动小部件 | hanc-ai-floating-call | 漂浮在您页面上的球形按钮 | 始终可见的行动号召 |
| 药丸小部件 | hanc-ai-pill-call | 内嵌在您内容中的紧凑药丸形按钮 | 现有布局中的最小占用空间 |
| 药丸浮动小部件 | hanc-ai-pill-float-call | 与药丸相同的紧凑药丸形状,但像浮动小部件一样随页面浮动 | 当您想要随访客滚动而跟随的药丸美学时 |
| 内嵌小部件 | hanc-ai-inline-call | 嵌入页面内容的完整大小通话按钮 | 专用的"与我们交谈"部分 |
| 回拨小部件 | hanc-ai-callback | 电话号码表单;代理回拨访客 | 潜在客户开发页面、高意向着陆页——请参阅回拨小部件 |
通用属性
所有小部件类型都支持这些核心属性:
| 属性 | 必需 | 描述 | 默认值 |
|---|---|---|---|
agent-id | 是 | 您的代理的唯一标识符 | — |
voice-service-url | 否 | 覆盖语音服务 URL | 自动检测 |
api-base-url | 否 | 覆盖 API 基本 URL | 自动检测 |
显示属性
| 属性 | 描述 | 值 | 默认值 |
|---|---|---|---|
position | 小部件在页面上的位置 | bottom-right、bottom-left、top-right、top-left、static | bottom-right |
size | 小部件大小(像素) | 数字 | 120 |
theme | 颜色主题名称 | 见颜色主题 | default |
按钮文本属性
| 属性 | 描述 | 默认值 |
|---|---|---|
button-start-text | 空闲按钮上显示的文本 | "Call" |
button-connecting-text | 连接时显示的文本 | "Connecting..." |
button-end-text | 活动通话期间显示的文本 | — |
条款属性
| 属性 | 描述 | 默认值 |
|---|---|---|
terms-enabled | 在通话前启用同意对话框 | false |
terms-content | Markdown 格式的同意文本 | "" |
terms-url | 您的条款和条件页面链接 | "https://hanc.ai/terms" |
privacy-url | 您的隐私政策页面链接 | "https://hanc.ai/privacy" |
信息
设置在 HTML 元素上的条款属性会被从 API 获取的代理小部件设置覆盖,除非 skip-fetch 设置为 true。
声音属性
| 属性 | 描述 | 默认值 |
|---|---|---|
sound-enabled | 启用通话开始/结束声音 | true |
sound-volume | 声音效果音量 | 0.25 |
sound-preset | 声音预设标识符 | "1" |
颜色主题
使用 11 个内置颜色主题自定义小部件外观:
| 主题 | 值 |
|---|---|
| 默认 | default |
| 紫色 | purple |
| 蓝色 | blue |
| 青色 | cyan |
| 翡翠 | emerald |
| 琥珀 | amber |
| 橘红 | tangerine |
| 玫瑰 | rose |
| 余烬 | ember |
| 黑色 | black |
| 白色 | white |
每个主题都有深色和浅色变体。通过嵌入代码中的 theme 属性设置主题,或在代理的小部件设置中配置它。
嵌入示例
浮动小部件
<hanc-ai-floating-call agent-id="YOUR_AGENT_ID"></hanc-ai-floating-call>
<script src="https://unpkg.com/hanc-webrtc-widgets" async type="text/javascript"></script>
带主题和位置的浮动小部件
<hanc-ai-floating-call
agent-id="YOUR_AGENT_ID"
theme="emerald"
position="bottom-left"
size="140"
></hanc-ai-floating-call>
<script src="https://unpkg.com/hanc-webrtc-widgets" async type="text/javascript"></script>
药丸小部件
<hanc-ai-pill-call agent-id="YOUR_AGENT_ID"></hanc-ai-pill-call>
<script src="https://unpkg.com/hanc-webrtc-widgets" async type="text/javascript"></script>
内嵌小部件
<hanc-ai-inline-call agent-id="YOUR_AGENT_ID"></hanc-ai-inline-call>
<script src="https://unpkg.com/hanc-webrtc-widgets" async type="text/javascript"></script>
固定小部件版本
上面的脚本 URL 始终加载最新发布的小部件——您的网站会自动获取改进。如果您需要锁定到已知良好的版本,请使用 https://unpkg.com/hanc-webrtc-widgets@1.4.0 明确固定(替换为您想要的版本)。@latest 标签是未指定版本时的默认值。
小部件事件
小部件发出您可以在 JavaScript 中监听的事件:
| 事件 | 描述 |
|---|---|
status-changed | 通话状态更改时触发 |
connecting | 正在建立通话 |
connected | 通话处于活动状态 |
idle | 无活动通话 |
error | 发生错误 |
audio-track | 接收到远程音频轨道(用于可视化) |
local-audio-track | 本地麦克风音频轨道(用于可视化) |
microphone-enabled | 麦克风已启用 |
microphone-disabled | 麦克风已禁用 |
call-start | 通话成功开始时触发 |
call-end | 通话结束时触发 |
示例:监听事件
const widget = document.querySelector('hanc-ai-floating-call');
widget.addEventListener('call-start', () => {
console.log('Call started');
});
widget.addEventListener('call-end', () => {
console.log('Call ended');
});
技术要求
小部件要求访客的浏览器支持:
- WebGL 2.0 — 用于渲染
- Web Audio API — 用于音频处理
- WebRTC — 用于实时语音通信
所有现代浏览器(Chrome、Firefox、Safari、Edge)都支持这些技术。
域限制
控制哪些网站可以嵌入您的代理小部件。
始终允许的域
无论配置如何,以下域始终被允许:
hanc.ai(及子域)hanc.me(及子域)localhost
允许所有域
默认情况下,您的小部件可以嵌入任何网站。在小部件设置中切换**"允许所有域"**以限制此功能。
限制为特定域
受限时,添加每个应被允许的域:
- 输入不带
https://的域名(例如,example.com) - 子域需要单独的条目(例如,
www.example.com、shop.example.com) - 可以指定端口(例如,
localhost:3000) - 最多可以将 50 个域列入白名单
安全
对于生产代理,将小部件限制在您自己的域中以防止未经授权的嵌入。
条款和条件
在来电者可以开始对话之前启用同意对话框。
配置
| 设置 | 描述 |
|---|---|
| 启用条款 | 切换条款对话框开/关 |
| 条款内容 | 向用户显示的 Markdown 格式同意文本(最多 5,000 个字符) |
| 条款 URL | 您的完整条款和条件页面链接 |
| 隐私 URL | 您的隐私政策页面链接 |
启用时:
- 用户在开始通话前看到同意对话框
- 他们必须点击"同意"才能继续
- 同意存储在浏览器本地
- 重置同意按钮清除存储的同意以供测试
内容格式
条款内容支持 Markdown 格式:
- 使用
####表示标题 - 使用
**粗体**表示强调 - 使用换行以提高可读性