服务端渲染 H5 SDK 接口说明

最近更新时间:2024-11-11 21:58:52

我的收藏
说明:
当前版本:5.1.2


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 初始化

参数说明

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

Option 类型说明

参数名称
必选
类型
说明
element
Element/String
容器元素对象,或者为找到容器元素的 selector,例如“#元素id”
virtualmanProjectId
String
数智人项目 ID。(原来的virtualmanKey)。参考产品介绍获取密钥。
sign
String
参考产品介绍获取密钥。
如果不设置,必须 setPrivatization 里设置 appKey 和 accessToken。
没 setPrivatization, 且设置了 sign, 为公有云鉴权

示例代码

IVH.init({
sign: 'xxxxxxx',
element: document.querySelector('.video-area'),
virtualmanProjectId: 'xxxxxx',
});

createSession 新建直播会话

参数说明

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

Option 类型说明

参数名称
必选
类型
说明
driverType
Int
数智人驱动方式。
1:纯文本驱动
3:音频驱动(原声),此模式下支持发送音频和文本两种驱动模式
userId
String
用户的唯一标识,由调用方自己维护。以相同的 UserId 创建新流,会导致上一个该 UserId 流关闭。不传会本地生成一个复用
customPlayStreamAddrFunc
Function
用户自定义修改直播拉流URL的函数。
注意:
1. 使用第三方账号下的腾讯云直播服务时请定义此函数。
2. 自定义云直播推流地址时,这里自行设置拉流地址。
protocolOption
ProtocolOption
协议自定义参数, 除了参数名首字母小写, 其他和apaas接口说明 一致

customPlayStreamAddrFunc 函数说明

// 会把请求返回的playStreamAddr信息当参数传入
function customPlayStreamAddrFunc(addr) {
// 自行操作addr信息
const newAddr = custom(addr)
// 一定要有返回,否则会引发后续逻辑错误
return newAddr
}

ProtocolOption类型局部举例

参数名称
必选
类型
说明
cssCustomPushUrl
String
自定义云直播推流地址
...
...
...
...

返回值说明

参数名称
必选
类型
说明
data
Promise<Data/Null>
自定义类型。为 null 时代表失败,请监听 error 事件看具体信息

Data 类型说明

参数名称
必选
类型
说明
sessionId
String
会话的唯一标识
playStreamAddr
String
直播流地址
注意:
自定义云直播推流地址时,拉流地址在customPlayStreamAddrFunc 里自行设置,这里后台接口会返回空。

示例代码

const result = await IVH.createSession();
if (result) {
console.log(result);
}

startSession 开启当前会话

返回值说明

参数名称
必选
类型
说明
data
Promise<Boolean>
true 正常,false 异常,请监听 error 事件看具体信息

示例代码

const result = await IVH.startSession();
console.log(result);

statSession 查询会话状态

参数说明

参数名称
必选
类型
说明
sessionId
String
会话唯一标识

返回值说明

参数名称
必选
类型
说明
data
Promise<Data/Null>
自定义类型。为 null 时代表失败,请监听 error 事件看具体信息

Data 类型说明

参数名称
必选
类型
说明
reqId
String
单次请求唯一标识
sessionStatus
Int
流状态。1:进行中,2:已关闭,3:准备中,4:建流失败
playStreamAddr
String
流播放地址,建流成功后返回
speakStatus
String
数智人状态。Initial:初始状态。
WaitingTextStart:等待文本播报开始。TextStart:文本播报中。
WaitingTextOver:等待文本播报结束。TextOver:文本播报结束。
WaitingAudioStart:等待音频开始播报。AudioStart:音频开始播报。
WaitingAudioOver:等待音频播报结束。AudioOver:音频播报结束。
Error:驱动错误。
isSessionStarted
Boolean
是否已经开启会话,只有开启状态,才可以发送驱动指令。
errorCode
Int
当前状态对应的错误码,0为正常。错误码列表参考
errorMessage
String
当前状态对应的错误信息。
closeType
Int
流退出原因。
1:正常退出
2:超时退出
3:下游退出
4:服务重启关流
5:同 userId 踢除

示例代码

const result = await IVH.statSession('xxxxxx');
if (result) {
console.log(result);
}


closeSession 关闭当前直播会话

返回值说明

参数名称
必选
类型
说明
data
Promise<Boolean>
true 正常,false 异常,请监听 error 事件看具体信息

示例代码

const result = await IVH.closeSession();
console.log(result);

closeSessionBySessionId 关闭指定的流

参数说明

参数名称
必选
类型
说明
sessionId
String
会话唯一标识

返回值说明

参数名称
必选
类型
说明
data
Promise<Boolean>
true 正常,false 异常,请监听 error 事件看具体信息

示例代码

const result = await IVH.closeSessionBySessionId('xxxxxx');
console.log(result);


listSessionOfProjectId 查询数智人项目下的会话列表

参数说明

参数名称
必选
类型
说明
virtualmanProjectId
String
数智人项目 ID,不传默认会用初始化时的 virtualmanProjectId。

返回值说明

参数名称
必选
类型
说明
data
Promise<Data[]>/Null
自定义类型。为 null 时代表失败,请监听 error 事件看具体信息

Data 类型说明

参数名称
必选
类型
说明
userId
String
用户的唯一标识
sessionId
String
会话唯一标识
sessionStatus
Int
流状态。1:进行中,2:已关闭,3:准备中,4:建流失败
playStreamAddr
String
流播放地址,建流成功后返回
driverType
String
数智人类型。1:文本驱动;3:语音驱动(原声)。
isSessionStarted
Boolean
是否已经开启会话,只有开启状态,才可以发送驱动指令。

示例代码

const result = await IVH.listSessionOfProjectId('xxxxxx');
console.log(result);

listSessionOfUin 查询 uin 下的会话列表

返回值说明

参数名称
必选
类型
说明
data
Promise<Data/Null>
自定义类型。为 null 时代表失败,请监听 error 事件看具体信息

Data 类型说明

参数名称
必选
类型
说明
userId
String
用户的唯一标识
sessionId
String
会话唯一标识
sessionStatus
Int
流状态。1:进行中,2:已关闭,3:准备中,4:建流失败
playStreamAddr
String
流播放地址,建流成功后返回
driverType
String
数智人类型。1:文本驱动;3:语音驱动(原声)。
isSessionStarted
Boolean
是否已经开启会话,只有开启状态,才可以发送驱动指令。

示例代码

const result = await IVH.listSessionOfUin();
console.log(result);


play 发送内容

参数说明

command 取值不同,对应参数组合不同。返回内容监听 socket 事件得到
text:文本驱动。
audio:音频驱动。
stream:流式文本驱动。

command=text

参数名称
必选
类型
说明
command
String
text:文本驱动。
data
String
内容字符串
chatCommand
String
对话指令类型 ,当数智人项目绑定对话/大模型 bot 时生效。
NotUseChat:客服 bot 配置不生效,数智人播报发送的内容。
传空或不传:客服 bot 配置生效,数智人播报对应的答案内容。
isNewChat
Boolean
大模型时生效,控制是否开启新轮次对话

command=audio

参数名称
必选
类型
说明
command
String
audio:音频驱动。
data
String
音频原始数据的byte数组,经Base64编码后的字符串。格式:PCM,采样率:16kHz,采样位深:16bits,声道:单声道,传输速率:5120B 160ms
seq
Int
包序号,序号必须从1开始
isFinal
Boolean
是否最后一个音频包,头包和过程包不填采用默认值 false,最后一个音频包填写空串,本字段填写 true,会触发结束音频驱动回到静默态

command=stream

参数名称
必选
类型
说明
command
String
stream:流式文本驱动。
data
String
流式内容
seq
Int
包序号,序号必须从1开始
isFinal
Boolean
默认值 false,代表是否是尾包
smartActionEnabled
Boolean
commad: stream 时有效
是否开启智能动作,缺省值:true。为 true 并且输入的文本或者话术增强后的文本没有动作标签则会生成智能动作。
isSentence
Boolean
commad: stream 时有效
是否是子句模式,缺省值:false。为 true 服务端不会做重新组句。
isInsertSentence
Boolean
commad: stream 时有效
是否是插入的子句,缺省值:false。为 true 并且是子句模式则表示当前分片需要插播。

示例代码

IVH.play({
command: 'text',
data: '现在几点了',
});

IVH.play({
command: 'audio',
data: 'xxxxxx',
seq: 1,
});

IVH.play({
command: 'stream',
data: 'xxxxxx',
seq: 1,
});

stop 打断当前播报

示例代码

IVH.stop();

info 版本信息

返回值说明

参数名称
必选
类型
说明
data
Data
自定义类型

Data 类型说明

参数名称
必选
类型
说明
version
String
版本号

示例代码

IVH.info();

setVolume 设置音量

参数说明

参数名称
必选
类型
说明
val
Number
音量 0 - 1的范围

示例代码

let volume = 1;
document.querySelector('#btn2').onclick = function (e) {
volume = 1 - volume;
IVH.setVolume(volume);
}

事件监听

参数说明

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

可监听的事件列表

事件名
必选
说明
error
有错误发生时触发
canplay
video 的 canplay 事件,受浏览器兼容性影响,看实际需求监听
socket
有 socket 的交互时触发,具体见 附录说明

示例代码

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

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

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

error 事件

回调数据的结构说明
参数名称
必有
类型
说明
code
Int
0为正常,非0为异常
message
String
对应的错误信息说明
path
String
发送请求的 path 信息
requestId
String
请求返回里的 RequestID 信息
sessionId
String
请求返回里的 SessionID 信息
dialogId
String
请求返回里的 DialogID 信息

canplay 事件

回调数据的结构说明
参数名称
必有
类型
说明
code
Int
0为正常,非0为异常
message
String
对应的错误信息说明

socket 事件

回调数据的结构说明(局部)其他字段参考(开头小写)
参数名称
必有
类型
说明
errorCode
Int
0为正常,非0为异常
errorMsg
String
对应的错误信息说明
type
Int
返回的数据类型。1:输入文本。2:播报内容。3:播报状态。4:大模型的答案。5:风险控制提示。7:由于当前播报句不可打断而被遗弃输入文本
speakStatus
String
当 type 为3时有此字段。
Initial:初始状态。
WaitingTextStart:等待文本播报开始。
TextStart:文本播报中。
WaitingTextOver:等待文本播报结束。
TextOver:文本播报结束。
WaitingAudioStart:等待音频开始播报。
AudioStart:音频开始播报。
WaitingAudioOver:等待音频播报结束。
AudioOver:音频播报结束。
SentenceNext:流式的子句模式返回该状态,客户端收到该状态表示可以发送下一条子句。
Error:驱动错误。
uninterrupt
Boolean
true:不可打断,false:可打断。
interruptResult
Int
当 type 为1时有此字段。仅在请求参数 interrupt 为 true 时需要关注此字段。1 - 成功,2 - 失败。
interruptMessage
String
当 type 为1时有此字段。仅在请求参数 interrupt 为 true 且打断失败时需要关注此字段。打断失败的原因。
text
String
当 type 为1、2、7时有此字段。输入文本/播报文本
textDisplay
String
配置端配置的内容,html 语法
textPro
String
TTS 播报的内容,ssml 语法
interactionType
String
客服对话的特殊消息类型,参考下面得客服对话说明
interactionContent
String
客服对话的特殊消息内容,参考同上

附录说明

客服对话

选择题




/*
* 说明:样式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"
}