本文档将帮助您使用 AtomicXCore SDK 的核心组件
LiveCoreView,快速构建一个包含主播开播和观众观看功能的基础直播 App。核心功能
LiveCoreView 是一个专为直播场景设计的轻量级 UI 组件,是您构建直播场景的核心,它封装了所有复杂的底层直播技术(例如推拉流、连麦、音视频渲染)。您可以将 LiveCoreView 作为直播画面的“画布”,专注于上层 UI 与交互的开发。通过下方的视图层级示意图,您可以直观了解
LiveCoreView 在直播界面中的位置和作用:
准备工作
步骤1:开通服务
步骤2:在当前项目中导入 AtomicXCore
1. 安装组件:请在您的工程中执行以下脚本,添加 AtomicXCore 的相关依赖;
# 1. 安装直播核心及原生构建工具 (必选)npx expo install react-native-tuikit-atomic-x expo-dev-client expo-build-properties#2. 安装 UI 适配与工具库 (建议)npx expo install react-native-safe-area-context react-native-toast-message react-native-localize
2. 配置工程权限:打开项目根目录下的
app.json 文件,配置直播需要用到的系统权限(相机、麦克风,后台音频),您可以这样配置:{"expo": {"name": "ExpoLive","slug": "ExpoLive",// ... Other Configurations"ios": {// ... Other Configurations"bundleIdentifier": "com.anonymous.ExpoLive","infoPlist": {"NSMicrophoneUsageDescription": "This app requires access to your microphone for live streaming.","NSCameraUsageDescription": "This app requires access to your camera for live streaming.","UIBackgroundModes": ["audio"]}},"plugins": ["react-native-localize",["expo-build-properties",{"ios": {"useFrameworks": "static"}}]]}}
3. 重新构建原生开发包:您刚刚引入了一个全新的包含了原生代码的库
AtomicXCore,必须在工程根目录下重新编译一次原生应用,把这些新的 C++/Java/Swift 代码打包进去;仅在首次集成或更新 SDK 版本时需要执行此步,日常开发只需执行步骤 4。# 本地已有 Android 和 iOS 的开发环境,则执行npx expo run:ios # 确保已安装 CocoaPodsnpx expo run:android# 或者使用云打包重新生成开发版的安装包npx eas build --profile development --platform all
4. 运行 app:在工程根目录下执行如下脚本,iOS 通过系统相机扫码跳转 app,Android 直接打开上一步安装的 app 直接扫码,后续的 JS 代码变更会自动热更新。
npx expo start
步骤3:完成登录
在您的项目中调用
LoginState 中的 login 方法完成登录,这是使用 AtomicXCore 所有功能的关键前提。重要:
推荐在您 App 自身的用户账户登录成功后,再调用 LoginState 中的 login 方法,以确保登录业务逻辑的清晰和一致。
import { useLoginState } from 'react-native-tuikit-atomic-x/lib/module/atomic-x/state/LoginState';const { login } = useLoginState();const handleLogin = () => {login({sdkAppID: 1400000001, // 替换为您的 SDKAppIDuserID: "test_001", // 替换为您的 UserIDuserSig: "xxxxxxxxxx" // 替换为您的 UserSig});}
登录接口参数说明:
参数 | 类型 | 说明 |
sdkAppID | number | |
userID | string | 当前用户的唯一 ID,仅包含英文字母、数字、连字符和下划线。为避免多端登录冲突,请勿使用 1、123 等简单 ID。 |
userSig | string | 用于腾讯云鉴权的票据。请注意: 开发环境:您可以采用本地 GenerateTestUserSig.genTestSig 函数生成 userSig 或者 通过 UserSig 辅助工具 生成临时的 UserSig。生产环境:为了防止密钥泄露,请务必采用服务端生成 UserSig 的方式。详细信息请参考 服务端生成 UserSig。 |
搭建基础直播间
步骤1:实现主播视频开播
主播开播流程如下,您只需执行以下几步操作,即可快速搭建主播视频直播。

1. 初始化主播推流的视图
在您的主播页中,引入
LiveCoreView 组件,将 coreViewType 指定为 pushView(推流视图), 并且为组件绑定当前直播 ID。import { LiveCoreView } from 'react-native-tuikit-atomic-x/lib/module/components/LiveCoreView';export default function YourAnchorScreen({ route, navigation }) {// 定义直播房 ID(需要与后续 createLive 中使用的 liveID 保持一致)// liveID 由开发者自定义,建议使用唯一标识符(例如 UUID 或时间戳组合)// 格式要求:仅支持英文字母、数字、下划线,长度不超过 64 个字符const liveID = 'your_live_room_id'; // 替换为您的视频直播间的 IDreturn (<View style={styles.container}><LiveCoreView liveId={liveID} coreViewType="pushView" style={styles.pushView} /></View>);}
2. 打开摄像头和麦克风
通过调用
DeviceState 的 openLocalCamera、openLocalMicrophone 接口打开摄像头和麦克风,您无需做额外操作,LiveCoreView 会自动预览当前摄像头的视频流,示例代码如下:import { useEffect } from 'react';import { useDeviceState } from 'react-native-tuikit-atomic-x/lib/module/atomic-x/state/DeviceState';const { openLocalCamera, openLocalMicrophone } = useDeviceState();useEffect(() => {openLocalMicrophone({onSuccess: () => { console.log('麦克风打开成功'); },onError: (error) => { console.log('麦克风打开失败', error); },});openLocalCamera({isFront: true,onSuccess: () => { console.log('摄像头打开成功'); },onError: (error) => { console.log('摄像头打开失败', error); },});}, []);
3. 开始直播
通过调用
LiveListState 的 createLive 接口开始视频直播,完整示例代码如下:import { useLiveListState } from 'react-native-tuikit-atomic-x/lib/module/atomic-x/state/LiveListState';const { createLive } = useLiveListState();const startLive = () => {createLive({liveInfo: {liveID: liveID, // 设置直播的房间 idliveName: 'live name', // 设置直播的房间名称seatLayoutTemplateID: 600, // 配置布局模板,默认:600 动态宫格布局keepOwnerOnSeat: true, // 配置主播始终在麦位上},onSuccess: () => { console.log('创建直播间成功'); },onError: (error) => { console.log('创建直播间失败', error); },});};
LiveInfo 参数说明:参数名 | 类型 | 属性 | 描述 |
liveID | string | 必填 | 直播间的唯一标识符。 |
liveName | string | 选填 | 直播间的标题。 |
notice | string | 选填 | 直播间的公告信息。 |
isMessageDisable | boolean | 选填 | 是否禁言( true:是,false:否)。 |
isPublicVisible | boolean | 选填 | 是否公开可见( true:是,false:否)。 |
isSeatEnabled | boolean | 选填 | 是否启用麦位功能( true:是,false:否)。 |
keepOwnerOnSeat | boolean | 选填 | 是否保持房主在麦位上。 |
maxSeatCount | number | 选填 | 最大麦位数量。 |
seatMode | string | 选填 | 上麦模式( 'FREE':自由上麦,'APPLY':申请上麦)。 |
seatLayoutTemplateID | number | 必填 | 麦位布局模板 ID。 |
coverURL | string | 选填 | 直播间的封面图片地址。 |
backgroundURL | string | 选填 | 直播间的背景图片地址。 |
activityStatus | number | 选填 | 直播活动状态。 |
isGiftEnabled | boolean | 选填 | 是否启用礼物功能( true:是,false:否)。 |
4. 结束直播
直播结束后,主播可以调用
LiveListState 的 endLive 接口结束直播。SDK 会处理停止推流和销毁房间的逻辑。import { useLiveListState } from 'react-native-tuikit-atomic-x/lib/module/atomic-x/state/LiveListState';const { endLive } = useLiveListState();const handleEndLive = () => {endLive({onSuccess: () => { console.log('结束直播成功'); },onError: (error) => { console.log('结束直播失败', error); },});};
步骤2:实现观众进房观看
观众观看流程如下,通过简单几步操作,即可实现观众观看直播。

1. 实现观众拉流页面
在您的观众页中,引入
LiveCoreView 组件,将 coreViewType 指定为 playView(拉流视图), 并且为组件绑定当前直播 ID。import { LiveCoreView } from 'react-native-tuikit-atomic-x/lib/module/components/LiveCoreView';export default function YourAudienceScreen({ route, navigation }) {const { liveID } = route.params || {};return (<View style={styles.container}><LiveCoreView liveId={liveID} coreViewType="playView" style={styles.playView} /></View>);}
2. 进入直播间观看
通过调用
LiveListState 的 joinLive 接口加入直播,您无需做额外操作,LiveCoreView 会自动播放当前房间的视频流,完整示例代码如下:import { useEffect } from 'react';import { useLiveListState } from 'react-native-tuikit-atomic-x/lib/module/atomic-x/state/LiveListState';export default function YourAudienceScreen({ route, navigation }) {const { liveID } = route.params || {};const { joinLive } = useLiveListState();useEffect(() => {joinLive({liveID: liveID,onSuccess: () => { console.log('加入直播间成功'); },onError: (error) => { console.log('加入直播间失败', error); },});}, []);}
3. 退出直播
观众退出直播间时,需要调用
LiveListState 的 leaveLive 接口退出直播。SDK 会自动停止拉流并退出房间。import { useLiveListState } from 'react-native-tuikit-atomic-x/lib/module/atomic-x/state/LiveListState';const { leaveLive } = useLiveListState();// 离开直播const handleLeaveLive = () => {leaveLive({onSuccess: () => { console.log('离开直播间成功'); },onError: (error) => { console.log('离开直播间失败', error); },});};
步骤3:监听直播事件
在观众加入直播间后,您还需要处理一些房间内的“被动”事件。例如,主播主动结束了直播,或者观众因为违规等原因被移出房间。如果不监听这些事件,观众端 UI 可能会停留在黑屏页面,影响用户体验。
您可以通过订阅
LiveListState 提供的 addLiveListListener 来实现事件监听。import { useEffect } from 'react';import { useLiveListState } from 'react-native-tuikit-atomic-x/lib/module/atomic-x/state/LiveListState';export default function LiveAudienceScreen({ route, navigation }) {const { addLiveListListener, removeLiveListListener } = useLiveListState();useEffect(() => {const onLiveEnded = (event) => {console.log('直播结束', event);// 在这里处理直播间结束后的相关逻辑,例如关闭当前页面};const onKickedOutOfLive = (event) => {console.log('被移出房间', event.reason);// 可以根据被移出房间的原因进行弹窗提示};addLiveListListener('onLiveEnded', onLiveEnded);addLiveListListener('onKickedOutOfLive', onKickedOutOfLive);return () => {removeLiveListListener('onLiveEnded', onLiveEnded);removeLiveListListener('onKickedOutOfLive', onKickedOutOfLive);};}, []);}
运行效果
集成
LiveCoreView 后,您将得到一个纯净的视频渲染视图,它已具备完整的直播业务能力,但没有任何交互 UI。您可以参考下一章节 丰富直播场景 来完善直播场景。
丰富直播场景
当您完成了基础的直播功能后,您可以参考以下功能指南来为直播添加丰富的互动玩法。
直播功能 | 功能介绍 | 功能 States | 实现指南 |
实现观众音视频连线 | 观众申请上麦,与主播进行实时视频互动。 | ||
实现主播跨房连线 | 两个不同房间的主播进行连线,实现互动 | ||
添加弹幕聊天功能 | 观众可以在直播间发送和接收实时文字消息。 | ||
构建礼物赠送系统 | 观众可以向主播赠送虚拟礼物,增加互动和趣味性。 |
API 文档
State | 功能描述 | API 文档 |
LiveListState | 视频直播全生命周期管理:创建 / 加入 / 离开 / 销毁房间,查询房间列表,修改直播信息(名称、公告等),监听直播状态(例如被移出、结束)。 | |
DeviceState | 音视频设备控制:麦克风(开关 / 音量),设备状态实时监听。 | |
CoGuestState | 观众连麦管理:连麦申请 / 邀请 / 同意 / 拒绝,连麦成员权限控制(麦克风),状态同步。 | |
CoHostState | 主播跨房连线:支持多布局模板(动态网格等),发起 / 接受 / 拒绝连线,连麦主播互动管理。 | |
GiftState | 礼物互动:获取礼物列表,发送 / 接收礼物,监听礼物事件(含发送者、礼物详情)。 | |
BarrageState | 弹幕功能:发送文本 / 自定义弹幕,维护弹幕列表,实时监听弹幕状态。 | |
LikeState | 点赞互动:发送点赞,监听点赞事件,同步总点赞数。 | |
LiveAudienceState | 观众管理:获取实时观众列表(ID / 名称 / 头像),统计观众数量,监听观众进出事件。 | |
AudioEffectState | 音频特效:变声(童声 / 男声)、混响(KTV 等)、耳返调节,实时切换特效。 | |
BaseBeautyState | 基础美颜:调节磨皮 / 美白 / 红润(0-100 级),重置美颜状态,同步效果参数。 |
常见问题
主播调用 createLive 或 观众调用 joinLive 后为什么画面是黑的,没有视频画面?
检查 liveID:请确保在调用开播或观看接口前,已经为
LiveCoreView 实例设置了正确的 liveID。检查设备权限:请确保 App 已获得摄像头和麦克风的系统使用权限。
检查主播端:主播端是否正常调用
openLocalCamera({ isFront: true}) 打开了摄像头。检查网络:请检查设备网络连接是否正常。
主播端打开摄像头后,开播后可以看到本地视频预览画面,开播前视频预览是黑屏?
检查主播端:请检查主播推流视图
LiveCoreView 的 coreViewType 是否配置为 pushView。检查观众端:请检查观众拉流视图
LiveCoreView 的 coreViewType 是否配置为 playView。