说明:
当前版本:3.5.9
SDK 包的文件说明
一个 SDK 文件:TXIVHSDK_Web_Client_Vx.x.x_Release.js
一个文件夹unzip (3.4.0+版本才有):内包含 unzip_worker.js,unzip_wasm.js,unzip_wasm_bg.wasm。 用来解压 zip 用的,使用方式具体参考 初始化解压功能。
SDK API 接口/事件的说明
setPrivatization 定制设置
在 init 前设置,设置后在调用 init 方法时可以不传入 sign 参数,如果不设置则必须传入 sign 参数。
注意:私有化部署环境必须设置。
参数说明
参数名称 | 必选 | 类型 | 说明 |
option | 是 | Option | 自定义类型 |
Option 类型说明
返回值说明
参数名称 | 必选 | 类型 | 说明 |
data | 是 | Boolean | true:代表设置成功 false:代表设置失败 |
示例代码
const result = IVH.setPrivatization({appKey: '密钥里的appkey',accessToken: '密钥里的accesstoken',httpOrigin: 'http://客户自己的私域域名',wsOrigin: 'ws://客户自己的私域域名',});console.log(result);
init 初始化
说明:
参数说明
参数名称 | 必选 | 类型 | 说明 |
option | 是 | Option | 自定义类型 |
Option 类型说明
参数名称 | 必选 | 类型 | 说明 |
element | 是 | Element/String | 容器元素对象,或者为找到容器元素的selector,例如“#元素id” |
virtualmanProjectId | 是 | String | |
sign | 否 | String | 如果不设置,必须 setPrivatization 里设置 appKey 和 accessToken。 没 setPrivatization, 且设置了 sign, 为公有云鉴权 |
modelPath | 否 | String | 与 modelData 二选一,优先级低 模型地址, 相对地址/绝对地址都可 说明: |
modelData | 否 | ArrayBuffer | 与 modelPath 二选一,优先级高 模型数据,fetch 获取后,转 arrayBuffer 即可。 |
actionPath | 否 | Array | 与 actionData 二选一,优先级低 动作地址, 相对地址/绝对地址都可 说明: 当传入动作文件的 zip 时,数组里第一个值为 url 链接即可,其他值会忽略 使用zip时 指定静默动作:把zip包里的 “对应动作.json” 改名为“default_action_idle.json”。 如果不指定命名,默认按压缩列表里排序为 defaultActionIdx 的动作为静默动作。 如果不想要静默动作,保证压缩包里没有名为“default_action_idle.json”动作且设置 defaultActionIdx 参数为 -1。 指定开场动作:把zip包里的 “对应动作.json” 改名为“opening_action_once.json”。 如果不想要开场动作,保证压缩包里没有名为“opening_action_once.json”动作且不设置 openingActionIdx 参数。 |
actionData | 否 | Array | 与 actionPath 二选一,优先级高 动作数据 |
defaultActionIdx | 否 | Int | 非zip格式时,指定动作json数组里的下标,会当成静默动作,默认值为0。 不想有静默动作时,defaultActionIdx设置为-1。 注意: 当传入动作 zip 文件时,指定逻辑参考 zip 的相关规则。 |
openingActionIdx | 否 | Int | 非zip格式时,指定动作json数组里的下标,不能和静默动作一样且值有效,会在init后执行一遍该动作。 注意: 当传入动作 zip 文件时,指定逻辑参考zip的相关规则,该参数不设置。 |
modelOption | 否 | ModelOption | 模型渲染参数 |
configPath | 否 | String | 与 configData 二选一,优先级低
配置文件地址,相对地址/绝对地址都可。 注意: 如果下载的模型资产压缩包内有配置文件,请 init 时加载进去。 |
configData | 否 | Object | 与 configPath 二选一,优先级高
json 数据,fetch 获取后,转 json 即可。 注意: 如果下载的模型资产压缩包内有配置文件,请 init 时加载进去。 |
isIntl | 否 | Boolean | 是否是国际版,默认值为false(国内版) 警告: 国内 | 国际版账号和接口不通用,如果不匹配会导致接口异常。 |
ModelOption 类型说明
参数名称 | 必选 | 类型 | 说明 |
mode | 否 | Array<String> | 模式集合 说明: 'position':定位模式,配置后可自由调整位置。
示例: ['position'] |
示例代码
// 路径加载方式IVH.init({element: '#model',virtualmanProjectId: 'xxxxxxxxxxxxxxxxxx',sign: 'xxxxxxxxxxxxxxxxxx',modelPath: `./model/yangxiaoyun/200.glb`,actionPath: [`./model/yangxiaoyun/action/hands_drooping.json`,],defaultActionIdx: 0});// 数据加载方式const option = {modelPath: `./model/yangxiaoyun/200.glb`,actionPath: [`./model/yangxiaoyun/action/welcome.json`,`./model/yangxiaoyun/action/thinking.json`,],};const fetchArr = option.actionPath.map(n => {return fetch(n).then(d => d.json());});Promise.all([fetch(option.modelPath).then(d => d.arrayBuffer())].concat(fetchArr)).then(data => {const opt = {element: '#model',virtualmanProjectId: 'xxxxxxxxxxxxxxxxxx',sign: 'xxxxxxxxxxxxxxxxxx',defaultActionIdx: 0,};opt.modelData = data[0];opt.actionData = [{name: 'welcome',data: data[1],},{name: 'thinking',data: data[2],}];IVH.init(opt);});
加载动作
注意:
要保证再 init 后执行
参数说明
参数名称 | 必选 | 类型 | 说明 |
option | 是 | Option | 自定义类型 |
Option 类型说明
参数名称 | 必选 | 类型 | 说明 |
actionPath | 否 | Array | 与 actionData 二选一,优先级低 动作地址, 相对地址/绝对地址都可 |
actionData | 否 | Array | 与 actionPath 二选一,优先级高 动作数据 |
示例代码
IVH.on('init', e => {console.log('init:', e);IVH.loadAction({actionPath: [`./model/yangxiaoyun/action/welcome.json`,],});});
初始化 AudioContext
示例代码
说明:
由于 iOS 的音频自动播放限制,必须在行为事件的回调里 init :
正确示例,在用户行为事件回调函数的层级里调用 initAudio。
document.querySelector('#btn').onclick = function (e) {IVH.initAudio();const txt = document.querySelector('#txt').value.trim();if (txt) {setTimeout(() => {IVH.play(txt);}, 1000);}}
错误示例,在其他函数层级里initAudio,这时 iOS 系统会认为是非用户行为。
document.querySelector('#btn').onclick = function (e) {const txt = document.querySelector('#txt').value.trim();if (txt) {setTimeout(() => {IVH.initAudio();IVH.play(txt);}, 1000);}}
播报 play
注意:
每次调用前先执行 initAudio
参数说明
参数名称 | 必选 | 类型 | 说明 |
text | 是 | Object | |
option | 是 | Option | 自定义类型 |
Option 类型说明
参数名称 | 必选 | 类型 | 说明 |
isChat | 否 | Boolean | 是否开启对话模式, 默认值是 false, 纯文本驱动 为 true 时, 启动对应的对话模式, 客服对话/大模型 |
isNew | 否 | Boolean | isChat 为 true 时有效 是否属于同一个会话(多轮),会影响多轮会话的结果 |
isStream | 否 | Boolean | isChat 为 false 时有效 为 true 时, 为流式文本驱动。默认值为 false。 警告: 流式文本不支持 SSML 格式 |
seqNo | 否 | Int | isStream 生效时必传 流式文本分片序号, 从1开始计数。 |
isFinal | 否 | Boolean | isStream 生效时必传 流式文本的结束标记(每一段流式文本结束必须传入结束标记)。 |
streamId | 否 | String | isStream 生效时必传 流式文本的请求 Id, 长度为32的 uuid, 用来标识是同一个流。 |
userId | 否 | String | isChat为true时有效,传值时会导致isNew无效,人为标识是否为同一个会话(用于多端查询)。 注意: 大模型对话时客户传入,长度不超过64位的字符串 |
示例代码
document.querySelector('#btn').onclick = function (e) {const txt = document.querySelector('#txt').value.trim();if (txt) {IVH.initAudio();IVH.play(txt, {isChat: true,});}}// 模拟流式接口测试用例, 仅供参考document.querySelector('#btn7').addEventListener('click', e => {const arr = ['今天天气不错,','风和日丽的,','可以出去玩了。'];IVH.initAudio();const streamId = crypto.randomUUID().replace(/-/g, '')for (let i = 0; i < arr.length; i++) {IVH.play(arr[i], {isStream: true,seqNo: i + 1,isFinal: i === arr.length - 1,streamId,})}})
版本信息
返回值
参数名称 | 必选 | 类型 | 说明 |
result | 是 | Object | 一个json对象, 里面还有版本信息对象 |
{version: '1.0.0'}
示例代码
/*** @returns Object* * @property {String} version:版本信息,例如:'1.0.0'*/IVH.info()
设置音量
参数说明
参数名称 | 必选 | 类型 | 说明 |
val | 是 | Number | 音量 0-1的范围 |
示例代码
let volume = 1;document.querySelector('#btn2').onclick = function (e) {volume = 1 - volume;IVH.setVolume(volume);}
打断播报
示例代码
document.querySelector('#btn3').onclick = function (e) {IVH.stop();}
获取指令配置
版本3.1.0+支持
参数说明
参数名称 | 必选 | 类型 | 说明 |
key | 是 | String | 指令key, 根据它获取已经配置好的指令信息 |
返回值
参数名称 | 必选 | 类型 | 说明 |
result | 是 | Promise<Object> |
示例代码
const result = await IVH.getActionConfig('xxx');console.log(result);
获取配置信息
版本3.2.0+支持
返回值
参数名称 | 必选 | 类型 | 说明 |
result | 是 | Object | 返回一个json数据,一般在调整模型位置后,存成conf.json,下次init时加载,可调整模型的初始位置。 |
示例代码
const result = IVH.getConf();console.log(result);
重置位置信息
版本3.2.0+支持,如果init时有自定义位置,调用此方法可reset。
示例代码
IVH.resetPositionInfo();
销毁
版本3.3.0+支持,用来销毁实例释放内存占用。
注意:
destroy后想要再次渲染需要重新init对应方法。
示例代码
IVH.destroy();
初始化解压功能
版本3.4.0+支持,初始化后模型和动作文件可以传入zip文件,减少网络请求时间。
注意:
只支持zip文件,Deflated压缩算法。
移动端系统 IOS 11.0+,Android 7.0+支持。
参数说明
参数名称 | 必选 | 类型 | 说明 |
option | 是 | Option | 自定义类型 |
Option类型说明
参数名称 | 必选 | 类型 | 说明 |
path | 是 | String | 解压相关文件所在的文件路径。 解压相关文件有三个,分别是unzip_worker.js,unzip_wasm.js,unzip_wasm_bg.wasm。把它们放在同一个文件夹里,然后把路径传给path。例如: http://xxx.com/unzip/ 或者是相对路径 ./unzip/之类的。 |
返回值
参数名称 | 必选 | 类型 | 说明 |
result | 是 | Promise<Boolean> | 异步返回的Boolean,true成功/fasle失败,失败时error事件里会有相关错误信息。 |
示例代码
// 需要保证initUnzip返回true,才可传入zip链接。(async () => {const result = await IVH.initUnzip({path: './unzip'});result && IVH.init({element: '#xxxx',sign: 'xxxxx',virtualmanProjectId: 'xxxxx',modelPath: './model/model.zip',// 动作文件的zip,只看数组里一个url链接,后续值会忽略。使用zip时指定静默动作,是把zip包里的”对应动作.json“改名为”default_action_idle.json“,系统会把这个命名的动作当作静默。actionPath: ['./model/action.zip',],});})();
加载组件数据
版本3.5.0+支持,模型init和initUnzip后,可以加载组件数据(例如: 带道具模型的配套动作)。
参数说明
参数名称 | 必选 | 类型 | 说明 |
option | 是 | Option | 自定义类型 |
Option类型说明
参数名称 | 必选 | 类型 | 说明 |
zipPath | 是 | String | 组件压缩文件所在的文件路径。 由于道具配套动作相关文件较多,缺失可能会引发后续异常,所以加载时会做文件校验。 如异常会在error事件里返回相关异常信息;如成功会在actionLoad事件中返回相关加载信息。 |
示例代码
// 需要保证init和initUnzip都已初始化完毕(async () => {const result = await IVH.initUnzip({path: './unzip'});IVH.on('init', e => {IVH.loadComponent({zipPath: './model/aiyun/aiyun.zip',})});result && IVH.init({element: '#xxxx',sign: 'xxxxx',virtualmanProjectId: 'xxxxx',modelPath: './model/model.zip',// 当传入动作文件的zip时,数组里第一个值为url链接即可,其他值会忽略actionPath: ['./model/action.zip',],});})();
事件监听
参数说明
参数名称 | 必选 | 类型 | 说明 |
event | 是 | String | 事件名 |
callback | 否 | Function | 回调函数 |
可监听的事件列表(参数event的可选取值)
事件名 | 必选 | 说明 |
error | 否 | 有错误发生时触发,回调函数会返回信息对象,可查看message属性获知具体错误信息。 |
init | 否 | 模型初始化完毕后触发,回调函数会返回信息对象 |
actionLoad | 否 | 动作数据加载后触发,回调函数会返回信息对象 |
actionEnd | 否 | 动作执行完毕后触发,回调函数会返回信息对象 |
play | 否 | TTS语音播完后触发,回调函数会返回信息对象 |
nlp | 否 | 对话的返回结果,用于富文本的展示 |
sentence | 否 | 大模型模式下的分句播报信息,回调函数会返回信息对象 seqNo 对应 nlp 事件里返回的 seqNo status 播放状态: start 开始/over 结束 |
示例代码
IVH.on('error', e => {console.log('error:', e.code, e.message);});IVH.on('init', e => {console.log('init:', e.code, e.message);});
指引
两个模型切换,来达成换装效果
示例代码
// 先初始化A服饰模型IVH.init({element: '#model',virtualmanProjectId: 'xxxxxxxxxxxxxxxxxx',sign: 'xxxxxxxxxxxxxxxxxx',modelPath: `./model/modelA.glb`,actionPath: [`./model/actionA/xxxx.json`,]});// 当要切换时,销毁之前的A服饰模型IVH.destroy();// 重新初始化B服饰模型IVH.init({element: '#model',virtualmanProjectId: 'xxxxxxxxxxxxxxxxxx',sign: 'xxxxxxxxxxxxxxxxxx',modelPath: `./model/modelB.glb`,actionPath: [`./model/actionB/xxxx.json`,]});
如何调整模型的起始位置和大小
示例代码
// 1、先初始化, 打开定位模式IVH.init({element: '#model',virtualmanProjectId: 'xxxxxxxxxxxxxxxxxx',sign: 'xxxxxxxxxxxxxxxxxx',modelPath: `./model/model.glb`,actionPath: [`./model/action/xxxx.json`,],modelOption: {mode: ['position']}});// 2、可以鼠标滚轮放缩模型大小, 鼠标右键拖拽模型位置, 确认好后调用getConf保存为conf.jsongetConf.addEventListener('click', e => {const blob = new Blob([JSON.stringify(IVH.getConf())], { type: 'application/json' });// 下载的文件名const filename = 'conf.json';// 创建隐藏的可下载链接const eleLink = document.createElement('a');eleLink.download = filename;eleLink.style.display = 'none';// 下载内容转变成blob地址eleLink.href = URL.createObjectURL(blob);// 触发点击document.body.appendChild(eleLink);eleLink.click();// 然后移除document.body.removeChild(eleLink);URL.revokeObjectURL(eleLink.href);});// 3、重新init模型, 加载configPath/configData, 模型会按照之前保存的信息渲染IVH.init({element: '#model',virtualmanProjectId: 'xxxxxxxxxxxxxxxxxx',sign: 'xxxxxxxxxxxxxxxxxx',modelPath: `./model/model.glb`,actionPath: [`./model/action/xxxx.json`,],configPath: './model/conf.json',});
附录说明
大模型
nlp事件返回数据的关键字段说明
属性名 | 说明 |
replyType | cloudAiGpt:腾讯云大模型对话 yunxiaowei:云小微客服 cloudAiWaiting: 首包超时等待话术 cloudAiTimeOut: 超时未返回话术,会话结束 sensitive:敏感内容固定话术 input:纯文本输入或流式文本输入的内容 enhanceText:纯文本驱动匹配上了话术管理中的内容 |
cloudAiExtra | JSON文本格式的字符串,大模型的额外补充字段。 replyType=cloudAiGpt,isFinal=true时有值 |
record_id | cloudAiExtra 的属性,消息ID |
-- references | |
seqNo | 子句序号 |
isFinal | 是否是最后一句 |
isHighLight | 高亮标识 |
contentType | md 格式时的类型 0:未知 1:普通字符串 2:有序列表 3:无序列表 4:图片链接 5:HTTP 链接 6:表格 7:代码块 |
客服对话
nlp事件返回数据的关键字段说明 (2.3.1及以后版本统一为小写开头)
属性名 | 说明 |
replyDisplay | 配置端配置的内容,html 语法 |
replyPro | TTS 播报的内容,ssml 语法 |
interactionType | 特殊消息类型,参考下面得特殊消息说明 |
interactionContent | 特殊消息内容,参考同上 |
特殊消息说明
通过腾讯云智能数智人话术管理模块,可针对不同的回复语配置特殊消息类型,可辅助集成方快速配置特殊消息内容,以下为实现前端特殊消息类型代码示例,SDK 本身不包含前端交互样式。
注意:
SDK 本身不包含前端交互样式,如需使用特殊消息类型,需集成方进行代码开发。
选择题
/** 说明:样式1:style=1;样式2:style=2;样式3:style=3;*/{InteractionContent: "{\\"style\\":1,\\"options\\":[\\"选项1\\",\\"选项2\\",\\"选项3\\"]}",InteractionType: "OptionInfo"}
图片
{InteractionContent: "{\\"url\\":\\"https://virtualhuman-cos-test-1251316161.cos.ap-nanjing.myqcloud.com/virtualman-config/0cbb2231-1afd-4cd5-8414-b1bc3d600a2f-王冰冰.png\\"}",InteractionType: "Image"}
弹窗
{InteractionContent: "{\\"title\\":\\"这是弹窗标题\\",\\"content\\":\\"这是弹窗内容\\",\\"button\\":\\"这是弹窗按钮\\"}",InteractionType: "Popup"}
视频
{InteractionContent: "{\\"url\\":\\"https://virtualhuman-cos-test-1251316161.cos.ap-nanjing.myqcloud.com/virtualman-config/0417e732-1d64-4c65-a2c4-cac23ed454e2-1cd396fb-86a9-480f-814f-cbdf14055cdd.mp4\\"}",InteractionType: "Video"}
图片 + 选择题
/** 说明:样式1:style=1;样式2:style=2;样式3:style=3;*/{InteractionContent: "{\\"url\\":\\"https://virtualhuman-cos-test-1251316161.cos.ap-nanjing.myqcloud.com/virtualman-config/22f4c069-cddb-4753-b482-02a20755b2ba-王冰冰.png\\",\\"style\\":1,\\"options\\":[\\"选项1\\",\\"选项2\\"]}",InteractionType: "ImageOption"}
自定义
{InteractionContent: "{\\"name\\":\\"这是标题\\",\\"contents\\":[\\"这里是内容\\"]}",InteractionType: "Customize"}