客户端渲染 H5 SDK 接口说明

最近更新时间:2024-11-12 11:37:42

我的收藏
说明:
当前版本: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 类型说明

参数名称
必选
类型
说明
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://客户自己的私域域名',
wsOrigin: 'ws://客户自己的私域域名',
});
console.log(result);

init 初始化

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

参数说明

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

Option 类型说明

参数名称
必选
类型
说明
element
Element/String
容器元素对象,或者为找到容器元素的selector,例如“#元素id”
virtualmanProjectId
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”。
如果不指定命名,默认按压缩列表里排序为 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
要播放的文本,支持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, 用来标识是同一个流。
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>
异步返回的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',
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.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模型, 加载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"
}