第三方接入
客服系统接入说明
把脚本嵌进你的前台网站（及可选的管理后台）即可。密钥由运营方在租户管理中创建站点后提供。把示例里的域名换成当前服务地址。
1. 接入前准备
向运营方索取：服务地址、site-key（前台）、agent-key（后台，勿公开）、并确认你的域名已加入 Origin 白名单。
浏览器地址栏的协议、主机、端口必须与白名单完全一致，否则挂件无法启动。
2. 访客前台（必接）
在公共布局加入（建议 </body> 前，全站一次）：
| 属性 | 必填 | 说明 |
|---|---|---|
data-site-key | 是 | 站点密钥 |
data-user-id | 否 | 业务用户 ID；客服可见；同站同 ID 跨浏览器共用会话 |
data-user-name | 否 | 业务显示名；客服侧优先展示 |
data-hide-launcher | 否 | true 隐藏右下角气泡 |
data-open-selector | 否 | 点击匹配元素时打开聊天 |
界面语言在租户管理里按站点指定，可选 English、Español、Português、中文。访客聊天窗不再提供语言切换。
登录后再补身份：
CustomerSupport.setUser({ id: String(user.id), name: user.nickname })
CustomerSupport.setUser(null) // 退出登录
JS：CustomerSupport.open() / close() / toggle()。元素加 data-cs-open 也可打开。
3. 自定义打开按钮（可选）
不隐藏气泡时，页面按钮与右下角气泡可同时使用。
5. 检查清单
- 前台 / 后台域名已告知运营方并加入白名单
- 脚本
src指向当前可访问的服务根地址 - 访客使用本站
site-key；后台使用对应agent-key - 已登录用户建议传
user-id+user-name或调用setUser - 真实域名下点开聊天，确认双方能收发消息
6. 常见问题
| 现象 | 处理 |
|---|---|
| 没有气泡 / 启动失败 | 检查 site-key 与 SITE_ORIGINS |
| 换票 403 | Origin 与白名单不一致（协议 / 端口） |
| 不实时 | 确认走正确服务地址；Nginx 需转发 WebSocket |
| 客服看不到昵称 | 传入 data-user-id / data-user-name 或 setUser |
请勿把 agent-key 写进公开页面或公开仓库。