本章节主要指导您完成
TUILiveKit UI 组件库接入的环境配置。集成方案说明:
本文档提供的是 UI 组件库接入方案,包含视频直播、语聊房的完整 UI 界面与全套业务逻辑。如果您有极高的 UI 定制需求,需要采用 无 UI(Core SDK) 集成方式,请直接参考 Core SDK 快速开始。
功能预览
TUILiveKit UI 组件为您提供的是功能闭环、交互丰富的直播全链路逻辑,集成后可快速实现一套交互完整、业务丰富的直播系统。
视频直播
主播开播前预览 | 主播开播 | 观众观看 | 主播和观众连麦 |
![]() | ![]() | ![]() | ![]() |
准备工作
开通服务
环境要求
Flutter
Flutter 3.27.4 或更高版本。
Dart 3.6.2 或更高的版本。
Android 平台
Android 5.0(SDK API Level 21)及以上版本。
Gradle 7.0 及以上的版本。
Android 5.0 及以上的手机设备。
iOS 平台
Xcode 16 或更高版本。
iOS 14.0 或更高版本。
已安装 CocoaPods 环境。如果您尚未安装,请 点击查看 安装步骤。
代码集成
步骤1:下载 TUILiveKit 组件
flutter pub add tencent_live_uikit atomic_x_core
安装命令执行成功后,控制台将输出如下信息:
Resolving dependencies...Downloading packages.........+ tencent_live_uikit x.x.x......Changed xx dependencies!xx packages have newer versions incompatible with dependency constraints.Try `flutter pub outdated` for more information.
步骤2:工程配置
1. 如果需要编译运行在 Android 平台,由于 SDK 内部使用了 Java 的反射特性,需要将 SDK 中的部分类加入不混淆名单。
首先,需要在工程的
android/app/build.gradle 文件中配置并开启混淆规则以及配置开启 Multidex 支持:android {......defaultConfig {......// 开启 Multidex 支持multiDexEnabled true}buildTypes {release {......// 配置并开启混淆规则minifyEnabled trueproguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro'}}}
在
android/app/proguard-rules.pro 文件中添加以下代码,如果该文件不存在则新建一个文件:-keep class com.tencent.** { *; }
2. 在
android/app/src/main/AndroidManifest.xml 中声明音视频能力所需权限。组件自身只声明网络与前台服务相关权限,摄像头、麦克风等权限需由宿主 App 声明:<uses-permission android:name="android.permission.INTERNET" /><uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" /><uses-permission android:name="android.permission.CAMERA" /><uses-permission android:name="android.permission.RECORD_AUDIO" /><uses-permission android:name="android.permission.MODIFY_AUDIO_SETTINGS" /><uses-permission android:name="android.permission.BLUETOOTH" /><uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />
3. 对齐插件版本。
在
android/app/settings.gradle 里,配置相关插件版本。plugins {id "dev.flutter.flutter-plugin-loader" version "1.0.0"id "com.android.application" version "8.2.1" apply falseid "org.jetbrains.kotlin.android" version "2.1.10" apply false}
1. 在 ios/Podfile 中确认部署目标,并打开相机、麦克风权限宏。permission_handler_apple 的权限策略由预处理器宏控制,宏未定义时相关代码整段不参与编译,权限请求会直接返回 denied:
platform :ios, '15.0'post_install do |installer|installer.pods_project.targets.each do |target|flutter_additional_ios_build_settings(target)target.build_configurations.each do |config|config.build_settings['GCC_PREPROCESSOR_DEFINITIONS'] ||= ['$(inherited)','PERMISSION_CAMERA=1','PERMISSION_MICROPHONE=1',]endendend
2. 在
ios/Runner/Info.plist 的一级 <dict> 中添加权限说明,并声明后台音频模式(观众退到后台时仍需听到直播间声音):<key>NSCameraUsageDescription</key><string>TUILiveKit 需要访问您的相机权限,开启后连麦视频才会有画面</string><key>NSMicrophoneUsageDescription</key><string>TUILiveKit 需要访问您的麦克风权限,开启后连麦才会有声音</string><key>UIBackgroundModes</key><array><string>audio</string></array>
3. iOS release 版本需保留全局符号:使用 Xcode 打开工程,在 TARGETS > Runner > Build Settings > Deployment 中将 Strip Style 设置为 Non-Global Symbols,否则可能在运行时出现异常、无法进入房间。
4. 修改原生依赖(Podfile、pubspec.yaml)后,执行 flutter pub get 与 pod install 并完整重编译,Hot Reload 不会更新原生配置。
完成登录
代码集成完成后,您需要完成登录。这是使用 TUILiveKit 的关键步骤,因为只有在登录成功后才能正常使用 TUILiveKit 的各项功能,故请您耐心检查相关参数是否配置正确:
说明:
在实际项目场景下,强烈推荐您在完成自己的用户身份验证等相关登录操作后,再调用 TUILiveKit 的登录服务。这样可以避免因过早调用登录服务,导致业务逻辑混乱或数据不一致的问题,同时也能更好地适配您项目中现有的用户管理和权限控制体系。
import 'package:atomic_x_core/atomicxcore.dart';import 'package:flutter/material.dart';Future<void> login() async {// 1. 调用登录接口,userSig 应由您的业务服务端下发final CompletionHandler result = await LoginStore.shared.login(sdkAppID: 1400000001, // 请替换为开通服务控制台的 SDKAppIDuserID: 'denny', // 请替换为您的 UserIDuserSig: 'xxxxxxxxxxx', // 请替换为服务端生成的 UserSig);// 2. 检查登录结果if (result.isSuccess) {debugPrint('login success');} else {debugPrint('login failed: ${result.errorCode} ${result.errorMessage}');}}
登录接口参数说明:
参数 | 类型 | 说明 |
SDKAppID | Int | |
userID | String | 当前用户的唯一 ID,仅包含英文字母、数字、连字符和下划线。为避免多端登录冲突,请勿使用 1、123 等简单 ID。 |
userSig | String | 用于腾讯云鉴权的票据。请注意: 开发环境:您可以采用本地 GenerateTestUserSig.genTestSig 函数生成 userSig 或者 通过 UserSig 辅助工具 生成临时的 UserSig。生产环境:为了防止密钥泄露,请务必采用服务端生成 UserSig 的方式。详细信息请参考 服务端生成 UserSig。 |
登录异常状态处理【可选】
LoginStore 提供了登录状态回调机制,方便您处理可能出现的登录异常情况,主要包括 “被踢下线” 和 “签名过期” 这两种异常状态的回调:被踢下线:用户在线情况下被踢, SDK 会通过
onKickedOffline 回调通知给您,此时可以在 UI 提示用户,并调用 LoginStore.shared.login 重新登录。签名过期:用户在线期间收到
onUserSigExpired 回调,说明您之前给该用户签发的 userSig 已经过期了,这个时候如果当前用户在您后台的登录态依然有效,您可以让您的 app 向您的后台请求新的 userSig,并调用 LoginStore.shared.login 续签登录态。import 'dart:async';import 'package:atomic_x_core/atomicxcore.dart';import 'package:flutter/foundation.dart';class LoginService {StreamSubscription<LoginEvent>? subscription;void subscribeLoginStatus() {subscription = LoginStore.shared.loginEventStream.listen((LoginEvent event) {switch (event) {case LoginEvent.kickedOffline:case LoginEvent.loginExpired:debugPrint('login state changed: $event');}});}void dispose() {subscription?.cancel();}}
下一步
恭喜您,现在您已经成功集成了直播组件并完成了登录。接下来,您可以根据您的业务场景实现主播开播、观众观看、直播列表等功能。
常见问题
关于每次进房是否需要登录?
不需要。通常您只需要完成一次
LoginStore.shared.login 调用即可,我们建议您将 LoginStore.shared.login 和 LoginStore.shared.logout 与自己的登录业务关联。iOS release 下运行或打包后无法进入房间?
请参考 工程配置 中 iOS 部分第 1 步:在 Xcode 中,在 TARGETS 列表中选择 target(通常是 Runner),选择项目 > Build Settings > Deployment,将其下的 Strip Style 设置为
Non-Global Symbols,以保留所需要的全局符号信息,否则可能在运行时出现异常,无法进入房间。


