交互SDK
1 概述
播报功能——播报用户指定的文本内容
1.1相关限制
2 安全校验
2.1 subscription-key的获取
注意：企业可用数字人、数字人交互任务并发路数、交互时长、对话次数等均受到企业权益的限制，请使用前先和小冰运营人员确认企业权益是否充足。
最佳实践：服务端获取signature,防止subscription-key泄露
2.2 生成signature
2.3 signature的使用
鉴权时序图
3 接入准备
需先选购小冰提供的数字分身，开始交互前，通过接口获取所有的数字人信息，从中选择一位开始交互，接口参考：获取所有虚拟人信息
3.1 选择心仪的数字人声音 接口参考：获取心仪的数字人声音
4 SDK快速集成
4.1WebSDK
引入SDK
初始化
| 参数名称 | 类型 | 是否必填 | 描述 |
|---|---|---|---|
| mountClass | string | 否，不传入则默认挂载在屏幕中间 | 传入需要挂载位置的dom类名，类名全局唯一 |
| signature | string | 是 | 参考2.1 SDK用户鉴权 |
| humanInfo | HumanInfo | 是 | 参考3 获取交互数字员工信息 |
| proxyServer | IProxyServer | 否，默认访问本域 | 自定义访问服务域名时填写 |
| webSocketServer | IProxyServer | 否，默认访问本域，若proxyServer存在访问proxyServer | 自定义websocket访问服务域名时填写 |
| customVoiceInfo | customVoiceInfo | 否，可选择声音，不传使用默认声音 |
| key | type | 描述 |
|---|---|---|
| protocol | string | 协议 |
| host | string | 域名 |
| path | string | 路径 |
1.
GET https://yourServerDomain/openapi/interactive/listVhInfo接口返回的id)GET https://yourServerDomain/openapi/interactive/listVoice/{数字人id}
返回结果
| 字段名 | 类型 | 描述 |
|---|---|---|
| code | int | 返回码，正常200，异常参考第5章错误码 |
| message | string | 返回码说明 |
| data | PrivateVoice | 数字人信息数组 |
| PrivateVoice | ||
| key | 描述 | |
| ------ | ------ | |
| voiceId | 声音id | |
| voiceName | 声音名称 |
2.
交互生命周期
| 名称 | 触发时间点 |
|---|---|
| onError | 整个交互过程遇到错误，都会调用，错误码参考第5章错误码 |
| onInited | 初始化完成，拉流之前 |
| onGetHeightAndWidth | 获取宽高接口，获取宽高后可数值容器宽高样式 |
| onJoinRoom | 流链接之时，开始交互 |
| onLeaveRoom | 流断开之后 |
| onTalkStart | 每次交互员工开始说话之前，立即调用，回调内容参考TalkRes |
| onTalkEnd | 每次交互员工开始说话完之后，立即调用，回调内容参考TalkRes |
| onRTCStatsReport | 拉流中获取流的各项参数信心，内容参考RTCStatsReport（https://developer.mozilla.org/zh-CN/docs/Web/API/RTCStatsReport） |
| onReconnectSuccess | 对话websocket断联后自动重连成功时执行的回调，回调内容参考ReconnectRes |
| 参数名称 | 类型 | 描述 |
|---|---|---|
| id | string | requestID，单句驱动开始和结束获取到的值相同，单句驱动之间值不同 |
| content | string | 数字员工播报内容 |
| 参数名称 | 类型 | 描述 |
|---|---|---|
| unplayedContent | boolean | 断连前是否在播报,如在播报，websocket重连成功会丢失结束标识 |
| content | string | websocket断连期间发送的驱动信息会在重连成功后发送，content为发送内容 |
开始交互(开启RTC拉流)
结束交互(结束RTC拉流)
文本驱动
true为等待前面播报后在播报传入text，false为不等待直接打断之前播报
音频流驱动
限制:
· PCM音频原始数据是单通道，音频流数据必须是二进制数组（new Uint8Array类型），且数组长度是偶数
· 采样率必传
Client.talkByArrayBuffer(pcm音频二进制数组, 音频采样率, true)打断当前对话
4.2 AndroidSDK
4.2.1 SDK 获取
4.2.2 接入环境
1.
2.
3.
4.
4.2.3 开发流程及接入示例
1.
2.
sdk为单例模式，销毁前只需要初始化一次，初始化不涉及功能创建
3.
4.
5.
6.
7.
4.2.4 进阶功能
4.2.4.1 播报功能⸺由⽤户指定数字员⼯播报的内容
4.2.4.2 SDK其他开放api
4.2.5 配置&回调类描述
4.2.6 Android端错误码
4.2.6 AndoridSDK注意事项
1.
2.
3.
4.3 IOSSDK
4.3.1 接入准备
sdk获取
接入须知
1.
2.
sdk导入
1.
2.
4.3.2 快速接入
初始化
开始启动交互
交互
结束交互，关闭数字员工
播报功能⸺由⽤户指定数字员⼯播报的内容
1.
4.3.3 其他开放api
获取数字员工当前状态
中断播报
4.3.4 代理
5 交互时序图
6 错误码
//交互过程异常
* 606 获取拉流信息失败
* 607 拉流启动失败
* 608 获取错误信息失败
* 609 获取拉流配置失败
* 611,"资源占用中",
* 612,"FAQ无效消息",
* 613,"无效的请求类型",
* 614,"RTC消息超时",
* 615,"无效的虚拟人资源信息",
* 616,"请求繁忙，请稍后尝试",
* 617,"session未失效，请勿重复申请",
* 618,"虚拟人资源配置错误",
* 619,"用户没有专属机器人",
* 620,"用户没有公共机器人",
* 621,"路数权益不足",
* 622,"JWT认证失败",
// 音频流相关
* 801 sampleRate必传
* 802 二进制数据数组长度必须是偶数
* 803 单次数据不大于2m
//鉴权异常
* 0o10, "signature is required"
//浏览器限制异常
* 16451 浏览器阻止自动播放行为,请引导用户与页面交互后调用startRTC7 其他说明
7.1 常见问题
错误16451，有默认引导弹窗,若想取消弹窗,请引导用户交互后再调用
Client.startRTC()
出于对用户安全、隐私等问题的考虑，浏览器限制网页只有在安全的环境下（例如
https、 localhost、file:// 等协议），才能采集麦克风、摄像头。HTTP 协议是不安全的，浏览器会禁止在 HTTP 协议下采集媒体设备。若您在本地开发测试一切正常，但是页面部署后，却无法正常采集摄像头、麦克风。则请检查您的网页是否部署到了 HTTP 协议上，若是，请使用 HTTPS 部署您的网页，并确保具备合格的 HTTPS 安全证书。
修改于 2025-06-17 07:52:04