@tencent-rtc/mcp 1.3.9 → 1.4.0

package/resource/doc/livekit/{voice → core-sdk/voice}/ios/voice-barrage.md

@@ -1,8 +1,5 @@
 This document provides a comprehensive guide for iOS developers to quickly integrate a feature-rich, high-performance live chat overlay (barrage/danmaku) system into your live streaming application using the `BarrageStore` module from the **AtomicXCore** framework.
 
-![](https://write-document-release-1258344699.cos.ap-guangzhou.tencentcos.cn/100027182498/17934b0bc6e111f087ad52540099c741.png)
-
-
 ## Core Features
 
 `BarrageStore` delivers a complete barrage solution for your live streaming app. Core features include:
@@ -14,50 +11,19 @@ This document provides a comprehensive guide for iOS developers to quickly integ
 
 - Inserting system tips into the local message list (for example, "Welcome XX to the live room").
 
-
 ## Core Concepts
-<table>
-<tr>
-<td rowspan="1" colSpan="1" >**Core Concept**</td>
-
-<td rowspan="1" colSpan="1" >**Type**</td>
-
-<td rowspan="1" colSpan="1" >**Core Responsibility & Description**</td>
-</tr>
-
-<tr>
-<td rowspan="1" colSpan="1" >[Barrage](https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/barrage)</td>
-
-<td rowspan="1" colSpan="1" >struct</td>
-
-<td rowspan="1" colSpan="1" >Represents the data model for a single barrage message. Contains all essential information such as sender (sender), message content (textContent or data), message type (messageType), and more.</td>
-</tr>
-
-<tr>
-<td rowspan="1" colSpan="1" >[BarrageState](https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/barragestate)</td>
-
-<td rowspan="1" colSpan="1" >struct</td>
-
-<td rowspan="1" colSpan="1" >Represents the current state of the barrage module. The main property, messageList, is an array of [Barrage] storing all barrage messages in chronological order for the current live room. This serves as the data source for UI rendering.</td>
-</tr>
-
-<tr>
-<td rowspan="1" colSpan="1" >[BarrageStore](https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/barragestore)</td>
-
-<td rowspan="1" colSpan="1" >class</td>
-
-<td rowspan="1" colSpan="1" >The core management class for barrage functionality. Use it to send messages (sendTextMessage, sendCustomMessage), and subscribe to its state property to receive all barrage message updates.</td>
-</tr>
-</table>
-
+| **Core Concept** | **Type** | **Core Responsibility & Description** |
+| --- | --- | --- |
+| [Barrage](https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/barrage) | struct | Represents the data model for a single barrage message. Contains all essential information such as sender (sender), message content (textContent or data), message type (messageType), and more. |
+| [BarrageState](https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/barragestate) | struct | Represents the current state of the barrage module. The main property, messageList, is an array of [Barrage] storing all barrage messages in chronological order for the current live room. This serves as the data source for UI rendering. |
+| [BarrageStore](https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/barragestore) | class | The core management class for barrage functionality. Use it to send messages (sendTextMessage, sendCustomMessage), and subscribe to its state property to receive all barrage message updates. |
 
 ## Implementation
 
 ### Step 1: Component Integration
-- **Video Live Streaming**: Please refer to [Quick Start](https://write.woa.com/document/194571606121816064) to integrate AtomicXCore. Quick Start to
-
-- **Voice Chat Room**: Please refer to [Quick Start](https://write.woa.com/document/194571595685527552) to integrate AtomicXCore.
+- **Video Live Streaming**: Please refer to Quick Start to integrate AtomicXCore. Quick Start to
 
+- **Voice Chat Room**: Please refer to Quick Start to integrate AtomicXCore.
 
 ### Step 2: Initialize and Listen for Barrage
 
@@ -71,10 +37,10 @@ class BarrageManager {
     private let liveId: String
     private let barrageStore: BarrageStore
     private var cancellables = Set<AnyCancellable>()
-    
+
     // Publisher for the complete message list, for UI layer subscription
     let messagesPublisher = PassthroughSubject<[Barrage], Never>()
-    
+
     init(liveId: String) {
         self.liveId = liveId
         // 1. Obtain the BarrageStore singleton for the given liveId
@@ -82,7 +48,7 @@ class BarrageManager {
         // 2. Start listening for barrage messages immediately after initialization
         subscribeToBarrageUpdates()
     }
-    
+
     private func subscribeToBarrageUpdates() {
         barrageStore.state
             .subscribe() // Subscribe to all BarrageState changes
@@ -109,7 +75,7 @@ extension BarrageManager {
             print("Barrage content cannot be empty")
             return
         }
-        
+
         // Send the message using the core API
         barrageStore.sendTextMessage(text: text, extensionInfo: nil) { result in
             // Handle the result in the callback, e.g., show a prompt to the user
@@ -125,40 +91,11 @@ extension BarrageManager {
 ```
 
 #### API Parameters
-<table>
-<tr>
-<td rowspan="1" colSpan="1" >**Parameter**</td>
-
-<td rowspan="1" colSpan="1" >**Type**</td>
-
-<td rowspan="1" colSpan="1" >**Description**</td>
-</tr>
-
-<tr>
-<td rowspan="1" colSpan="1" >`text`</td>
-
-<td rowspan="1" colSpan="1" >`String`</td>
-
-<td rowspan="1" colSpan="1" >The text content to send.</td>
-</tr>
-
-<tr>
-<td rowspan="1" colSpan="1" >`extensionInfo`</td>
-
-<td rowspan="1" colSpan="1" >`[String: String]?`</td>
-
-<td rowspan="1" colSpan="1" >Additional extension information for business customization.</td>
-</tr>
-
-<tr>
-<td rowspan="1" colSpan="1" >`completion`</td>
-
-<td rowspan="1" colSpan="1" >`CompletionClosure?`</td>
-
-<td rowspan="1" colSpan="1" >Callback after sending is complete, containing the success or failure result.</td>
-</tr>
-</table>
-
+| **Parameter** | **Type** | **Description** |
+| --- | --- | --- |
+| `text` | `String` | The text content to send. |
+| `extensionInfo` | `[String: String]?` | Additional extension information for business customization. |
+| `completion` | `CompletionClosure?` | Callback after sending is complete, containing the success or failure result. |
 
 ### Step 4: Send Custom Barrage
 
@@ -169,7 +106,7 @@ extension BarrageManager {
     func sendGiftMessage(giftId: String, giftCount: Int) {
         // 1. Define a business-recognizable ID
         let businessId = "live_gift"
-        
+
         // 2. Encode business data as a JSON string
         let giftData: [String: Any] = ["gift_id": giftId, "gift_count": giftCount]
         guard let jsonData = try? JSONSerialization.data(withJSONObject: giftData),
@@ -177,7 +114,7 @@ extension BarrageManager {
             print("Failed to encode gift data as JSON")
             return
         }
-        
+
         // 3. Send the custom message using the core API
         barrageStore.sendCustomMessage(businessID: businessId, data: jsonString) { result in
             switch result {
@@ -192,40 +129,11 @@ extension BarrageManager {
 ```
 
 #### API Parameters
-<table>
-<tr>
-<td rowspan="1" colSpan="1" >**Parameter**</td>
-
-<td rowspan="1" colSpan="1" >**Type**</td>
-
-<td rowspan="1" colSpan="1" >**Description**</td>
-</tr>
-
-<tr>
-<td rowspan="1" colSpan="1" >`businessId`</td>
-
-<td rowspan="1" colSpan="1" >`String`</td>
-
-<td rowspan="1" colSpan="1" >Unique business identifier, e.g., "live_gift", used by the receiver to distinguish different custom messages.</td>
-</tr>
-
-<tr>
-<td rowspan="1" colSpan="1" >`data`</td>
-
-<td rowspan="1" colSpan="1" >`String`</td>
-
-<td rowspan="1" colSpan="1" >Business data, usually a JSON-formatted string.</td>
-</tr>
-
-<tr>
-<td rowspan="1" colSpan="1" >`completion`</td>
-
-<td rowspan="1" colSpan="1" >`CompletionClosure?`</td>
-
-<td rowspan="1" colSpan="1" >Callback after sending is complete.</td>
-</tr>
-</table>
-
+| **Parameter** | **Type** | **Description** |
+| --- | --- | --- |
+| `businessId` | `String` | Unique business identifier, e.g., "live_gift", used by the receiver to distinguish different custom messages. |
+| `data` | `String` | Business data, usually a JSON-formatted string. |
+| `completion` | `CompletionClosure?` | Callback after sending is complete. |
 
 ### Step 5: Insert Local Tip Message
 
@@ -239,7 +147,7 @@ extension BarrageManager {
         welcomeTip.messageType = .text // Reuse the text type for display
         welcomeTip.textContent = "Welcome \(user.userName) to the live room!"
         // sender can be left empty or set to a system user identifier
-        
+
         // 2. Insert the message into the local list
         barrageStore.appendLocalTip(message: welcomeTip)
     }
@@ -247,24 +155,9 @@ extension BarrageManager {
 ```
 
 #### API Parameters
-<table>
-<tr>
-<td rowspan="1" colSpan="1" >**Parameter**</td>
-
-<td rowspan="1" colSpan="1" >**Type**</td>
-
-<td rowspan="1" colSpan="1" >**Description**</td>
-</tr>
-
-<tr>
-<td rowspan="1" colSpan="1" >message</td>
-
-<td rowspan="1" colSpan="1" >Barrage</td>
-
-<td rowspan="1" colSpan="1" >The message object to insert locally. The SDK appends this message to the messageList in BarrageState.</td>
-</tr>
-</table>
-
+| **Parameter** | **Type** | **Description** |
+| --- | --- | --- |
+| message | Barrage | The message object to insert locally. The SDK appends this message to the messageList in BarrageState. |
 
 ### Step 6: Manage User Speaking Permissions (Mute and Unmute)
 
@@ -305,7 +198,7 @@ import AtomicXCore
 let liveListStore = LiveListStore.shared
 
 // 2. Get the current live room info and modify the global mute status
-var currentLiveInfo = liveListStore.state.value.currentLive 
+var currentLiveInfo = liveListStore.state.value.currentLive
 currentLiveInfo.isMessageDisable = true // true to enable global mute, false to disable
 
 // 3. Call the update API and specify the modify flag
@@ -400,7 +293,7 @@ class BarrageUIManager {
 
     private func refreshUIIfNeeded() {
         guard let fullList = self.latestMessageList, let tableView = self.tableView else { return }
-        self.latestMessageList = nil 
+        self.latestMessageList = nil
 
         // Only keep the latest N messages
         let cappedList = Array(fullList.suffix(self.capacity))
@@ -468,7 +361,7 @@ For detailed information on all public interfaces, properties, and methods of [B
 
 ### In addition to basic text barrages, we also want to implement richer styles such as "colored barrages" and "gift barrages." How can we achieve this?
 
-You can implement these features using custom messages with `sendCustomMessage`. 
+You can implement these features using custom messages with `sendCustomMessage`.
 
 **Implementation Steps**
 1. **Define the Data Structure**: Collaborate with your client and server teams to define the JSON structure for custom messages. For example, a colored barrage can be defined as:
@@ -480,7 +373,6 @@ You can implement these features using custom messages with `sendCustomMessage`.
 
 3. **Receiver**: Upon receiving a barrage message, check whether its messageType is `BarrageType.CUSTOM` and whether the `businessID` matches. If so, parse the data string (usually as JSON), and render your custom UI style based on the parsed data (such as `color`, `text`).
 
-
 ### If I call BarrageStore.create(liveID = "some_id") in different classes or files, will this create multiple instances and cause confusion?
 
 No. The internal mechanism of **AtomicXCore** ensures that as long as you pass in the same liveID, you always get the same `BarrageStore` instance for that live room. You do not need to manage singletons manually.
@@ -496,7 +388,6 @@ No. The internal mechanism of **AtomicXCore** ensures that as long as you pass i
 
 4. **Network issues**: Ensure the device's network connection is normal. Message sending depends on network connectivity.
 
-
 ### How can new viewers see historical barrage messages sent before they joined the live room?
 
 `AtomicXCore` supports retrieving historical chat messages, but you need to enable this feature in the **server console**. Once configured, the SDK handles everything automatically—no additional client code is required.
@@ -506,12 +397,8 @@ No. The internal mechanism of **AtomicXCore** ensures that as long as you pass i
 
 2. On the Live Configuration page, select **View Past Messages**, and set Previous Messages Viewable to specify the number of messages (up to a maximum of 50) that new viewers can see.
 
-
-   ![](https://write-document-release-1258344699.cos.ap-guangzhou.tencentcos.cn/100027202808/5ca7e8c2e20c11f095b0525400e889b2.png)
-
-
 #### **Step 2: Automatic Retrieval on the Client Side**
 
 After completing the above configuration, **no changes are needed** in your client code.
 
-When a new user joins the live room, `AtomicXCore` automatically retrieves the configured number of historical chat messages in the background. These messages are delivered to the UI layer through the `BarrageState` subscription channel, just like real-time messages. Your application will receive and display these historical chat messages in the same way as live messages.
+When a new user joins the live room, `AtomicXCore` automatically retrieves the configured number of historical chat messages in the background. These messages are delivered to the UI layer through the `BarrageState` subscription channel, just like real-time messages. Your application will receive and display these historical chat messages in the same way as live messages.