tencent cloud

文档反馈

客户端渲染 H5 SDK 接口说明

最后更新时间:2024-11-07 09:44:13
    说明:
    当前版本:3.5.6

    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://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”
    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“即可。
    设置开场动作:是把zip包里的”对应动作.json“改名为”opening_action_once.json“即可。
    actionData
    Array
    与 actionPath 二选一,优先级高
    动作数据
    defaultActionIdx
    Int
    动作数组里的下标,会当成静默动作, 默认值为0
    注意:
    当传入动作 zip 文件时,该参数不生效。
    openingActionIdx
    Int
    动作数组里的下标,不能和静默动作一样且值有效,会在init后执行一遍
    注意:
    当传入动作 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
    回调函数

    可监听的事件列表

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

    示例代码

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

    指引

    两个模型切换,来达成换装效果

    示例代码

    // 先初始化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"
    }

    

    联系我们

    联系我们,为您的业务提供专属服务。

    技术支持

    如果你想寻求进一步的帮助,通过工单与我们进行联络。我们提供7x24的工单服务。

    7x24 电话支持