客户端渲染H5 SDK接口说明

最近更新时间:2024-08-13 15:53:01

我的收藏

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 用的,使用方式具体参考 初始化解压功能
一个 pdf 版本的使用文档

SDK API接口/事件的说明

setPrivatization 定制设置

在 init 前设置,设置后在调用 init 方法时可以不传入 sign 参数,如果不设置则必须传入 sign 参数。
注意:私有化部署环境必须设置。

参数说明

参数名称
必选
类型
说明
option
Option
自定义类型

Option 类型说明

参数名称
必选
类型
说明
appKey
String
参考产品介绍获取密钥,设置后本地鉴权
accessToken
String
参考产品介绍获取密钥,设置后本地鉴权
httpOrigin
String
可选配置,优先级高,设置后 HTTP 请求都按这个 origin 设置,不设置时请求公有云地址
wsOrigin
String
可选配置,优先级高,设置后 socket 请求都按这个 origin 设置,不设置时请求公有云地址

返回值说明

参数名称
必选
类型
说明
data
Boolean
true:代表设置成功
false:代表设置失败

示例代码

const result = IVH.setPrivatization({
appKey: '密钥里的appkey',
accessToken: '密钥里的accesstoken',
httpOrigin: 'http://www.test.com',
wsOrigin: 'ws://www.test.com',
});
console.log(result);

init 初始化

说明:
3.4.0+版本支持传入zip文件路径,具体参考 初始化解压功能(需要 initUnzip 后才可以传入 zip 文件路径),可减少网络加载文件的时间。

参数说明

参数名称
必选
类型
说明
option
Option
自定义类型

Option 类型说明

参数名称
必选
类型
说明
element
Element/String
容器元素对象,或者为找到容器元素的selector,例如“#元素id”
virtualmanKey
String
参考使用流程
sign
String
参考产品介绍
如果不设置,必须 setPrivatization 里设置 appKey 和 accessToken。
没 setPrivatization, 且设置了 sign, 为公有云鉴权
modelPath
String
与 modelData 二选一,优先级低
模型地址, 相对地址/绝对地址都可
说明:
可支持 zip 链接,参考 初始化解压功能
modelData
ArrayBuffer
与 modelPath 二选一,优先级高
模型数据,fetch 获取后,转 arrayBuffer 即可。
actionPath
Array
与 actionData 二选一,优先级低
动作地址, 相对地址/绝对地址都可
说明:
可支持zip链接,参考 初始化解压功能
当传入动作文件的 zip 时,数组里第一个值为url链接即可,其他值会忽略
使用zip时指定静默动作,是把zip包里的”对应动作.json“改名为”default_action_idle.json“,系统会把这个命名的动作当作静默
actionData
Array
与 actionPath 二选一,优先级高
动作数据
defaultActionIdx
Int
动作数组里的下标,会当成静默动作, 默认值为0
注意:
当传入动作 zip 文件时,该参数不生效。
使用zip时指定静默动作,是把zip包里的”对应动作.json“改名为”default_action_idle.json“,系统会把这个命名的动作当作静默。
openingActionIdx
Int
动作数组里的下标,不能和静默动作一样且值有效,会在init后执行一遍
skinMap
Object
具体结构可参考换肤接口说明
modelOption
ModelOption
模型渲染参数
confPath
String
与 confData 二选一,优先级低 配置文件地址,相对地址/绝对地址都可。
注意:
如果下载的模型资产压缩包内有 conf.json,请 init 时加载进去。
confData
Object
与 confPath 二选一,优先级高 json 数据,fetch 获取后,转 json 即可。
注意:
如果下载的模型资产压缩包内有 conf.json,请 init 时加载进去。

ModelOption 类型说明

参数名称
必选
类型
说明
mode
Array<String>
模式集合
说明:
'position':定位模式,配置后可自由调整位置。 示例: ['position']

示例代码

// 路径加载方式
IVH.init({
element: '#model',
virtualmanKey: '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',
virtualmanKey: '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
要播放的文本,支持SSML规范。(纯动作标签只支持单动作)
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, 用来标识是同一个流。

示例代码

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();
}

换皮肤纹理

版本2.3.0+支持

前置条件

在 init 时,需要增加 skinMap 属性,皮肤纹理名为空字符时,会替换回模型的原皮肤纹理。
IVH.init({
...
skinMap: {
"皮肤名": {
"data": [
{
"name": "纹理名称,具体名称会跟进模型而变化",
"url": "纹理文件的相对/绝对地址",
},
...
]
},
"皮肤名2": {
"data": [
{
"name": "纹理名称,具体名称会跟进模型而变化",
"url": "纹理文件的相对/绝对地址",
},
...
]
},
...
}
})

参数说明

参数名称
必选
类型
说明
name
String
皮肤名, 为空字符时,会替换回模型的原皮肤

示例代码

IVH.reskin('皮肤名');

获取指令配置

版本3.1.0+支持

参数说明

参数名称
必选
类型
说明
key
String
指令key, 根据它获取已经配置好的指令信息

返回值

参数名称
必选
类型
说明
result
Promise<Object>
异步返回的json对象, 关键字段参考 附录说明

示例代码

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',
virtualmanKey: 'xxxxx',
modelPath: './model/model.zip',
// 动作文件的zip,只看数组里一个url链接,后续值会忽略。使用zip时指定静默动作,是把zip包里的”对应动作.json“改名为”default_action_idle.json“,系统会把这个命名的动作当作静默。
actionPath: [
'./model/action.zip',
],
});
})();

事件监听

参数说明

参数名称
必选
类型
说明
event
String
事件名
callback
Function
回调函数

可监听的事件列表

事件名
必选
说明
error
有错误发生时触发
init
模型初始化完毕后触发
actionLoad
动作数据加载后触发
actionEnd
动作执行完毕后触发
play
TTS语音播完后触发
reskinEnd
换肤事件, 换肤结束后/异常时触发
nlp
对话的返回结果,用于富文本的展示
具体说明参考 附录说明
sentence
大模型模式下的分句播报信息
seqNo 对应 nlp 事件里返回的 seqNo,status 播放状态: start 开始/over 结束

示例代码

IVH.on('init', e => {
console.log('init:', e);
});

指引

如何调整模型的起始位置和大小

示例代码

// 1、先初始化, 打开定位模式
IVH.init({
element: '#model',
virtualmanKey: 'xxxxxxxxxxxxxxxxxx',
sign: 'xxxxxxxxxxxxxxxxxx',
modelPath: `./model/model.glb`,
actionPath: [
`./model/action/xxxx.json`,
],
modelOption: {
mode: ['position']
}
});

// 2、可以鼠标滚轮放缩模型大小, 鼠标右键拖拽模型位置, 确认好后调用getConf保存为conf.json
getConf.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模型, 加载confPath/confData, 模型会按照之前保存的信息渲染
IVH.init({
element: '#model',
virtualmanKey: 'xxxxxxxxxxxxxxxxxx',
sign: 'xxxxxxxxxxxxxxxxxx',
modelPath: `./model/model.glb`,
actionPath: [
`./model/action/xxxx.json`,
],
confPath: './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"
}