1. 接入 SDK
在
oh-package.json5 中添加 SDK 依赖:{"dependencies": {"virtualman-stream-sdk": "file:../sdk"}}
同时确保 TRTC HarmonyOS SDK 已放入
sdk/libs/ 目录下,并在 SDK 的 oh-package.json5 中配置:{"dependencies": {"@tencentcloud/liteavsdk_trtc": "file:./libs/LiteAVSDK_TRTC_13.4.0.8928.har"}}
注意:
使用的是专为数智人场景定制的 TRTC 版本,包含 Alpha 通道视频等数智人专属能力,请勿替换为通用版本。
2. 配置权限
SDK 需要网络权限和麦克风权限(语音驱动时),请在
module.json5 中配置:"requestPermissions": [{ "name": "ohos.permission.INTERNET" },{"name": "ohos.permission.MICROPHONE","reason": "$string:permission_microphone_reason","usedScene": { "abilities": ["EntryAbility"], "when": "inuse" }}]
3. 配置凭证
在
Config.ets 中填入您的数智人项目凭证:export class Config {static readonly APP_KEY: string = 'xxx'static readonly ACCESS_TOKEN: string = 'xxx'static readonly ASSET_VIRTUALMAN_KEY: string = 'xxx' // Asset 建流时使用static readonly VIRTUALMAN_PROJECT_ID: string = 'xxx' // Project 建流时使用}
4. 初始化及使用
import {VirtualmanView, Virtualman,VirtualmanParams, VirtualmanProjectParams, AssetVirtualmanParams, ExtraInfo} from 'virtualman-stream-sdk'import { Config } from '../Config'@Entry@Componentstruct Index {private virtualman: Virtualman = new Virtualman()@State isReady: boolean = falseaboutToAppear(): void {// 第一步:初始化(配置鉴权参数和建流参数,不建流)// 注意:ArkTS 严格模式要求使用 new,不可使用匿名对象字面量const params = new VirtualmanParams()params.appkey = Config.APP_KEYparams.accesstoken = Config.ACCESS_TOKEN// 方式一:项目建流参数const projectParams = new VirtualmanProjectParams()projectParams.virtualmanProjectId = Config.VIRTUALMAN_PROJECT_IDconst projectExtra = new ExtraInfo()projectExtra.alphaChannelEnable = trueprojectParams.extraInfo = projectExtraparams.virtualmanProjectParams = projectParams// 方式二:资产建流参数const assetParams = new AssetVirtualmanParams()assetParams.assetVirtualmanKey = Config.ASSET_VIRTUALMAN_KEYconst assetExtra = new ExtraInfo()assetExtra.alphaChannelEnable = trueassetParams.extraInfo = assetExtraparams.assetVirtualmanParams = assetParamsthis.virtualman.init(params)// 第二步:设置事件回调(挂在 controller 上,而非 VirtualmanView)this.virtualman.onError = (error: string): void => {console.error(`错误: ${error}`)}this.virtualman.onMessage = (text: string): void => {console.info(`收到WS消息: ${text}`)}this.virtualman.onWsOpen = (): void => {console.info('WebSocket 已连接,可以发送消息')}this.virtualman.onWsClose = (code: number, reason: string): void => {console.info(`WebSocket 已断开: code=${code}`)}}build() {Stack() {// 第三步:挂载渲染视图(始终挂载,内部管理生命周期)VirtualmanView({controller: this.virtualman}).width('100%').height('100%')Column() {// 方式一:通过 ProjectId 建流Button('项目建流').onClick(async (): Promise<void> => {const result = await this.virtualman.open()if (result.success) {this.isReady = trueconsole.info(`建流成功, sessionId: ${result.sessionId ?? ''}`)} else {console.error(`建流失败: ${result.error ?? ''}`)}})// 方式二:通过 AssetVirtualmanKey 建流Button('资产建流').onClick(async (): Promise<void> => {const result = await this.virtualman.openByAsset()if (result.success) {this.isReady = trueconsole.info(`建流成功, sessionId: ${result.sessionId ?? ''}`)} else {console.error(`建流失败: ${result.error ?? ''}`)}})// 建流成功后:发送指令if (this.isReady) {Button('发送对话').onClick((): void => {this.virtualman.chat({ text: '你好', isNewChat: true })})Button('关流').onClick((): void => {this.virtualman.close()this.isReady = false})}}}}}
5. 运行 Demo
5.1 打开工程
使用 DevEco Studio 打开
harmony 目录。5.2 配置签名
1. File → Project Structure → Signing Configs。
2. 勾选 Automatically generate signature。
3. 选择您的开发者证书。
5.3 选择设备并运行
1. 在 DevEco Studio 顶部工具栏选择目标设备。
2. 单击 ▶️ 运行按钮。
5.4 常见问题
问题 | 解决方法 |
运行后黑屏无画面 | 确认 Config.ets 中的凭证填写正确,且网络可用 |
编译时找不到 SDK | 确认 oh-package.json5 中 dependencies 路径配置正确 |
透明通道不生效 | 确认 open 时传入了 extraInfo.alphaChannelEnable = true |
建流失败后无法重试 | 建流失败后 open() 返回 success: false,按钮仍可点击重新 open |