本文导读

展开导读

文档首页/ 数字内容生产线 MetaStudio/ API参考/ 智能交互/ 智能交互客户端SDK/ Web SDK/ 接口参考/ 主入口（HwICSUiSdk）

主入口（HwICSUiSdk）

更新时间：2025-01-24 GMT+08:00

本节介绍Web SDK的接口详情。

表1 接口
接口	描述	三方驱动场景（是否支持）	非三方驱动场景（是否支持）
activeInteractionMode	获取当前生效的交互模式（语音问答/文本问答）。	×	√
addEventListeners	回调注册。	√	√
checkBrowserSupport	检查浏览器是否支持。	√	√
create	创建交互任务。	√	√
destroy	销毁交互任务。	√	√
getJobInfo	获取交互任务信息。	√	√
initResourcePath	初始化语音唤醒资源，不使用语音唤醒能力则忽略该接口。	×	√
interactionModeSwitch	切换交互模式（语音问答/文本问答）。	×	√
interruptSpeaking	中断数字人讲话。	×	√
muteRemoteAudio	数字人静音。	√	√
sendDrivenText	发送智能交互数字人主动播报的文本信息。	×	√
sendTextQuestion	发送问题文本。	×	√
setConfig	更新配置项。	√	√
setLogLevel	设置日志级别。	√	√
startChat	开始对话。	×	√
startSpeak	开始说话（注：接口已重命名为startUserSpeak，请直接切换至新接口）。	×	√
startUserSpeak	用户开始提问。	×	√
stopChat	结束对话。	×	√
stopSpeak	停止说话（注：接口已重命名为stopUserSpeak，请直接切换至新接口）。	×	√
stopUserSpeak	用户停止提问（注：此处只是停止ASR接收用户语音，对话仍处于激活态）。	×	√
unmuteRemoteAudio	数字人取消静音。	√	√

activeInteractionMode

(static) activeInteractionMode(): Promise<InteractionModeResult>

【功能说明】

获取当前生效的交互模式（语音问答/文本问答）。

【请求参数】

无。

【返回参数】

表2 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

【功能说明】

设置事件回调。

【请求参数】

表3 eventMap
参数	是否必须	默认值	类型	描述
eventMap	是	-	EventMap	事件注册Map，请参见表4。

表4 EventMap
参数	是否必须	默认值	类型	描述
error	否	-	(icsError: IcsError) => any	错误事件。
jobInfoChange	否	-	(jobInfo: JobInfo) => any	交互任务信息变更事件。
speakingStart	否	-	() => any	数字人开始讲话事件。
speakingStop	否	-	() => any	数字人结束讲话事件。
speechRecognized	否	-	(question: SpeechRecognitionInfo) => any	语音识别结果。
semanticRecognized	否	-	(answer: SemanticRecognitionInfo) => any	语义识别结果。

【返回参数】

无

【代码示例】

HwICSUiSdk.addEventListeners({
  error: (icsError) => {
    console.error('icsError', icsError);
  },
  jobInfoChange: (jobInfo) => {
    console.info('jobInfoChange', jobInfo);
  } 
});

checkBrowserSupport

(static) checkBrowserSupport(): Promise<boolean>

【功能说明】

检查当前浏览器是否支持运行SDK。

【请求参数】

无

【返回参数】

Promise<boolean>：当前浏览器是否支持运行SDK。

【代码示例】

     
        const result = await HwICSUiSdk.checkBrowserSupport();
if (result) {
  // 支持
} else {
  // 不支持
}

create

(static) create(param: CreateParam): Promise<void>

【功能说明】

通过获取的任务链接和一次性鉴权码，创建智能交互任务。

【请求参数】

表5 param
参数	是否必选	默认值	类型	描述
param	是	-	CreateParam	创建活动选项，请参见表6。

表6 CreateParam
参数	是否必选	默认值	类型	描述
onceCode	是	-	string	一次性鉴权码，获取方式请参见创建一次性鉴权码。说明： CreateOnceCode接口需要在后台调用，不能在浏览器直接调用，否则有跨域问题。
serverAddress	是	-	string	智能交互服务端地址。不同Region的取值如下所示：亚太-新加坡：metastudio-api.ap-southeast-3.myhuaweicloud.com
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	配置信息，请参见表14。
eventListeners	否	-	EventMap	事件注册Map，请参见表4。第三方驱动的智能交互场景，必须传本参数。
logLevel	否	info	string	日志级别。取值如下所示： debug info warn error none

【返回参数】

无

【代码示例】

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>

【功能说明】

获取交互任务信息。

【请求参数】

无

【返回参数】

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

initResourcePath

(static) interactionModeSwitch(param: ResourcePath): Promise<void>

【功能说明】

初始化语音唤醒资源，不使用语音唤醒能力则忽略该接口。

3.0.1之后的websdk包里面有如下两个资源文件，如果不使用语音唤醒，可忽略这两个文件。

wasmData.js：语音唤醒的算法资源文件。
modelData.js：语音唤醒的模型资源文件。

SDK内置默认唤醒模型，支持定制唤醒词，并更新本地模型，详见Web语音唤醒。

【请求参数】

表8 ResourcePath
参数	是否必选	默认值	类型	描述
wasmPath	是	'wasmData.js'	string	唤醒算法资源文件的相对路径或者绝对路径。相对路径为基于当前页面的路径，比如：页面地址为https://.../a/b，默认值为'wasmData.js'，则算法可执行文件路径为https://.../a/b/wasmData.js。需要确保该路径为websdk包内部wasmData.js文件。绝对路径为完整的HTTP文件资源路径。
dataPath	是	'modelData.js'	string	唤醒模型资源文件的相对路径或者绝对路径。相对路径为基于当前页面的路径，比如：页面地址为https://.../a/b，默认值为'modelData.js'，则算法可执行文件路径为https://.../a/b/modelData.js。绝对路径为完整的HTTP文件资源路径。
initModel	否	true	boolean	是否直接初始化唤醒模型。初始化唤醒模型需要2~3s的加载时间，这段时间无法进行其他操作，所以需要根据实际情况选择模型初始化的时间点，详细说明如下所示：如果为true，会在接口执行时，初始化模型。如果为false，会在数字人创建过程中，初始化模型。

【返回参数】

无。

【代码示例】

await HwICSUiSdk.initResourcePath({
  wasmPath: 'wasmData.js',
  dataPath: 'modelData.js',
  initModel: true,
});

注意：如果未设置wasmPath和dataPath或设置的不对，会报类似下面的异常。

此时语音唤醒是无法正常使用的，需要将路径设置为正确的才行。

图1 异常报错

interactionModeSwitch

(static) interactionModeSwitch(param: InteractionModeParam): Promise<InteractionModeResult>

【功能说明】

切换交互模式（语音问答/文本问答）。

【请求参数】

表9 InteractionModeParam
参数	是否必须	默认值	类型	描述
interactionMode	否	AUDIO	AUDIO TEXT	交互模式，语音交互还是文本交互。

【返回参数】

见：表2

【代码示例】

const { result } = await HwICSUiSdk.interactionModeSwitch({ interactionMode: 'AUDIO' });

interruptSpeaking

(static) interruptSpeaking(): Promise<UISdkResult>

【功能说明】

中断数字人讲话。

【请求参数】

无

【返回参数】

请参见表18。

【代码示例】

const { result } = await HwICSUiSdk.interruptSpeaking();

muteRemoteAudio

(static) muteRemoteAudio(): Promise<boolean>

【功能说明】

数字人静音。

【请求参数】

无

【返回参数】

Promise<boolean>：数字人静音是否成功。

【代码示例】

const result = await HwICSUiSdk.muteRemoteAudio();

sendDrivenText

(static) sendDrivenText(param: TextDrivenParam): Promise<ChatResult>

【功能说明】

发送智能交互数字人主动播报的文本信息。

注意：主动播报结束时的最后一次调用，一定要传“isLast:true”参数，否则数字人讲话结束时无法及时收到speakingStop通知。

【请求参数】

**表10** TextDrivenParam
参数	是否必须	默认值	类型	描述
text	是	""	string	智能交互数字人主动播报的文本信息。
isLast	否	false	boolean	是否是最后一条。

【返回参数】

请参见表17。

【代码示例】

const { result } = await HwICSUiSdk.sendDrivenText({ text: '你好', isLast: true });

sendTextQuestion

(static) sendTextQuestion(param: TextQuestionParam): Promise<TextQuestionResult>

【功能说明】

发送问题文本。

【请求参数】

**表11** TextQuestionParam
参数	是否必须	默认值	类型	描述
text	是	-	string	问题文本。

【返回参数】

**表12** TextQuestionResult
参数	类型	描述
result	boolean	执行结果。
errorCode	string \| undefined	错误码，详细见表1。
errorMsg	string \| undefined	错误信息。
chatId	string	对话id。

【代码示例】

const { result } = await HwICSUiSdk.sendTextQuestion({ text: '你是谁' });

setConfig

(static) setConfig(config: ConfigMap): void

【功能说明】

设置配置项，用于控制是否显示字幕或交互按钮。

【请求参数】

**表13** config
参数	是否必须	默认值	类型	描述
config	是	-	ConfigMap	配置信息，请参见表14。

**表14** ConfigMap
参数	是否必须	默认值	类型	描述
enableCaption	否	false	boolean	是否显示字幕。
enableChatBtn	否	false	boolean	是否显示交互按钮。
enableHotIssues	否	false	boolean	是否显示热点问题。
enableWeakErrorInfo	否	true	boolean	是否显示弱提示。示例：SDK内部websocket异常提示。
enableBusinessTrack	否	true	boolean	是否上报SDK埋点数据。
enableJobCache	否	true	boolean	是否启用任务缓存。如果用户希望每次修改任务配置后能快速生效，可不启用缓存。启用任务缓存，可加快数字人的启动速度。关闭任务缓存，每次调用create创建任务时，都会创建新任务，不使用上次缓存的任务。
useDefaultBackground	否	true	boolean	是否使用默认背景图。
enableLocalWakeup	否	false	boolean	是否启用语音唤醒能力。如果启动，需要先调用initResourcePath接口初始化唤醒资源路径，再调用create接口创建数字人。

【返回参数】

无

【代码示例】

HwICSUiSdk.setConfig({
  enableCaption: true,
  enableChatBtn: false,
  enableHotIssues: false,
  enableWeakErrorInfo: true,
});

setLogLevel

(static) setLogLevel(logLevel: 'debug' | 'info' | 'warn' | 'error' | 'none'): void

【功能说明】

设置输出日志的级别。

【请求参数】

**表15** logLevel
参数	是否必须	默认值	类型	描述
logLevel	是	info	debug info warn error none	日志级别。

【返回参数】

无

【代码示例】

HwICSUiSdk.setLogLevel('warn');

startChat

(static) startChat(param?: ChatParam): Promise<ChatResult>

【功能说明】

开始对话。

【请求参数】

**表16** ChatParam
参数	是否必须	默认值	类型	描述
interactionMode	否	AUDIO	AUDIO TEXT	交互模式，语音交互还是文本交互。

【返回参数】

**表17** ChatResult
参数	类型	描述
result	boolean	执行结果。
errorCode	string \| undefined	错误码，详细见表1。
errorMsg	string \| undefined	错误信息。
chatId	string	对话id。

【代码示例】

const { result } = await HwICSUiSdk.startChat({ interactionMode: 'AUDIO' });

startSpeak

(static) startSpeak(): Promise<UISdkResult>

【功能说明】

开始说话。

【请求参数】

无

【返回参数】

请参见表18。

【代码示例】

const { result } = await HwICSUiSdk.startSpeak();

startUserSpeak

(static) startUserSpeak(): Promise<UISdkResult>

【功能说明】

用户开始提问。

【请求参数】

无

【返回参数】

**表18** UISdkResult
参数	类型	描述
result	boolean	执行结果。
errorCode	string \| undefined	错误码，详细见表1。
errorMsg	string \| undefined	错误信息。

【代码示例】

const { result } = await HwICSUiSdk.startUserSpeak();

stopChat

(static) stopChat(): Promise<ChatResult>

【功能说明】

结束对话。

【请求参数】

无

【返回参数】

请参见表17。

【代码示例】

const { result } = await HwICSUiSdk.stopChat();

stopSpeak

(static) stopSpeak(): Promise<UISdkResult>

【功能说明】

停止说话。

【请求参数】

无

【返回参数】

请参见表18。

【代码示例】

const { result } = await HwICSUiSdk.stopSpeak();

stopUserSpeak

(static) stopUserSpeak(): Promise<UISdkResult>

【功能说明】

用户停止提问。

【请求参数】

无

【返回参数】

请参见表18。

【代码示例】

const { result } = await HwICSUiSdk.stopUserSpeak();

unmuteRemoteAudio

(static) unmuteRemoteAudio(): Promise<boolean>

【功能说明】

数字人取消静音。

【请求参数】

无

【返回参数】

Promise<boolean>：数字人取消静音是否成功。

【代码示例】

const result = await HwICSUiSdk.unmuteRemoteAudio();

父主题：接口参考

上一篇：接口参考

下一篇：事件通知（EventMap）

意见反馈

文档内容是否对您有帮助？

有帮助没帮助

提供反馈

提交成功！非常感谢您的反馈，我们会继续努力做到更好！

系统繁忙，请稍后重试

在使用文档中是否遇到以下问题

内容与产品页面不一致

内容不易理解

缺失示例代码

步骤不可操作

搜不到想要的内容

缺少最佳实践

意见反馈（选填）

0/500

请至少选择一项反馈信息并填写问题反馈

字符长度不能超过500

直接提交取消

主入口（HwICSUiSdk）

activeInteractionMode

addEventListeners

checkBrowserSupport

create

destroy

getJobInfo

initResourcePath

interactionModeSwitch

interruptSpeaking

muteRemoteAudio

sendDrivenText

sendTextQuestion

setConfig

setLogLevel

startChat

startSpeak

startUserSpeak

stopChat

stopSpeak

stopUserSpeak

unmuteRemoteAudio

意见反馈

文档内容是否对您有帮助？

文档反馈