帮你快速理解、总结文档立即下载
文档中心>实时音视频>直播与语聊 SDK>快速接入>快速接入（HarmonyOS）

快速接入（HarmonyOS）

最近更新时间：2026-11-11 16:15:30
本文档已由 AI 辅助审校
我的收藏

本页目录：

本章节主要指导您完成 TUILiveKit UI 组件库接入的环境配置。

功能预览

TUILiveKit UI 组件为您提供的是功能闭环、交互丰富的直播全链路逻辑，集成后可快速实现一套交互完整、业务丰富的直播系统。

视频直播

主播开播前预览
主播开播
观众观看
主播和观众连麦









准备工作

开通服务

在使用 TUILiveKit 前，请先参考 开通服务，领取 TUILiveKit 体验版或者开通付费版。

环境要求

DevEco Studio：已安装 HarmonyOS SDK 6.1.1（API 24），并使用 DevEco 自带的 JBR 作为 JDK。
工程配置：Hvigor modelVersion 为 6.1.1；targetSdkVersion 为 6.1.1(24)，compatibleSdkVersion 为 6.0.0(20)，runtimeOS 为 HarmonyOS。
设备：HarmonyOS 6.0.0（API 20）及以上版本的手机设备。

代码集成

步骤1：下载 TUILiveKit 组件

1. 在 GitHub 中克隆/下载代码，将 live-v2/tuilivekit 目录拷贝到您的 Hvigor 工程根目录下（与 entry 模块同级）。

2. 声明依赖：在 entry/oh-package.json5 中声明本地组件与 AtomicXCore 核心库：
{
  "name": "entry",
  "version": "1.0.0",
  "dependencies": {
    "tuilivekit": "file:../../TUILiveKit",
    "@tencentcloud/atomicxcore": "5.3.0"
  }
}
3. 注册模块：在工程根 build-profile.json5 的 modules 中注册组件模块，srcPath 大小写需与磁盘目录一致：
 {
  "app": {
    "products": [
      {
        "name": "default",
        "targetSdkVersion": "6.1.1(24)",
        "compatibleSdkVersion": "6.0.0(20)",
        "runtimeOS": "HarmonyOS",
        "buildOption": {
          "strictMode": {
            "caseSensitiveCheck": true,
            "useNormalizedOHMUrl": true
          }
        }
      }
    ]
  },
  "modules": [
    {
      "name": "entry",
      "srcPath": "./entry"
    },
    {
      "name": "tuilivekit",
      "srcPath": "../TUILiveKit"
    }
  ]
}
4. 安装依赖：在工程根目录执行：
ohpm install --all

步骤2：工程配置

组件 HAR 自身不声明权限，音视频权限需由宿主 entry 模块声明。请在 entry/src/main/module.json5 的 module 节点中添加：
{
  "module": {
    "name": "entry",
    "type": "entry",
    "mainElement": "EntryAbility",
    "deviceTypes": [
      "phone"
    ],
    "requestPermissions": [
      {
        "name": "ohos.permission.INTERNET"
      },
      {
        "name": "ohos.permission.GET_NETWORK_INFO"
      },
      {
        "name": "ohos.permission.CAMERA",
        "reason": "$string:app_name",
        "usedScene": {
          "abilities": [
            "EntryAbility"
          ],
          "when": "inuse"
        }
      },
      {
        "name": "ohos.permission.MICROPHONE",
        "reason": "$string:app_name",
        "usedScene": {
          "abilities": [
            "EntryAbility"
          ],
          "when": "inuse"
        }
      }
    ]
  }
}
同时在 AppScope/app.json5 中配置您的 bundleName，并在 DevEco Studio 的 File > Project Structure > Signing Configs 中完成调试签名配置。
说明：
compatibleSdkVersion 请保持 6.0.0(20)；提高到设备不支持的版本会导致安装失败。组件侧通过 applicationStateChange 监听前后台切换，无需在 module.json5 中额外声明后台模式。

完成登录

代码集成完成后，您需要完成登录，这是使用 TUILiveKit 的关键步骤，因为只有在登录成功后才能正常使用 TUILiveKit 的各项功能，故请您耐心检查相关参数是否配置正确：
说明：
在示例代码中直接进行了登录接口的调用。但在实际项目场景下，强烈推荐您在完成自己的用户身份验证等相关登录操作后，再调用 TUILiveKit 的登录服务。这样可以避免因过早调用登录服务，导致业务逻辑混乱或数据不一致的问题。
import { LoginStore } from '@tencentcloud/atomicxcore'

@Component
struct LoginService {
  private readonly loginStore: LoginStore = LoginStore.shared()

  login(): void {
    // 1. 调用登录接口，userSig 应由您的业务服务端下发
    this.loginStore.login(
      1400000001,       // 请替换为开通服务控制台的 SDKAppID
      'denny',          // 请替换为您的 UserID
      'xxxxxxxxxxx',    // 请替换为服务端生成的 UserSig
      getContext(this),
    ).then(() => {
      // 2. 登录成功
      console.info('login success')
    }).catch((error: Error) => {
      console.error(`login failed: ${error.message}`)
    })
  }

  build() {
    Column() {
    }
  }
}

登录接口参数说明

参数
类型
说明
SDKAppID
Int
从 TRTC 控制台 > 应用管理 获取。
UserID
String
当前用户的唯一 ID，仅包含英文字母、数字、连字符和下划线。
UserSig
String
用于腾讯云鉴权的票据。请注意：
开发环境：您可以采用本地 GenerateTestUserSig.genTestSig 函数生成 UserSig 或者通过 UserSig 辅助工具 生成临时的 UserSig。
生产环境：为了防止密钥泄露，请务必采用服务端生成 UserSig 的方式。详细信息请参见 服务端生成 UserSig。
更多信息请参见 如何计算及使用 UserSig。

登录异常状态处理【可选】

LoginStore 提供了登录事件订阅，方便您处理可能出现的登录异常情况，主要包括 被踢下线 和 签名过期 两种事件：
被踢下线：用户在线情况下被踢，SDK 会通过 LoginEvent.KICKED_OFFLINE 事件通知给您，此时可以在 UI 提示用户，并调用 LoginStore.shared().login 重新登录。
签名过期：收到 LoginEvent.LOGIN_EXPIRED 事件说明 userSig 已过期，如果当前用户在您后台的登录态依然有效，可向后台请求新的 userSig 并重新登录。
import { LoginEvent, LoginStore } from '@tencentcloud/atomicxcore'

@Component
struct LoginEventObserver {
  private readonly loginStore: LoginStore = LoginStore.shared()

  observeLoginEvents(): void {
    this.loginStore.loginEventEmitter.subscribe(this, (event: LoginEvent) => {
      if (event === LoginEvent.KICKED_OFFLINE) {
        console.info('kicked offline')
      } else if (event === LoginEvent.LOGIN_EXPIRED) {
        console.info('login expired')
      }
    })
  }

  build() {
    Column() {
    }
  }
}

下一步

恭喜您，现在您已经成功集成了直播组件并完成了登录。接下来，您可以根据您的业务场景实现主播开播、观众观看、直播列表等功能。
业务场景
描述
集成指引
视频直播
包含主播开播、观众观看、连麦互动、美颜设置、礼物弹幕等全套功能。
主播开播
观众观看
直播列表
展示直播间/语聊房列表，支持封面、人数、房间标题等信息展示。
直播列表

常见问题

集成后还需要添加摄像头、麦克风权限声明吗？

需要。组件 HAR 的 module.json5 不包含 requestPermissions，请在宿主 entry 模块中声明 INTERNET、GET_NETWORK_INFO、CAMERA、MICROPHONE 四项权限；组件内的开播页会在运行时动态申请相机与麦克风权限。

ohpm 依赖解析失败或找不到 tuilivekit？

请在 Hvigor 工程根执行 ohpm install --all，并确认 entry/oh-package.json5 中的 file: 路径与 build-profile.json5 中 srcPath 指向真实的 TUILiveKit 目录。工程开启了 caseSensitiveCheck，路径大小写必须与磁盘一致。

构建时报 Unable to locate a Java Runtime？

请将 JAVA_HOME 显式指向 DevEco Studio 自带的 JBR，并把 $JAVA_HOME/bin 加入 PATH，再重新执行构建命令。
中国站