简介
跨房连线功能允许不同直播间的主播进行实时互动。CoHostStore 提供了一套全面的 API 来管理整个跨房连线生命周期。
重要:
请始终使用工厂方法 CoHostStore.create 并提供有效的直播间 ID 来创建 CoHostStore 实例。不要尝试直接初始化。
说明:
连线状态更新通过 coHostState 发布者传递。订阅它以接收有关连线状态、已连接主播、邀请和申请的实时更新。
警告:
如果连线请求在指定的超时时间内未收到响应,将触发超时事件。请始终在 UI 中处理超时场景。
功能特性
双向连线:主播可以向其他主播发起连线请求,也可以接收其他主播的连线请求。
状态管理:实时跟踪连线状态、已连接主播、邀请列表和申请者。
事件驱动架构:提供连线事件流用于监听各种连线状态变化。
布局模板:支持多种连线布局模板,如动态网格布局和1对6布局。
可订阅数据
CoHostState 的字段描述如下:
属性名 | 类型 | 描述 |
coHostStatus | 跨房连线的实时状态。 | |
connected | 正在和当前直播间连线的主播列表。 | |
invitees | 向其他直播间发出请求的主播列表。 | |
applicant | 向当前直播间发起连线请求的主播。 | |
candidatesCursor | StateFlow<String> | 推荐用户列表游标。 |
candidates | 推荐用户列表。 |
API 列表
函数名 | 描述 |
创建对象实例。 | |
连线事件回调。 | |
连线事件回调。 | |
发起连线请求。 | |
取消连线请求。 | |
接受连线请求。 | |
拒绝连线请求。 | |
退出连线。 | |
获取推荐主播列表。 |
创建实例
CoHostStore.create
创建对象实例。
观察状态和事件
addCoHostListener
添加连线回调监听器
abstract fun addCoHostListener(listener: CoHostListener?)
版本信息
从 3.5 版本开始支持。
参数说明
参数名 | 类型 | 是否必填 | 描述 |
listener | 必填 | 监听器。 |
removeCoHostListener
移除连线回调监听器
abstract fun removeCoHostListener(listener: CoHostListener?)
版本信息
从 3.5 版本开始支持。
参数说明
参数名 | 类型 | 是否必填 | 描述 |
listener | 必填 | 监听器。 |
连线操作
requestHostConnection
发起主播连线请求
abstract fun requestHostConnection(targetHostLiveID: String?,layoutTemplate: CoHostLayoutTemplate,timeout: Int,extraInfo: String?,completion: CompletionHandler?)
向目标主播发起跨房连线请求。
调用此方法后,会向目标主播发送连线请求。请求将保持活动状态,直到:
• 目标主播通过 acceptHostConnection(fromHostLiveID:completion:) 接受
• 目标主播通过 rejectHostConnection(fromHostLiveID:completion:) 拒绝
• 超时时间到期
• 您通过 cancelHostConnection(toHostLiveID:completion:) 取消
版本信息
从 3.5 版本开始支持。
参数说明
参数名 | 类型 | 是否必填 | 描述 |
targetHostLiveID | String? | 必填 | 目标主播的直播间ID。 |
layoutTemplate | 必填 | 连线布局模板。 | |
timeout | Int | 必填 | 请求超时时间(单位:秒)。 |
extraInfo | String? | 必填 | 扩展信息。 |
completion | 必填 | 发起请求成功的回调。 |
cancelHostConnection
取消主播连线请求
abstract fun cancelHostConnection(toHostLiveID: String?,completion: CompletionHandler?)
版本信息
从 3.5 版本开始支持。
参数说明
参数名 | 类型 | 是否必填 | 描述 |
toHostLiveID | String? | 必填 | 目标主播的直播间ID。 |
completion | 必填 | 取消请求成功的回调。 |
acceptHostConnection
接受主播连线请求
abstract fun acceptHostConnection(fromHostLiveID: String?,completion: CompletionHandler?)
版本信息
从 3.5 版本开始支持。
参数说明
参数名 | 类型 | 是否必填 | 描述 |
fromHostLiveID | String? | 必填 | 发起连线请求的主播直播间ID。 |
completion | 必填 | 接受成功的回调。 |
rejectHostConnection
拒绝主播连线请求
abstract fun rejectHostConnection(fromHostLiveID: String?,completion: CompletionHandler?)
版本信息
从 3.5 版本开始支持。
参数说明
参数名 | 类型 | 是否必填 | 描述 |
fromHostLiveID | String? | 必填 | 发起连线请求的主播直播间ID。 |
completion | 必填 | 拒绝成功的回调。 |
exitHostConnection
退出主播连线
abstract fun exitHostConnection(completion: CompletionHandler?)
版本信息
从 3.5 版本开始支持。
参数说明
参数名 | 类型 | 是否必填 | 描述 |
completion | 必填 | 退出连线成功的回调。 |
getCoHostCandidates
获取可以与当前主播连线的推荐主播列表
abstract fun getCoHostCandidates(cursor: String,completion: CompletionHandler?)
版本信息
从 3.5 版本开始支持。
参数说明
参数名 | 类型 | 是否必填 | 描述 |
cursor | String | 必填 | 游标。 |
completion | 必填 | 完成回调。 |
数据结构
CoHostStatus
当前用户的跨房连线状态。
枚举值 | 值 | 说明 |
CONNECTED | 0 | 和其他主播正在连线中。 |
DISCONNECTED | 1 | 没有和其他主播连线。 |
CoHostLayoutTemplate
连线布局模板。
枚举值 | 值 | 说明 |
HOST_VOICE_CONNECTION | 2 | 语聊房连线布局。 |
HOST_DYNAMIC_GRID | 600 | 主播动态网格布局。 |
HOST_DYNAMIC_1V6 | 601 | 主播动态1对6布局。 |
CoHostListener
连线请求的回调事件。
方法
方法名 | 说明 |
onCoHostRequestReceived | 当收到连线请求时触发此回调。 |
onCoHostRequestCancelled | 当连线请求被取消时触发此回调。 |
onCoHostRequestAccepted | 当连线请求被接受时触发此回调。 |
onCoHostRequestRejected | 当连线请求被拒绝时触发此回调。 |
onCoHostRequestTimeout | 当连线请求超时时触发此回调。 |
onCoHostUserJoined | 当用户加入连线时触发此回调。 |
onCoHostUserLeft | 当用户离开连线时触发此回调。 |
CoHostState
CoHostStore 对外提供的跨房连线相关状态数据。
属性 | 类型 | 说明 |
coHostStatus | 跨房连线的实时状态。 | |
connected | 正在和当前直播间连线的主播列表。 | |
invitees | 向其他直播间发出请求的主播列表。 | |
applicant | 向当前直播间发起连线请求的主播。 | |
candidatesCursor | StateFlow<String> | 推荐用户列表游标。 |
candidates | 推荐用户列表。 |
使用示例
// 创建 store 实例val store = CoHostStore.create("live_room_123")// 订阅状态变化lifecycleScope.launch {store.coHostState.coHostStatus.collect { status ->println("连线状态: $status")}}lifecycleScope.launch {store.coHostState.connected.collect { connected ->println("已连接主播: ${connected.size}")}}// 添加连线事件监听器store.addCoHostListener(object : CoHostListener() {override fun onCoHostRequestReceived(inviter: SeatUserInfo, extensionInfo: String) {println("收到来自 ${inviter.userName} 的连线请求")// 显示接受/拒绝的 UI}override fun onCoHostRequestAccepted(invitee: SeatUserInfo) {println("连线请求被 ${invitee.userName} 接受")}override fun onCoHostUserJoined(userInfo: SeatUserInfo) {println("主播 ${userInfo.userName} 加入连线")}})// 发起连线请求store.requestHostConnection(targetHostLiveID = "target_live_id",layoutTemplate = CoHostLayoutTemplate.HOST_DYNAMIC_GRID,timeout = 30,extraInfo = "",completion = { code, message ->if (code == 0) {println("连线请求发送成功")}})