主入口(HwICSUiSdk)
本节介绍Web SDK的接口详情。
接口 |
描述 |
三方驱动场景(是否支持) |
非三方驱动场景(是否支持) |
---|---|---|---|
获取当前生效的交互模式(语音问答/文本问答)。 |
× |
√ |
|
回调注册。 |
√ |
√ |
|
设置交互任务语言。 |
× |
√ |
|
检查浏览器是否支持。 |
√ |
√ |
|
创建交互任务。 |
√ |
√ |
|
销毁交互任务。 |
√ |
√ |
|
获取交互任务信息。 |
√ |
√ |
|
获取交互任务多语言信息。 |
× |
√ |
|
初始化语音唤醒资源,不使用语音唤醒能力则忽略该接口。 |
× |
√ |
|
切换交互模式(语音问答/文本问答)。 |
× |
√ |
|
中断数字人讲话。 |
× |
√ |
|
数字人静音。 |
√ |
√ |
|
播放数字人音视频。 |
√ |
√ |
|
发送智能交互数字人主动播报的文本信息。 |
× |
√ |
|
发送问题文本。 |
× |
√ |
|
更新配置项。 |
√ |
√ |
|
设置日志级别。 |
√ |
√ |
|
设置第三方配置。 |
× |
√ |
|
开始对话。 |
× |
√ |
|
开始录制用户讲话声音。 |
× |
√ |
|
用户开始提问。 |
× |
√ |
|
结束对话。 |
× |
√ |
|
结束录制用户讲话声音,并弹框提示或自动保存pcm格式录音文件。 |
× |
√ |
|
用户停止提问(注:此处只是停止ASR接收用户语音,对话仍处于激活态)。 |
× |
√ |
|
数字人取消静音。 |
√ |
√ |
activeInteractionMode
(static) activeInteractionMode(): Promise<InteractionModeResult>
【功能说明】
获取当前生效的交互模式(语音问答/文本问答)。
【请求参数】
无。
【返回参数】
参数 |
类型 |
描述 |
---|---|---|
result |
boolean |
执行结果。 |
errorCode |
string | undefined |
错误码,详细见表1。 |
errorMsg |
string | undefined |
错误信息。 |
interactionMode |
'AUDIO' | 'TEXT' |
交互模式。 |
【代码示例】
const { result, interactionMode } = await HwICSUiSdk.activeInteractionMode();
addEventListeners
(static) addEventListeners(eventMap: EventMap): void
【功能说明】
设置事件回调。
【请求参数】
参数 |
是否必须 |
默认值 |
类型 |
描述 |
---|---|---|---|---|
eventMap |
是 |
- |
EventMap |
事件注册Map,请参见表4。 |
参数 |
是否必须 |
默认值 |
类型 |
描述 |
---|---|---|---|---|
error |
否 |
- |
(icsError: IcsError) => any |
错误事件。 |
jobInfoChange |
否 |
- |
(jobInfo: JobInfo) => any |
交互任务信息变更事件。 |
speakingStart |
否 |
- |
() => any |
数字人开始讲话事件。 |
speakingStop |
否 |
- |
() => any |
数字人结束讲话事件。 |
speechRecognized |
否 |
- |
(question: SpeechRecognitionInfo) => any |
语音识别结果。 |
semanticRecognized |
否 |
- |
(answer: SemanticRecognitionInfo) => any |
语义识别结果。 |
enterActive |
否 |
- |
() => any |
数字人激活事件。 |
enterSleep |
否 |
- |
() => any |
数字人自动休眠事件。 |
【返回参数】
无
【代码示例】
HwICSUiSdk.addEventListeners({
error: (icsError) => {
console.error('icsError', icsError);
},
jobInfoChange: (jobInfo) => {
console.info('jobInfoChange', jobInfo);
}
});
changeLanguage
(static) changeLanguage(param: ChangeParam): Promise<void>
【功能说明】
设置交互任务语言。
【请求参数】
参数 |
是否必选 |
默认值 |
类型 |
描述 |
---|---|---|---|---|
param |
是 |
- |
ChangeParam |
语言选项,请参见表6。 |
【返回参数】
请参见表26。
【代码示例】
const { result } = await HwICSUiSdk.changeLanguage({
langCode: 'zh_CN',
});
checkBrowserSupport
(static) checkBrowserSupport(): Promise<boolean>
【功能说明】
检查当前浏览器是否支持运行SDK。
【请求参数】
无
【返回参数】
Promise<boolean>:当前浏览器是否支持运行SDK。
【代码示例】
1 2 3 4 5 6 |
const result = await HwICSUiSdk.checkBrowserSupport();
if (result) {
// 支持
} else {
// 不支持
}
|
create
(static) create(param: CreateParam): Promise<void>
【功能说明】
通过获取的任务链接和一次性鉴权码,创建智能交互任务。
【请求参数】
参数 |
是否必选 |
默认值 |
类型 |
描述 |
---|---|---|---|---|
param |
是 |
- |
CreateParam |
创建活动选项,请参见表8。 |
参数 |
是否必选 |
默认值 |
类型 |
描述 |
---|---|---|---|---|
onceCode |
是 |
- |
string |
一次性鉴权码,获取方式请参见创建一次性鉴权码。 须知:CreateOnceCode接口需要在后台调用,不能在浏览器直接调用,否则有跨域问题。 |
serverAddress |
是 |
- |
string |
智能交互服务端地址。 不同Region的取值如下所示:
|
robotId |
否 |
- |
string |
智能交互活动ID,为参数“taskUrl”取值URL中携带的robot_id参数的值。 示例,如果URL为“https://metastudio-api.cn-north-4.myhuaweicloud.com/icswebclient?robot_id=a1b2c3d4e5f6”,则robotId值为a1b2c3d4e5f6。 注意:robotId和taskUrl必须至少设置一个参数。 |
taskUrl |
否 |
- |
string |
在MetaStudio控制台创建生成的数字人互动任务页面URL。URL获取方式,请参见创建智能交互数字人。 注意:robotId和taskUrl必须至少设置一个参数。 |
containerId |
是 |
- |
string |
渲染SDK交互界面UI的DOM节点ID。 |
config |
否 |
- |
ConfigMap |
配置信息,请参见表18。 |
eventListeners |
否 |
- |
EventMap |
事件注册Map,请参见表4。 第三方驱动的智能交互场景,必须传本参数。 |
logLevel |
否 |
info |
string |
日志级别。 取值如下所示:
|
extendParamStr |
否 |
'' |
string |
扩展参数,按照Json字符串格式携带。比如: '{"client_id":"2134","city":"city","extra_json_param":"{\\"param1\\":\\"value1\\",\\"param2\\":\\"value2\\"}"}' |
【返回参数】
无
【代码示例】
HwICSUiSdk.create({
serverAddress: 'serverAddress',
onceCode: 'onceCode',
robotId: 'robotId',
containerId: 'ics-root',
logLevel: 'debug',
config: {
enableCaption: true,
enableChatBtn: false
},
eventListeners: {
error: (error) => {
console.error('sdk error', {
message: error.message,
code: error.code,
}, error);
}
}
});
destroy
(static) destroy(): Promise<void>
【功能说明】
销毁交互任务。
【请求参数】
无
【返回参数】
无
【代码示例】
HwICSUiSdk.destroy();
getJobInfo
(static) getJobInfo(): Promise<JobInfo>
【功能说明】
获取交互任务信息。
【请求参数】
无
【返回参数】
参数 |
类型 |
描述 |
---|---|---|
jobId |
string |
任务ID。 |
websocketAddr |
string | undefined |
智能交互服务端websocket地址,三方驱动场景用来拼接websocket链接。 参数返回的地址默认无wss://前缀,实际使用时,需要补齐前缀。示例:如果返回字段内容为metastudio-api.cn-north-4.myhuaweicloud.com:443,则需要拼接为wss://metastudio-api.cn-north-4.myhuaweicloud.com:443。 |
【代码示例】
const jobInfo = await HwICSUiSdk.getJobInfo();
getLanguageInfo
(static) getLanguageInfo(): Promise<LanguageResult>
【功能说明】
获取交互任务多语言信息。如需实现多语言能力,需要在后台创建智能交互活动页面,配置多种语言,目前支持中文和英文两种语言。
【请求参数】
无
【返回参数】
参数 |
类型 |
描述 |
---|---|---|
languageList |
语言列表。 |
|
currentLanguage |
'zh_CN' | 'en_US' |
当前交互任务语言值。 |
result |
boolean |
执行结果。 |
errorCode |
string | undefined |
错误码,详细见表1。 |
errorMsg |
string | undefined |
错误信息。 |
参数 |
类型 |
描述 |
---|---|---|
language |
'zh_CN' | 'en_US' |
语言。 |
language_desc |
string |
语言描述。 |
isDefault |
boolean |
是否为默认语言。 |
【代码示例】
const languageResult = await HwICSUiSdk.getLanguageInfo();
initResourcePath
(static) interactionModeSwitch(param: ResourcePath): Promise<void>
【功能说明】
初始化语音唤醒资源,不使用语音唤醒能力则忽略该接口。
- 3.0.1版本之后的websdk包中有如下两个资源文件,如果不使用语音唤醒,可忽略这两个文件。
- wasmData.js:语音唤醒的算法资源文件。
- modelData.js:语音唤醒的模型资源文件。
- 4.0.0版本及之后的websdk支持worker线程开启语音唤醒能力,可通过useWorker参数启用。
- SDK内置默认唤醒模型,支持定制唤醒词,并更新本地模型,详见Web语音唤醒。
【请求参数】
参数 |
是否必选 |
默认值 |
类型 |
描述 |
---|---|---|---|---|
wasmPath |
是 |
'wasmData.js' |
string |
唤醒算法资源文件的相对路径或者绝对路径。
须知:如果useWorker设置为true,则需要传入绝对路径。 |
dataPath |
是 |
'modelData.js' |
string |
唤醒模型资源文件的相对路径或者绝对路径。
须知:如果useWorker设置为true,则需要传入绝对路径。 |
initModel |
否 |
true |
boolean |
是否直接初始化唤醒模型。 初始化唤醒模型需要2~3s的加载时间,这段时间无法进行其他操作,所以需要根据实际情况选择模型初始化的时间点,详细说明如下所示:
|
useWorker |
否 |
false |
boolean |
是否开启语音唤醒worker线程能力。
须知:如果开启此开关,参数wasmPath、dataPath均需传入绝对路径,不支持传入相对路径。 |
【返回参数】
无。
【代码示例】
await HwICSUiSdk.initResourcePath({
wasmPath: 'wasmData.js',
dataPath: 'modelData.js',
initModel: true,
});
注意:如果未设置wasmPath和dataPath或设置的不对,会报类似下面的异常。
此时语音唤醒是无法正常使用的,需要将路径设置为正确的才行。

interactionModeSwitch
(static) interactionModeSwitch(param: InteractionModeParam): Promise<InteractionModeResult>
【功能说明】
切换交互模式(语音问答/文本问答)。
【请求参数】
参数 |
是否必须 |
默认值 |
类型 |
描述 |
---|---|---|---|---|
interactionMode |
否 |
AUDIO |
|
交互模式,语音交互还是文本交互。 |
【返回参数】
见:表2
【代码示例】
const { result } = await HwICSUiSdk.interactionModeSwitch({ interactionMode: 'AUDIO' });
interruptSpeaking
(static) interruptSpeaking(): Promise<UISdkResult>
【功能说明】
中断数字人讲话。
【请求参数】
无
【返回参数】
请参见表26。
【代码示例】
const { result } = await HwICSUiSdk.interruptSpeaking();
muteRemoteAudio
(static) muteRemoteAudio(): Promise<boolean>
【功能说明】
数字人静音。
【请求参数】
无
【返回参数】
Promise<boolean>:数字人静音是否成功。
【代码示例】
const result = await HwICSUiSdk.muteRemoteAudio();
playRemoteVideo
(static) playRemoteVideo(): Promise<UISdkResult>
【功能说明】
播放数字人音视频。跟开关参数“autoPlayRemoteVideo”配合使用,当create接口中参数config的autoPlayRemoteVideo属性设置为false,则需要调用该接口主动播放数字人音视频。
【请求参数】
无
【返回参数】
请参见表26。
【代码示例】
const { result } = await HwICSUiSdk.playRemoteVideo();
sendDrivenText
(static) sendDrivenText(param: TextDrivenParam): Promise<ChatResult>
【功能说明】
发送智能交互数字人主动播报的文本信息。
注意:主动播报结束时的最后一次调用,一定要传“isLast:true”参数,否则数字人讲话结束时无法及时收到speakingStop通知。
【请求参数】
参数 |
是否必须 |
默认值 |
类型 |
描述 |
---|---|---|---|---|
text |
是 |
"" |
string |
智能交互数字人主动播报的文本信息。 |
isLast |
否 |
false |
boolean |
是否是最后一条。 |
【返回参数】
请参见表24。
【代码示例】
const { result } = await HwICSUiSdk.sendDrivenText({ text: '你好', isLast: true });
sendTextQuestion
(static) sendTextQuestion(param: TextQuestionParam): Promise<TextQuestionResult>
【功能说明】
发送问题文本。
【请求参数】
参数 |
是否必须 |
默认值 |
类型 |
描述 |
---|---|---|---|---|
text |
是 |
- |
string |
问题文本。 |
【返回参数】
参数 |
类型 |
描述 |
---|---|---|
result |
boolean |
执行结果。 |
errorCode |
string | undefined |
错误码,详细见表1。 |
errorMsg |
string | undefined |
错误信息。 |
chatId |
string |
对话id。 |
【代码示例】
const { result } = await HwICSUiSdk.sendTextQuestion({ text: '你是谁' });
setConfig
(static) setConfig(config: ConfigMap): void
【功能说明】
设置配置项,用于控制是否显示字幕或交互按钮。
【请求参数】
参数 |
是否必须 |
默认值 |
类型 |
描述 |
---|---|---|---|---|
config |
是 |
- |
ConfigMap |
配置信息,请参见表18。 |
参数 |
是否必须 |
默认值 |
类型 |
描述 |
---|---|---|---|---|
enableCaption |
否 |
false |
boolean |
是否显示字幕。 |
enableChatBtn |
否 |
false |
boolean |
是否显示交互按钮。 |
enableHotIssues |
否 |
false |
boolean |
是否显示热点问题。 |
enableWeakErrorInfo |
否 |
true |
boolean |
是否显示弱提示。 示例:SDK内部websocket异常提示。 |
enableBusinessTrack |
否 |
true |
boolean |
是否上报SDK埋点数据。 |
enableJobCache |
否 |
true |
boolean |
是否启用任务缓存。如果用户希望每次修改任务配置后能快速生效,可不启用缓存。
|
useDefaultBackground |
否 |
true |
boolean |
是否使用默认背景图。 |
enableLocalWakeup |
否 |
false |
boolean |
是否启用语音唤醒能力。如果启用,需要先调用initResourcePath接口初始化唤醒资源路径,再调用create接口创建数字人。否则可能会因为语音唤醒算法加载失败或模型加载失败,导致语音唤醒功能不可用。 |
firstCreateLocalStream |
否 |
false |
boolean |
是否优先创建本地流。解决某些Android设备在听筒模式下,数字人播放声音小的问题。 |
enableMediaViewer |
否 |
true |
boolean |
是否启用图片预览。支持鼠标单击默认对话列表中的图片,实现放大查看功能。 如无需该功能, 可设置为false关闭。 |
autoPlayRemoteVideo |
否 |
true |
boolean |
是否自动播放数字人音视频。跟接口playRemoteVideo配套使用,当前参数设置为false后,可以自行控制数字人音视频播放的时机。 |
enableCollectAudioDemand |
否 |
false |
boolean |
是否按需采集麦克风声音。
开启相比关闭,拾音工作区间最小化。但是开启后,每次重新开始对话,需要重新拾音,会有一些时耗。 注:若使用语音唤醒能力,且开启当前开关时,会一直采集麦克风声音,则该开关不生效。 |
enableOriginCutAlgorithm |
否 |
false |
boolean |
是否使用原来的透明背景模式。3.3.0版本优化了透明背景的算法,如果发现没之前版本的效果好,可以通过此开关设置使用原版本的透明背景算法,保持原有效果。 |
enableVerbatim |
否 |
false |
boolean |
是否开启默认字幕逐字显示效果。该开关需要在enableCaption设置为true,即开启默认字幕时生效。
|
【返回参数】
无
【代码示例】
HwICSUiSdk.setConfig({
enableCaption: true,
enableChatBtn: false,
enableHotIssues: false,
enableWeakErrorInfo: true,
});
setLogLevel
(static) setLogLevel(logLevel: 'debug' | 'info' | 'warn' | 'error' | 'none'): void
【功能说明】
设置输出日志的级别。
【请求参数】
参数 |
是否必须 |
默认值 |
类型 |
描述 |
---|---|---|---|---|
logLevel |
是 |
info |
|
日志级别。 |
【返回参数】
无
【代码示例】
HwICSUiSdk.setLogLevel('warn');
setThirdPartyConfig
(static) setThirdPartyConfig(param: ThirdPartyParam): Promise<void>
【功能说明】
设置第三方配置。支持通过配置接入声影降噪设备。声影降噪设备上的多模态app开启的前提下,可以通过该接口与多模态app建立websocket连接,进而实现人脸唤醒、定向拾音以及拾音降噪等增强能力。
声影降噪设备目前支持分体式和瓦力两种类型。
【请求参数】
参数 |
是否必选 |
默认值 |
类型 |
描述 |
---|---|---|---|---|
param |
是 |
- |
ThirdPartyParam |
第三方配置,详见表21。 |
参数 |
是否必选 |
默认值 |
类型 |
描述 |
---|---|---|---|---|
uHan |
否 |
- |
UHanParam |
声影分体式降噪设备配置,请参见表22。 |
uHanV2 |
否 |
- |
UHanParam |
声影瓦力降噪设备配置,请参见表22。 |
参数 |
是否必选 |
默认值 |
类型 |
描述 |
---|---|---|---|---|
origin |
否 |
"wss://127.0.0.1:10001" |
string |
声影降噪设备websocket建链地址,格式为“wss://IP:Port”或“ws://IP:Port”。 须知:origin和host参数二选一配置即可,如果2个参数均配置,优先使用origin配置。origin是4.0.0版本新增,低于此版本不支持配置origin。 |
host |
否 |
"127.0.0.1:10001" |
string |
声影降噪设备websocket建链地址,格式为“IP:Port”。 须知:origin和host参数二选一配置即可,如果2个参数均配置,优先使用origin配置。 |
enable |
否 |
false |
boolean |
是否启用声影降噪设备。 |
sleepDelay |
否 |
10000 |
number |
与数字人对话的用户人脸休眠时延。单位:ms。 |
showVideoUi |
否 |
false |
boolean |
是否显示与数字人对话的用户人脸画面。 |
【返回参数】
无
await HwICSUiSdk.setThirdPartyConfig({
uHan: {
enable: true,
showVideoUi: true,
host: `127.0.0.1:10001`,
sleepDelay: 10000,
},
});
startChat
(static) startChat(param?: ChatParam): Promise<ChatResult>
【功能说明】
开始对话。
【请求参数】
参数 |
是否必须 |
默认值 |
类型 |
描述 |
---|---|---|---|---|
interactionMode |
否 |
AUDIO |
|
交互模式,语音交互还是文本交互。 |
wakeupType |
否 |
"" |
string |
开始对话的方式。仅做数字人运维使用,如果有不同场景触发开始对话,比如按钮点击、语音唤醒等,可以通过该字段区分下触发场景。 |
preCheckPermissions |
否 |
true |
boolean |
是否进行麦克风权限校验。
|
【返回参数】
参数 |
类型 |
描述 |
---|---|---|
result |
boolean |
执行结果。 |
errorCode |
string | undefined |
错误码,详细见表1。 |
errorMsg |
string | undefined |
错误信息。 |
chatId |
string |
对话id。 |
sessionId |
string |
此轮对话的唯一标识,用于关联对话上下文内容。 |
【代码示例】
const { result } = await HwICSUiSdk.startChat({ interactionMode: 'AUDIO' });
startSpeak
(static) startSpeak(): Promise<UISdkResult>
【功能说明】
开始说话(注:接口已重命名为startUserSpeak,请直接切换至新接口)。
【请求参数】
无
【返回参数】
请参见表26。
【代码示例】
const { result } = await HwICSUiSdk.startSpeak();
startStreamRecord
(static) startStreamRecord(): Promise<void>
【功能说明】
开始录制用户讲话声音。
【请求参数】
无
【返回参数】
无
【代码示例】
await HwICSUiSdk.startStreamRecord();
startUserSpeak
(static) startUserSpeak(param?: Param): Promise<UISdkResult>
【功能说明】
用户开始提问。
【请求参数】
参数 |
是否必须 |
默认值 |
类型 |
描述 |
---|---|---|---|---|
preCheckPermissions |
否 |
true |
boolean |
是否进行麦克风权限校验。
|
【返回参数】
参数 |
类型 |
描述 |
---|---|---|
result |
boolean |
执行结果。 |
errorCode |
string | undefined |
错误码,详细见表1。 |
errorMsg |
string | undefined |
错误信息。 |
【代码示例】
const { result } = await HwICSUiSdk.startUserSpeak({ preCheckPermissions: false });
stopChat
(static) stopChat(): Promise<ChatResult>
【功能说明】
结束对话。
【请求参数】
无
【返回参数】
请参见表24。
【代码示例】
const { result } = await HwICSUiSdk.stopChat();
stopSpeak
(static) stopSpeak(): Promise<UISdkResult>
【功能说明】
停止说话(注:接口已重命名为stopUserSpeak,请直接切换至新接口)。
【请求参数】
无
【返回参数】
请参见表26。
【代码示例】
const { result } = await HwICSUiSdk.stopSpeak();
stopStreamRecord
(static) stopStreamRecord(): Promise<void>
【功能说明】
结束录制用户讲话声音,并弹框提示或自动保存pcm格式录音文件。
【请求参数】
无
【返回参数】
无
【代码示例】
await HwICSUiSdk.stopStreamRecord();
stopUserSpeak
(static) stopUserSpeak(): Promise<UISdkResult>
【功能说明】
用户停止提问(注:此处只是停止ASR接收用户语音,对话仍处于激活态)。
【请求参数】
无
【返回参数】
请参见表26。
【代码示例】
const { result } = await HwICSUiSdk.stopUserSpeak();