**AtomicXCore** 提供了 [CoGuestStore](https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/cogueststore) 模块，专门用于管理观众连麦的完整业务流程。您无需关心复杂的状态同步和信令交互，只需调用几个简单的方法，即可为您的直播添加强大的观众与主播音视频互动功能。

## 核心场景

`CoGuestStore` 支持以下两种最主流的连麦场景：
- **观众申请上麦**：观众主动发起连麦请求，主播在收到请求后进行同意或拒绝。

- **主播邀请上麦**：主播可以主动向直播间内的任意一位观众发起连麦邀请。

## 实现步骤

### 步骤1：组件集成

请参考 开始直播 集成 **AtomicXCore**，并完成 **LiveCoreView** 的接入。

### 步骤2：实现观众申请上麦

#### 观众端实现

作为观众，您的核心任务是**发起申请、接收结果**和**主动下麦**。
1. **发起连麦申请**

   当用户点击界面上的“申请连麦”按钮时，调用 `applyForSeat` 方法。

   ``` swift
   import AtomicXCore

   let liveId = "房间ID"
   let guestStore = CoGuestStore.create(liveID: liveId)

   // 用户点击“申请连麦”
   func requestToConnect() {
       // timeout: 请求超时时间，例如 30 秒
       guestStore.applyForSeat(timeout: 30.0, extraInfo: nil) { result in
         switch result {
         case .success():
             print("连麦申请已发送，等待主播处理...")
         case .failure(let error):
             print("申请发送失败: \(error.message)")
         }
       }
   }
   ```
2. **监听主播的响应**

   通过订阅 `guestEventPublisher`，您可以接收到主播的处理结果。

   ``` swift
   // 在您的视图控制器初始化时订阅事件
   func subscribeGuestEvents() {
       guestStore.guestEventPublisher
         .sink { [weak self] event in
             if case let .onGuestApplicationResponded(isAccept, hostUser) = event {
                 if isAccept {
                     print("主播 \(hostUser.userName) 同意了你的申请，准备上麦")
                     // 1. 打开摄像头、麦克风
                     DeviceStore.shared.openLocalCamera(isFront: true, completion: nil)
                     DeviceStore.shared.openLocalMicrophone(completion: nil)
                     // 2. 在此更新 UI，例如关闭申请按钮，显示连麦中的状态
                 } else {
                     print("主播 \(hostUser.userName) 拒绝了你的申请")
                     // 弹窗提示用户申请被拒绝
                 }
             }
         }
         .store(in: &cancellables) // 管理订阅生命周期
   }
   ```
3. **主动下麦**

   当连麦观众想结束互动时，调用 `disConnect` 方法即可返回普通观众状态。

   ``` swift
   // 用户点击“下麦”按钮
   func leaveSeat() {
       guestStore.disConnect { result in
         switch result {
         case .success():
             print("已成功下麦")
         case .failure(let error):
             print("下麦失败: \(error.message)")
         }
       }
   }
   ```
4. **(可选) 取消申请**

   如果观众在主播处理前想撤回申请，可以调用 `cancelApplication`。

   ``` swift
   // 用户在等待时，点击“取消申请”
   func cancelRequest() {
       guestStore.cancelApplication { result in
         switch result {
         case .success():
             print("申请已取消")
         case .failure(let error):
             print("申请取消失败: \(error.message)")
         }
       }
   }
   ```

#### 主播端实现

作为主播，您的核心任务是**接收申请、展示申请列表**和**处理申请**。
1. **监听新的连麦申请**

   通过订阅 `hostEventPublisher`，您可以在有新观众申请时立即收到通知，并给出提示。

   ``` swift
   import AtomicXCore

   let liveId = "房间ID"
   let guestStore = CoGuestStore.create(liveID: liveId)

   // 订阅主播事件
   guestStore.hostEventPublisher
       .sink { [weak self] event in
           if case let .onGuestApplicationReceived(guestUser) = event {
               print("收到观众 \(guestUser.userName) 的连麦申请")
               // 在此更新 UI，例如在“申请列表”按钮上显示红点
           }
       }
       .store(in: &cancellables)
   ```
2. **展示申请列表**

   `CoGuestStore` 的 state 会实时维护当前的申请者列表，您可以订阅它来刷新您的 UI。

   ``` swift
   // 订阅状态变更
   guestStore.state
       .subscribe(StatePublisherSelector(keyPath: \CoGuestState.applicants)) // 只关心申请者列表的变化
       .removeDuplicates()
       .sink { applicants in
           print("当前申请人数: \(applicants.count)")
           // 在此刷新您的“申请者列表”UI
           // self.applicantListView.update(with: applicants)
       }
       .store(in: &cancellables)
   ```
3. **处理连麦申请**

   当您在列表中选择一位观众并点击“同意”或“拒绝”时，调用相应的方法。

   ``` perl
   // 主播点击“同意”按钮，传入申请者的 userID
   func accept(userId: String) {
       guestStore.acceptApplication(userID: userId) { result in
           if case .success = result {
               print("已同意 \(userId) 的申请，对方正在上麦")
           }
       }
   }

   // 主播点击“拒绝”按钮
   func reject(userId: String) {
       guestStore.rejectApplication(userID: userId) { result in
           if case .success = result {
               print("已拒绝 \(userId) 的申请")
           }
       }
   }
   ```

### 步骤3：实现主播邀请上麦

#### 主播端实现
1. **向观众发起邀请**

   当主播在观众列表中选择某人并点击“邀请连麦”时，调用 `inviteToSeat` 方法。

   ``` swift
    // 主播选择观众并发起邀请
   func invite(userId: String) {
       // timeout: 邀请超时时间
       guestStore.inviteToSeat(userID: userId, timeout: 30.0, extraInfo: nil) { result in
           if case .success = result {
               print("已向 \(userId) 发出邀请，等待对方回应...")
           }
       }
   }
   ```
2. **监听观众的回应**

   通过 `hostEventPublisher` 监听 `onHostInvitationResponded` 事件。

   ``` swift
   // 在 hostEventPublisher 的订阅中添加
   if case let .onHostInvitationResponded(isAccept, guestUser) = event {
       if isAccept {
           print("观众 \(guestUser.userName) 接受了你的邀请")
       } else {
           print("观众 \(guestUser.userName) 拒绝了你的邀请")
       }
   }
   ```

#### 观众端实现
1. **接收主播的邀请**

   通过 `guestEventPublisher` 监听 `onHostInvitationReceived` 事件。

   ``` swift
   // 在 guestEventPublisher 的订阅中添加
   if case let .onHostInvitationReceived(hostUser) = event {
       print("收到主播 \(hostUser.userName) 的连麦邀请")
       // 在此弹出一个对话框，让用户选择“接受”或“拒绝”
       // self.showInvitationDialog(from: hostUser)
   }
   ```
2. **响应邀请**

   当用户在弹出的对话框中做出选择后，调用相应的方法。

   ``` swift
   let inviterId = "发起邀请的主播ID" // 从 onHostInvitationReceived 事件中获取

   // 用户点击“接受”
   func accept() {
       guestStore.acceptInvitation(inviterID: inviterId) { result in
           if case .success = result {
               // 2. 打开摄像头、麦克风
               DeviceStore.shared.openLocalCamera(isFront: true, completion: nil)
               DeviceStore.shared.openLocalMicrophone(completion: nil)
           }
       }
   }

   // 用户点击“拒绝”
   func reject() {
       guestStore.rejectInvitation(inviterID: inviterId) { result in
           // ...
       }
   }
   ```

### 运行效果

当您集成以上功能实现后，请分别使用两个观众与主播进行连麦操作，观众 A 同时打开摄像头和麦克风，观众 B 只打开麦克风，运行效果如下，您可以参考下一章节 完善 UI 细节 来定制您想要的 UI 逻辑。

## 完善 UI 细节

您可以通过 `LiveCoreView.VideoViewDelegate` 协议提供的“插槽”能力，在观众连麦的视频流画面上添加自定义视图，用于显示昵称、头像等信息，或在他们关闭摄像头时提供占位图，以优化视觉体验。

### 实现视频流画面的昵称显示

#### **实现效果**

#### **实现方式**

> **提示：**
>

> 您也可以参考 TUILiveKit 开源项目中的 [AnchorCoGuestView.swift](https://github.com/Tencent-RTC/TUIKit_iOS/blob/main/live/Sources/Features/AnchorBoardcast/View/LivingView/Video/AnchorCoGuestView.swift) 和 [AnchorEmptySeatView.swift](https://github.com/Tencent-RTC/TUIKit_iOS/blob/main/live/Sources/Features/AnchorBoardcast/View/LivingView/Video/AnchorEmptySeatView.swift) 文件来了解完整的实现逻辑。
>

- **步骤 1**：创建前景视图 (**CustomSeatView**)，该视图用于在视频流上方显示用户信息。

   ``` swift
   import UIKit

   // 自定义的用户信息悬浮视图（前景）
   class CustomSeatView: UIView {
      lazy var nameLabel: UILabel = {
           let label = UILabel()
           label.textColor = .white
           label.font = .systemFont(ofSize: 14)
           return label
       }()

       override init(frame: CGRect) {
           super.init(frame: frame)
           backgroundColor = UIColor.black.withAlphaComponent(0.5)
           addSubview(nameLabel)
           nameLabel.snp.makeConstraints { make in
               make.bottom.equalToSuperview().offset(-5)
               make.leading.equalToSuperview().offset(5)
           }
       }
   }
   ```
- **步骤 2**：创建背景视图 (**CustomAvatarView**)，该视图用于在用户无视频流时作为占位图显示。

   ``` swift
   import UIKit

   // 自定义的头像占位视图（背景）
   class CustomAvatarView: UIView {
       lazy var avatarImageView: UIImageView = {
           let imageView = UIImageView()
           imageView.tintColor = .gray
           return imageView
       }()

       override init(frame: CGRect) {
           super.init(frame: frame)
           backgroundColor = .clear
           layer.cornerRadius = 30
           addSubview(avatarImageView)
           avatarImageView.snp.makeConstraints { make in
               make.center.equalToSuperview()
               make.width.height.equalTo(60)
           }
       }
   }

   ```
- **步骤 3**：实现 `VideoViewDelegate.createCoGuestView` 协议，根据 `viewLayer` 的值返回对应的视图。

   ``` swift
   import AtomicXCore

   // 1. 在您的视图控制器中，遵守 VideoViewDelegate 协议
   class YourViewController: UIViewController, VideoViewDelegate {

       // ... 其他代码 ...

       // 2. 完整实现协议方法，处理两种 viewLayer
       func createCoGuestView(seatInfo: TUISeatFullInfo, viewLayer: ViewLayer) -> UIView? {
           guard let userId = seatInfo.userID,!userId.isEmpty else {
               return nil
           }
           if viewLayer == .foreground {
               // 用户摄像头开启时，显示前景视图
               let seatView = CustomSeatView()
               seatView.nameLabel.text = seatInfo.userName
               return seatView
           } else { // viewLayer == .background
               // 用户摄像头关闭时，显示背景视图
               let avatarView = CustomAvatarView()
               // 您可以在这里通过 seatInfo.userAvatar 加载用户真实头像
               return avatarView
           }
       }
   }
   ```

#### **参数说明**：
| **参数** | **类型** | **说明** |
| --- | --- | --- |
| `seatInfo` | `TUISeatFullInfo` | 麦位信息对象，包含麦上用户的详细信息。 |
| `seatInfo.userID` | `String?` | 麦上用户的 ID。 |
| `seatInfo.userName` | `String? ` | 麦上用户的昵称。 |
| `seatInfo.userAvatar` | `String?` | 麦上用户的头像 URL。 |
| `seatInfo.userMicrophoneStatus` | `TUIDeviceStatus` | 麦上用户的麦克风状态。 |
| `seatInfo.userCameraStatus ` | `TUIDeviceStatus` | 麦上用户的摄像头状态。 |
| `viewLayer` | `ViewLayer` | 视图层级枚举。<br>`.foreground` 表示前景挂件视图，始终显示在视频画面的最上层。<br>`.background` 表示背景挂件视图，位于前景视图下层，仅在对应用户没有视频流（例如未开摄像头）的情况下显示，通常用于展示用户的默认头像或占位图。 |

## API 文档

关于 [CoGuestStore](https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/cogueststore) 及其相关类的所有公开接口、属性和方法的详细信息，请参阅 [AtomicXCore](https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore) 框架的官方 API 文档。本指南使用到的相关 Store 如下：
| Store/Component | 功能描述 | API 文档 |
| --- | --- | --- |
| LiveCoreView | 直播视频流展示与交互的核心视图组件：负责视频流渲染和视图挂件处理，支持主播直播、观众连麦、主播连线等场景。 | [API 文档](https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/livecoreview) |
| DeviceStore | 音视频设备控制：麦克风（开关 / 音量）、摄像头（开关 / 切换 / 画质）、屏幕共享，设备状态实时监听。 | [API 文档](https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/devicestore) |
| CoGuestStore | 观众连麦管理：连麦申请 / 邀请 / 同意 / 拒绝，连麦成员权限控制（麦克风 / 摄像头），状态同步。 | [API 文档](https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/cogueststore) |

## 常见问题

### 如何管理通过 `VideoViewDelegate` 添加的自定义视图的生命周期和事件？

**LiveCoreView** 会自动管理您通过代理方法返回的视图的添加和移除，您无需手动处理。如果需要在自定义视图中处理用户交互（例如点击事件），请在创建视图时为其添加相应的事件即可。

### `VideoViewDelegate` 中的 viewLayer 参数有什么作用？

`viewLayer` 用于区分前景和背景挂件：
- `.foreground`：前景层，始终显示在视频画面的最上层。

- `.background`：背景层，仅在对应用户没有视频流（例如未开摄像头）的情况下显示，通常用于展示用户的默认头像或占位图。

### 我的自定义视图为什么没有显示？
- **检查代理设置**：请确认已调用 `coreView.videoViewDelegate = self` 并成功设置了代理。

- **检查实现方法**：请检查是否正确实现了对应的代理方法（例如 `createCoGuestView`）。

- **检查返回值**：确保您的代理方法在正确的时机返回了一个有效的 `UIView` 实例，而不是 `nil`。您可以在代理方法中添加断点或日志进行调试。