tencent cloud

直播 SDK

文档直播 SDK客户端 APIiOSBattleStore

BattleStore

Download
聚焦模式
字号
最后更新时间： 2026-06-29 16:59:21

简介

PK 功能实现主播之间的实时互动对战。BattleStore 提供了一套全面的 API 来管理整个 PK 生命周期。
重要：
请始终使用工厂方法 create(liveID:) 并提供有效的直播间 ID 来创建 BattleStore 实例。不要尝试直接初始化。
说明：
PK 状态更新通过 state 发布者传递。订阅它以接收有关 PK 信息、参与用户和分数的实时更新。
警告：
如果 PK 请求在指定的超时时间内未收到响应，将触发超时事件。请始终在 UI 中处理超时场景。

功能特性

PK 请求管理：主播可以发起 PK 请求，被邀请方可以接受或拒绝。
状态管理：实时跟踪 PK 信息、参与用户和分数。
事件驱动架构：提供完整的 PK 事件回调。
超时处理：为 PK 请求提供内置超时机制。

可订阅数据

BattleState 的字段描述如下：
属性名
类型
描述
currentBattleInfo
当前 PK 信息。
battleUsers
[SeatUserInfo]
PK 用户列表。
battleScore
[String: UInt]
PK 分数的映射。

API 列表

函数名
描述
创建 BattleStore 实例。
PK 事件发布者。
发起 PK 请求。
取消 PK 请求。
接受 PK 请求。
拒绝 PK 请求。
退出 PK。

创建实例

create

创建 BattleStore 实例。
public static func create(liveID: String) -> BattleStore {
    let store: BattleStoreImpl = StoreFactory.shared.getStore(roomID: liveID)
    return store
}
版本信息
从3.5版本开始支持。
参数说明
参数名
类型
描述
liveID
String
直播间 ID。

观察状态和事件

battleEventPublisher

PK 事件发布者。
数据结构：BattleEvent

PK 操作

requestBattle

发起 PK 请求。
public func requestBattle(config: BattleConfig, userIDList: [String], timeout: TimeInterval, completion: BattleRequestClosure?) {
    fatalError("\\(#function) must be overridden by subclass")
}
版本信息
从3.5版本开始支持。
参数说明
参数名
类型
描述
config
PK 配置。
userIDList
[String]
希望邀请 PK 的其他主播用户 ID 列表。请传入您想要 PK 的对方主播用户 ID，请注意不要在此列表中包含当前用户自己的 ID。
timeout
TimeInterval
超时时间（单位：秒），最大限制为30秒。
completion
BattleRequestClosure?
发起请求成功的回调。

cancelBattleRequest

取消 PK 请求。
public func cancelBattleRequest(battleId: String, userIdList: [String], completion: CompletionClosure?) {
    fatalError("\\(#function) must be overridden by subclass")
}
版本信息
从3.5版本开始支持。
参数说明
参数名
类型
描述
battleId
String
PK ID。
userIdList
[String]
用户 ID 列表。
completion
CompletionClosure?
取消请求成功的回调。

acceptBattle

接受 PK 请求。
public func acceptBattle(battleID: String, completion: CompletionClosure?) {
    fatalError("\\(#function) must be overridden by subclass")
}
版本信息
从3.5版本开始支持。
参数说明
参数名
类型
描述
battleID
String
PK ID。
completion
CompletionClosure?
接受成功的回调。

rejectBattle

拒绝 PK 请求。
public func rejectBattle(battleID: String, completion: CompletionClosure?) {
    fatalError("\\(#function) must be overridden by subclass")
}
版本信息
从3.5版本开始支持。
参数说明
参数名
类型
描述
battleID
String
PK ID。
completion
CompletionClosure?
拒绝成功的回调。

exitBattle

退出 PK。
public func exitBattle(battleID: String, completion: CompletionClosure?) {
    fatalError("\\(#function) must be overridden by subclass")
}
版本信息
从3.5版本开始支持。
参数说明
参数名
类型
描述
battleID
String
PK ID。
completion
CompletionClosure?
退出 PK 成功的回调。

数据结构

BattleEndedReason

正在 PK 中用户收到 PK 结束的原因。
枚举值
值
说明
timeOver
0
PK 倒计时结束。
allMemberExit
1
所有 PK 成员退出。

BattleEvent

收到 PK 相关的回调事件。
枚举值
说明
onBattleStarted
当 PK 正式开始时触发此回调，通知所有参与者 PK 已经开始。
onBattleEnded
当 PK 结束时触发此回调。
onUserJoinBattle
当有用户加入 PK 时触发此回调。
onUserExitBattle
当有用户退出 PK 时触发此回调。
onBattleRequestReceived
当收到 PK 请求时触发此回调。
onBattleRequestCancelled
当 PK 请求被取消时触发此回调。
onBattleRequestTimeout
当 PK 请求超时时触发此回调。
onBattleRequestAccept
当 PK 请求被接受时触发此回调。
onBattleRequestReject
当 PK 请求被拒绝时触发此回调。

BattleConfig

发送 PK 请求时，设置的 PK 配置信息。
属性
类型
说明
duration
TimeInterval
PK 持续时间（单位：秒）。
needResponse
Bool
被邀请用户是否需要回复同意/拒绝。
extensionInfo
String
扩展信息。

BattleInfo

PK 信息。
属性
类型
说明
battleID
String
PK ID。
config
发送 PK 请求时，设置的 PK 配置信息。
startTime
UInt
PK 开始标记时间戳（单位：秒）。
endTime
UInt
PK 结束标记时间戳（单位：秒）。

BattleState

BattleStore 对外提供的 PK 相关状态数据。
属性
类型
说明
currentBattleInfo
当前 PK 信息。
battleUsers
[SeatUserInfo]
PK 用户列表。
battleScore
[String: UInt]
PK 分数的映射。

BattleRequestCallback

PK 请求回调。
PK 请求的回调接口，用于处理 PK 请求的成功或失败结果。
方法
onSuccess: 成功回调。
fun onSuccess(battleInfo: BattleInfo, resultMap: Map<String, Int>)
参数名
类型
说明
battleInfo
PK 信息，包含 PK 的详细配置和状态。
resultMap
Map<String, Int>
PK 请求的响应结果回调。
onError: 失败回调。
fun onError(code: Int, desc: String)
参数名
类型
说明
code
Int
错误码。
desc
String
错误描述。

使用示例

// 创建 store 实例
let store = BattleStore.create(liveID: "live_room_123")
// 订阅状态变化
store.state.subscribe { state in
    if let battleInfo = state.currentBattleInfo {
        print("当前 PK ID: \\(battleInfo.battleID)")
    }
    print("PK 用户数: \\(state.battleUsers.count)")
}
// 订阅 PK 事件
store.battleEventPublisher.sink { event in
    switch event {
    case .onBattleStarted(let battleInfo, let inviter, let invitees):
        print("PK 开始，发起者: \\(inviter.userName)")
    case .onBattleEnded(let battleInfo, let reason):
        print("PK 结束，原因: \\(reason)")
    default:
        break
    }
}
// 发起 PK 请求
let config = BattleConfig(duration: 300, needResponse: true)
store.requestBattle(config: config, userIDList: ["user_456"], timeout: 30) { result in
    switch result {
    case .success(let (battleInfo, resultMap)):
        print("PK 请求成功: \\(battleInfo.battleID)")
    case .failure(let error):
        print("PK 请求失败: \\(error)")
    }
}

上一篇: BaseBeautyStore下一篇: CoGuestStore

帮助和支持

本页内容是否解决了您的问题？

填写满意度调查问卷，共创更好文档体验。

文档反馈