帮你快速理解、总结文档立即下载

观众观看(iOS)

最近更新时间:2026-11-11 16:15:32
本文档已由 AI 辅助审校
我的收藏
TUILiveKit 的观众观看页为用户提供了丰富且便捷的直播观看与互动功能,能快速集成到您的应用中,满足观众多样化的需求。
集成提示:
本文档介绍基于 UI 组件 的观众观看方式(含完整交互 UI)。若您需通过 Core SDK 自行搭建观众端界面,请参考 观众观看 (Core SDK)。

功能概览

直播预览:未进房前即可先预览主播实时画面,点击进入直播间后再参与互动。
直播观看:清晰、流畅观看主播实时直播画面,可查看直播间标题、主播信息及在线观众。
直播互动:送礼物(有动画特效,主播接收提示)、点赞(有动画及实时统计)、发弹幕互动,并可申请与主播音视频连麦互动。
直播预览
直播观看
直播互动






组件说明

PlayerView 用于观看单个直播间,适用于直接进入某一个直播间的场景(如分享链接、开播推送通知),组件内已包含拉流、进房、连麦、弹幕、礼物、点赞等完整交互 UI。

快速接入

步骤 1:开通服务

参考 开通服务 文档开通体验版或大规模直播版套餐。

步骤 2:代码集成

参考 准备工作 接入 TUILiveKit,并完成 AtomicXCore 登录。
注意:
创建 PlayerView 之前,请确保已完成登录,否则拉流与进房会失败。
宿主 App 必须声明 audio 后台模式(UIBackgroundModes → audio,即 Target → Signing & Capabilities → Background Modes → Audio, AirPlay, and Picture in Picture)。未声明时 App 进入后台会被系统挂起,观众端将听不到直播间声音。

步骤 3:使用 PlayerView 观看单个直播间

在您的观众观看视图控制器中创建并初始化 PlayerView:
Swift

import AtomicXCore
import Combine
import SnapKit
import TUILiveKit
import UIKit

class AudiencePlayerViewController: UIViewController {

private let liveID: String
private let playerView = PlayerView()
private var cancellables = Set<AnyCancellable>()

init(liveID: String) {
self.liveID = liveID
super.init(nibName: nil, bundle: nil)
}

@available(*, unavailable)
required init?(coder: NSCoder) {
fatalError("init(coder:) has not been implemented")
}

override func viewDidLoad() {
super.viewDidLoad()

// 1. 将 playerView 添加到视图上
view.addSubview(playerView)
playerView.snp.makeConstraints { make in
make.edges.equalToSuperview()
}

// 2. 设置直播间信息(必须在 startPlay / joinChannel 之前调用)
let liveInfo = LiveInfo()
liveInfo.liveID = liveID
playerView.setLiveInfo(liveInfo)
playerView.contentSafeAreaInsets = view.safeAreaInsets

// 3. 监听关闭、进房事件
playerView.onCloseClicked = { [weak self] in
self?.dismiss(animated: true)
}
playerView.onJoinLiveClicked = { [weak self] in
print("onJoinLiveClicked, liveID:\\(self?.liveID ?? "")")
}

// 4. (可选) 监听播放状态变化
playerView.status
.receive(on: DispatchQueue.main)
.sink { status in
print("player status:\\(status)")
}
.store(in: &cancellables)

// 5. 开始拉流播放
playerView.startPlay()

// 6. 加入直播间,进房成功后观众才能发弹幕、点赞、送礼、连麦
playerView.joinChannel { result in
switch result {
case .success(let joinedLiveInfo):
print("joinChannel success, liveID:\\(joinedLiveInfo.liveID)")
case .failure(let error):
print("joinChannel failed:\\(error.localizedDescription)")
}
}
}

override func viewDidDisappear(_ animated: Bool) {
super.viewDidDisappear(animated)
// 7. 离开页面时停止播放并退出直播间
guard isMovingFromParent || isBeingDismissed else { return }
playerView.stopPlay()
playerView.leaveChannel(completion: nil)
}
}

步骤 4:导航路由到观众观看页面

在您需要跳转到观众观看页时,可参考如下代码示例:
Swift
// 跳转到「单个直播间」观看页
let playerVC = AudiencePlayerViewController(liveID: "您的直播房间 id")
playerVC.modalPresentationStyle = .fullScreen
present(playerVC, animated: false)

组件 API 说明

PlayerView

PlayerView 继承自 UIView,用于观看单个直播间。
方法 / 属性
说明
PlayerView()
构造方法,创建观看视图。
setLiveInfo(_ liveInfo: LiveInfo)
设置直播间信息。必须在 startPlay、joinChannel 之前调用,否则这两个接口会因缺少直播间信息直接返回。
startPlay()
开始拉流播放(仅播放画面,尚未进房)。
stopPlay()
停止拉流播放。
joinChannel(completion:)
加入直播间,通过 Result<LiveInfo, Error> 回调进房结果。进房成功后观众才能发弹幕、点赞、送礼、申请连麦。
leaveChannel(completion:)
退出直播间,通过 Result<Void, Error> 回调退出结果。
setVolume(_ volume: Int)
设置播放音量,取值范围 0 ~ 100。
joinLiveEntranceEnabled
是否展示进入直播间入口。关闭后观众可直接观看画面,点击入口才进房。
contentSafeAreaInsets
组件内容区的安全边距,用于适配刘海屏与自定义容器。
status
AnyPublisher<PlayerStatus, Never>(Combine),用于观察当前播放状态。
liveID
当前观看的直播间 ID。
onCloseClicked
闭包回调,观众点击关闭按钮时触发(组件会先退出直播间再回调)。
onJoinLiveClicked
闭包回调,观众通过进入直播间入口进房成功时触发。

PlayerStatus

PlayerView.status 的播放状态,取值如下:
状态
说明
idle
空闲,未播放也未进房。
playing
正在拉流播放,观众尚未进房(展示进入直播间入口)。
inRoom
已进房,观众可参与弹幕、点赞、送礼、连麦等互动。
coGuest
连麦中(申请中或已上麦)。
end
直播已结束或被踢出,组件展示直播结束页。

下一步

恭喜您,现在您已经成功集成了观众观看。接下来,您可以实现主播开播、直播列表等功能,可参考下表:
功能
描述
集成指引
主播开播
主播开播全流程功能,包括开播前的准备和开播后的各种互动
礼物系统
实现自定义礼物素材配置、计费系统对接、PK 场景互动等功能

常见问题

App 退到后台后直播间没有声音?

请检查宿主 App 是否已声明 audio 后台模式:Target → Signing & Capabilities → Background Modes → 勾选 Audio, AirPlay, and Picture in Picture。未声明时 iOS 会在 App 进入后台后挂起音频会话。
调用了 startPlay 或 joinChannel 后没有画面 / 进房失败?
请先确认:
已调用 setLiveInfo() 设置直播间信息,且 liveID 不为空;
已完成 AtomicXCore 登录;
该直播间确实处于开播状态。
若以上都已确认,可通过 TUILiveKit 日志进一步定位。

观众选择视频连麦后,视频画面显示黑屏?

请前往手机设置 > App > 相机,检查摄像头权限是否开启,可参考下图:


观众发送弹幕时,直播间内其他观众看不到弹幕内容?

原因1:先检查网络连接,确保观众设备网络正常。
原因2:该观众被主播禁言,无法发送弹幕。
原因3:观众的弹幕内容涉及关键词屏蔽,请确认观众发送的弹幕内容是否符合直播间规则。