@tencent-rtc/mcp 1.3.8 → 1.4.0

package/resource/doc/livekit/{live → core-sdk/live}/android/live-co-guest-interaction.md

@@ -7,48 +7,18 @@
 
 - **Host Invites to Join**: The host can invite any audience member in the live room to co-host.
 
-
 ## Core Concepts
-<table>
-<tr>
-<td rowspan="1" colSpan="1" >**Core Concept**</td>
-
-<td rowspan="1" colSpan="1" >**Core Responsibilities**</td>
-
-<td rowspan="1" colSpan="1" >**Key APIs / Properties**</td>
-</tr>
-
-<tr>
-<td rowspan="1" colSpan="1" >`CoGuestStore`</td>
-
-<td rowspan="1" colSpan="1" >Manages the entire signaling workflow for viewer-host interaction (Apply, Invite, Accept, Reject, Disconnect) and maintains real-time state of related user lists.</td>
-
-<td rowspan="1" colSpan="1" >- `coGuestState`: A read-only StateFlowcontaining `connected` (current co-guests), `applicants` (pending applications), and `invitees` (pending invitations).<br>- `applyForSeat()`: Viewer applies to become a co-guest.<br>- `inviteToSeat()`: Host invites a viewer to take a seat.<br>- `acceptApplication()`: Host accepts a link mic application.<br>- `disconnect():` Terminates the connection.</td>
-</tr>
-
-<tr>
-<td rowspan="1" colSpan="1" >`HostListener`</td>
-
-<td rowspan="1" colSpan="1" >Used by the UI layer to respond to events such as "Received viewer application" or "Viewer accepted invitation".</td>
-
-<td rowspan="1" colSpan="1" >- `onGuestApplicationReceived()`: Triggered when a viewer applies for a seat.<br>- `onHostInvitationResponded()`: Triggered when a viewer responds to an invitation.</td>
-</tr>
-
-<tr>
-<td rowspan="1" colSpan="1" >`GuestListener`</td>
-
-<td rowspan="1" colSpan="1" >Used by the UI layer to respond to events such as "Received host invitation", "Application approved", or "Kicked off seat".</td>
-
-<td rowspan="1" colSpan="1" >- `onHostInvitationReceived()`: Triggered when the host sends an invitation.<br>- `onGuestApplicationResponded()`: Triggered when the host processes an application (Accept/Reject).<br>- `onKickedOffSeat()`: Triggered when kicked off the seat by the host.</td>
-</tr>
-</table>
-
+| **Core Concept** | **Core Responsibilities** | **Key APIs / Properties** |
+| --- | --- | --- |
+| `CoGuestStore` | Manages the entire signaling workflow for viewer-host interaction (Apply, Invite, Accept, Reject, Disconnect) and maintains real-time state of related user lists. | - `coGuestState`: A read-only StateFlowcontaining `connected` (current co-guests), `applicants` (pending applications), and `invitees` (pending invitations).<br>- `applyForSeat()`: Viewer applies to become a co-guest.<br>- `inviteToSeat()`: Host invites a viewer to take a seat.<br>- `acceptApplication()`: Host accepts a link mic application.<br>- `disconnect():` Terminates the connection. |
+| `HostListener` | Used by the UI layer to respond to events such as "Received viewer application" or "Viewer accepted invitation". | - `onGuestApplicationReceived()`: Triggered when a viewer applies for a seat.<br>- `onHostInvitationResponded()`: Triggered when a viewer responds to an invitation. |
+| `GuestListener` | Used by the UI layer to respond to events such as "Received host invitation", "Application approved", or "Kicked off seat". | - `onHostInvitationReceived()`: Triggered when the host sends an invitation.<br>- `onGuestApplicationResponded()`: Triggered when the host processes an application (Accept/Reject).<br>- `onKickedOffSeat()`: Triggered when kicked off the seat by the host. |
 
 ## Implementation
 
 ### Step 1: Component Integration
 
-Refer to [Quick Start](https://write.woa.com/document/194571606056804352) to integrate AtomicXCore and complete the setup of LiveCoreView.
+Refer to Quick Start to integrate AtomicXCore and complete the setup of LiveCoreView.
 
 ### Step 2: Implement Audience Request to Join
 
@@ -57,16 +27,15 @@ Refer to [Quick Start](https://write.woa.com/document/194571606056804352) to int
 As an audience member, your primary tasks are to **initiate a request, handle the host's response, and leave the seat when desired.**
 1. **Initiate a Co-hosting Request**
 
-
    When the user taps the "Request to Join" button, call the `applyForSeat` method.
 
    ``` kotlin
    import io.trtc.tuikit.atomicxcore.api.live.CoGuestStore
    import io.trtc.tuikit.atomicxcore.api.CompletionHandler
-   
+
    val liveId = "Room ID"
    val guestStore = CoGuestStore.create(liveId)
-   
+
    // User clicks "Request to Join"
    fun requestToConnect() {
        // timeout: Request timeout in seconds, e.g., 30
@@ -78,7 +47,7 @@ As an audience member, your primary tasks are to **initiate a request, handle th
                override fun onSuccess() {
                    println("Co-hosting request sent, waiting for host response...")
                }
-   
+
                override fun onFailure(code: Int, desc: String) {
                    println("Failed to send request: $desc")
                }
@@ -88,7 +57,6 @@ As an audience member, your primary tasks are to **initiate a request, handle th
    ```
 2. **Listen for Host Response**
 
-
    Add a `GuestListener` to receive the host's response.
 
    ``` kotlin
@@ -98,7 +66,7 @@ As an audience member, your primary tasks are to **initiate a request, handle th
    import io.trtc.tuikit.atomicxcore.api.live.CoGuestStore
    import io.trtc.tuikit.atomicxcore.api.live.GuestListener
    import io.trtc.tuikit.atomicxcore.api.live.LiveUserInfo
-   
+
    class YourActivity : AppCompatActivity() {
        val liveId = "Room ID"
        val guestStore = CoGuestStore.create(liveId)
@@ -117,12 +85,12 @@ As an audience member, your primary tasks are to **initiate a request, handle th
                }
            }
        }
-   
+
        override fun onCreate(savedInstanceState: Bundle?) {
            super.onCreate(savedInstanceState)
            guestStore.addGuestListener(guestListener)
        }
-   
+
        override fun onDestroy() {
            super.onDestroy()
            guestStore.removeGuestListener(guestListener)
@@ -131,7 +99,6 @@ As an audience member, your primary tasks are to **initiate a request, handle th
    ```
 3. **Leave the Seat**
 
-
    When the co-hosting audience member wants to end the interaction, call `disconnect` to return to audience status.
 
    ``` kotlin
@@ -141,7 +108,7 @@ As an audience member, your primary tasks are to **initiate a request, handle th
            override fun onSuccess() {
                println("Successfully left the seat")
            }
-   
+
            override fun onFailure(code: Int, desc: String) {
                println("Failed to leave seat: $desc")
            }
@@ -150,7 +117,6 @@ As an audience member, your primary tasks are to **initiate a request, handle th
    ```
 4. **(Optional) Cancel Request**
 
-
    To withdraw a pending request before the host responds, call `cancelApplication`.
 
    ``` kotlin
@@ -160,7 +126,7 @@ As an audience member, your primary tasks are to **initiate a request, handle th
            override fun onSuccess() {
                println("Request cancelled")
            }
-   
+
            override fun onFailure(code: Int, desc: String) {
                println("Failed to cancel request: $desc")
            }
@@ -173,7 +139,6 @@ As an audience member, your primary tasks are to **initiate a request, handle th
 As a host, your main responsibilities are to **receive requests, display the applicant list, and process requests**.
 1. **Listen for New Co-hosting Requests**
 
-
    Add a `HostListener` to be notified when a new audience request arrives.
 
    ``` kotlin
@@ -182,7 +147,7 @@ As a host, your main responsibilities are to **receive requests, display the app
    import io.trtc.tuikit.atomicxcore.api.live.CoGuestStore
    import io.trtc.tuikit.atomicxcore.api.live.HostListener
    import io.trtc.tuikit.atomicxcore.api.live.LiveUserInfo
-   
+
    class YourActivity : AppCompatActivity() {
        val liveId = "Room ID"
        val guestStore = CoGuestStore.create(liveId)
@@ -192,13 +157,13 @@ As a host, your main responsibilities are to **receive requests, display the app
                // Update UI, e.g., show a badge on the "Request List" button
            }
        }
-   
+
        override fun onCreate(savedInstanceState: Bundle?) {
            super.onCreate(savedInstanceState)
            // Add listener
            guestStore.addHostListener(hostListener)
        }
-   
+
        override fun onDestroy() {
            super.onDestroy()
            // Remove listener
@@ -208,17 +173,16 @@ As a host, your main responsibilities are to **receive requests, display the app
    ```
 2. **Display Request List**
 
-
    `CoGuestStore` maintains the current list of applicants in real time. Subscribe to this list to update your UI.
 
    ``` kotlin
    class YourActivity : AppCompatActivity() {
        val liveId = "Room ID"
        val guestStore = CoGuestStore.create(liveId)
-   
+
        override fun onCreate(savedInstanceState: Bundle?) {
            super.onCreate(savedInstanceState)
-   
+
            // Subscribe to applicant list updates
            lifecycleScope.launch {
                guestStore.coGuestState.applicants.collect { applicants ->
@@ -232,7 +196,6 @@ As a host, your main responsibilities are to **receive requests, display the app
    ```
 3. **Process Co-hosting Requests**
 
-
    When you select an audience member and choose "Accept" or "Reject", call the corresponding method.
 
    ``` kotlin
@@ -242,20 +205,20 @@ As a host, your main responsibilities are to **receive requests, display the app
            override fun onSuccess() {
                println("Accepted $userId's request. They are joining the stage.")
            }
-   
+
            override fun onFailure(code: Int, desc: String) {
                println("Failed to accept request: $desc")
            }
        })
    }
-   
+
    // Host taps "Reject"
    fun reject(userId: String) {
        guestStore.rejectApplication(userId, object : CompletionHandler {
            override fun onSuccess() {
                println("Rejected $userId's request")
            }
-   
+
            override fun onFailure(code: Int, desc: String) {
                println("Failed to reject request: $desc")
            }
@@ -268,7 +231,6 @@ As a host, your main responsibilities are to **receive requests, display the app
 #### Host-Side Implementation
 1. **Send Invitation to Audience**
 
-
    When the host selects an audience member and taps "Invite to Co-host", call the `inviteToSeat` method.
 
    ``` kotlin
@@ -284,7 +246,7 @@ As a host, your main responsibilities are to **receive requests, display the app
                override fun onSuccess() {
                    println("Invitation sent to $userId. Waiting for response...")
                }
-   
+
                override fun onFailure(code: Int, desc: String) {
                    println("Failed to send invitation: $desc")
                }
@@ -294,7 +256,6 @@ As a host, your main responsibilities are to **receive requests, display the app
    ```
 2. **Listen for Audience Response**
 
-
    Listen for the `onHostInvitationResponded` event via `HostListener`.
 
    ``` kotlin
@@ -311,7 +272,6 @@ As a host, your main responsibilities are to **receive requests, display the app
 #### Audience-Side Implementation
 1. **Receive Host Invitation**
 
-
    Listen for the `onHostInvitationReceived` event via `GuestListener`.
 
    ``` kotlin
@@ -324,12 +284,11 @@ As a host, your main responsibilities are to **receive requests, display the app
    ```
 2. **Respond to Invitation**
 
-
    After the user makes a selection, call the corresponding method.
 
    ``` kotlin
    val inviterId = "Inviting Host ID" // Obtained from onHostInvitationReceived
-   
+
    // User taps "Accept"
    fun accept() {
        guestStore.acceptInvitation(inviterId, object : CompletionHandler {
@@ -338,20 +297,20 @@ As a host, your main responsibilities are to **receive requests, display the app
                DeviceStore.shared().openLocalCamera(true, completion = null)
                DeviceStore.shared().openLocalMicrophone(completion = null)
            }
-   
+
            override fun onFailure(code: Int, desc: String) {
                println("Failed to accept invitation: $desc")
            }
        })
    }
-   
+
    // User taps "Reject"
    fun reject() {
        guestStore.rejectInvitation(inviterId, object : CompletionHandler {
            override fun onSuccess() {
                println("Invitation rejected")
            }
-   
+
            override fun onFailure(code: Int, desc: String) {
                println("Failed to reject invitation: $desc")
            }
@@ -361,10 +320,7 @@ As a host, your main responsibilities are to **receive requests, display the app
 
 ### Run and Test
 
-After integrating the above features, use two audience members and a host to test co-hosting. For example, Audience A enables both camera and microphone, while Audience B enables only the microphone. The result is shown below. For UI customization, see [Refining UI Details](https://write.woa.com/#.E5.AE.8C.E5.96.84-ui-.E7.BB.86.E8.8A.82).
-
-![](https://write-document-release-1258344699.cos.ap-guangzhou.tencentcos.cn/100027182498/6464f319c6b711f0a4a55254001c06ec.png)
-
+After integrating the above features, use two audience members and a host to test co-hosting. For example, Audience A enables both camera and microphone, while Audience B enables only the microphone. The result is shown below. For UI customization, see Refining UI Details.
 
 ## Refining UI Details
 
@@ -374,16 +330,13 @@ Use the "slot" feature provided by the `VideoViewAdapter` interface to add custo
 
 #### Implementation Example
 
-![](https://write-document-release-1258344699.cos.ap-guangzhou.tencentcos.cn/100027182498/b28831bac6b711f0a7775254005ef0f7.png)
-
-
 #### Implementation
 
 > **Note：**
-> 
+>
 
 > You can also refer to the [widgets](https://github.com/Tencent-RTC/TUIKit_Android/tree/main/live/tuilivekit/src/main/java/com/trtc/uikit/livekit/features/anchorboardcast/view/coguest/widgets) directory in the open-source TUILiveKit project for a complete implementation.
-> 
+>
 
 - **Step 1**: Create the foreground view `CustomSeatView` to display user info above the video stream.
 
@@ -394,21 +347,21 @@ Use the "slot" feature provided by the `VideoViewAdapter` interface to add custo
    import android.view.ViewGroup
    import android.widget.LinearLayout
    import android.widget.TextView
-   
+
    // Custom floating user info view (foreground)
    class CustomSeatView(context: Context) : LinearLayout(context) {
        private val nameLabel: TextView
-   
+
        init {
            orientation = VERTICAL
            gravity = Gravity.BOTTOM or Gravity.START
            setBackgroundColor(Color.parseColor("#80000000")) // Semi-transparent black background
-   
+
            nameLabel = TextView(context).apply {
                setTextColor(Color.WHITE)
                textSize = 14f
            }
-   
+
            addView(nameLabel, LayoutParams(
                ViewGroup.LayoutParams.WRAP_CONTENT,
                ViewGroup.LayoutParams.WRAP_CONTENT
@@ -416,7 +369,7 @@ Use the "slot" feature provided by the `VideoViewAdapter` interface to add custo
                setMargins(20, 0, 0, 20) // Left margin 20, bottom margin 20
            })
        }
-   
+
        fun setUserName(userName: String) {
            nameLabel.text = userName
        }
@@ -431,24 +384,24 @@ Use the "slot" feature provided by the `VideoViewAdapter` interface to add custo
    import android.view.ViewGroup
    import android.widget.ImageView
    import android.widget.LinearLayout
-   
+
    // Custom avatar placeholder view (background)
    class CustomAvatarView(context: Context) : LinearLayout(context) {
        private val avatarImageView: ImageView
-   
+
        init {
            orientation = VERTICAL
            gravity = Gravity.CENTER
            setBackgroundColor(Color.TRANSPARENT)
-   
+
            avatarImageView = ImageView(context).apply {
                setColorFilter(Color.GRAY)
                scaleType = ImageView.ScaleType.CENTER_CROP
            }
-   
+
            addView(avatarImageView, LayoutParams(120, 120)) // 60dp * 2 = 120px
        }
-   
+
        fun setUserAvatar(avatarUrl: String) {
            // Load user avatar here, e.g., using Glide
            // Glide.with(context).load(avatarUrl).into(avatarImageView)
@@ -464,18 +417,18 @@ Use the "slot" feature provided by the `VideoViewAdapter` interface to add custo
    import com.tencent.cloud.tuikit.engine.room.TUIRoomDefine
    import io.trtc.tuikit.atomicxcore.api.view.VideoViewAdapter
    import io.trtc.tuikit.atomicxcore.api.view.ViewLayer
-   
+
    // Implement VideoViewAdapter in your Activity
    class YourActivity : AppCompatActivity(), VideoViewAdapter {
-   
+
        // ... other code ...
-   
+
        // Implement the interface method for both viewLayer types
        override fun createCoGuestView(userInfo: TUIRoomDefine.SeatFullInfo?, viewLayer: ViewLayer?): View? {
            userInfo ?: return null
            val userId = userInfo.userId
            if (userId.isNullOrEmpty()) return null
-   
+
            return when (viewLayer) {
                ViewLayer.FOREGROUND -> {
                    // Show foreground view when camera is on
@@ -492,7 +445,7 @@ Use the "slot" feature provided by the `VideoViewAdapter` interface to add custo
                else -> null
            }
        }
-   
+
        override fun onCreate(savedInstanceState: Bundle?) {
            super.onCreate(savedInstanceState)
            // Set the adapter
@@ -502,110 +455,24 @@ Use the "slot" feature provided by the `VideoViewAdapter` interface to add custo
    ```
 
 #### Parameter Description:
-<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" >`seatInfo`</td>
-
-<td rowspan="1" colSpan="1" >`SeatFullInfo?`</td>
-
-<td rowspan="1" colSpan="1" >Seat information object, containing detailed information about the user on the seat</td>
-</tr>
-
-<tr>
-<td rowspan="1" colSpan="1" >`seatInfo.userId`</td>
-
-<td rowspan="1" colSpan="1" >`String`</td>
-
-<td rowspan="1" colSpan="1" >ID of the user on the seat</td>
-</tr>
-
-<tr>
-<td rowspan="1" colSpan="1" >`seatInfo.userName`</td>
-
-<td rowspan="1" colSpan="1" >`String`</td>
-
-<td rowspan="1" colSpan="1" >Nickname of the user on the seat</td>
-</tr>
-
-<tr>
-<td rowspan="1" colSpan="1" >`seatInfo.userAvatar`</td>
-
-<td rowspan="1" colSpan="1" >`String`</td>
-
-<td rowspan="1" colSpan="1" >Avatar URL of the user on the seat</td>
-</tr>
-
-<tr>
-<td rowspan="1" colSpan="1" >`seatInfo.userMicrophoneStatus`</td>
-
-<td rowspan="1" colSpan="1" >`DeviceStatus`</td>
-
-<td rowspan="1" colSpan="1" >Microphone status of the user on the seat</td>
-</tr>
-
-<tr>
-<td rowspan="1" colSpan="1" >`seatInfo.userCameraStatus`</td>
-
-<td rowspan="1" colSpan="1" >`DeviceStatus`</td>
-
-<td rowspan="1" colSpan="1" >Camera status of the user on the seat</td>
-</tr>
-
-<tr>
-<td rowspan="1" colSpan="1" >`viewLayer`</td>
-
-<td rowspan="1" colSpan="1" >`ViewLayer`</td>
-
-<td rowspan="1" colSpan="1" >View layer enum:<br>- `FOREGROUND`: Foreground widget view, always displayed on top of the video<br>- `BACKGROUND`: Background widget view, displayed below the foreground view, only shown when the user has no video stream (e.g., camera is off); typically used for the user's avatar or a placeholder image</td>
-</tr>
-</table>
-
+| **Parameter** | **Type** | **Description** |
+| --- | --- | --- |
+| `seatInfo` | `SeatFullInfo?` | Seat information object, containing detailed information about the user on the seat |
+| `seatInfo.userId` | `String` | ID of the user on the seat |
+| `seatInfo.userName` | `String` | Nickname of the user on the seat |
+| `seatInfo.userAvatar` | `String` | Avatar URL of the user on the seat |
+| `seatInfo.userMicrophoneStatus` | `DeviceStatus` | Microphone status of the user on the seat |
+| `seatInfo.userCameraStatus` | `DeviceStatus` | Camera status of the user on the seat |
+| `viewLayer` | `ViewLayer` | View layer enum:<br>- `FOREGROUND`: Foreground widget view, always displayed on top of the video<br>- `BACKGROUND`: Background widget view, displayed below the foreground view, only shown when the user has no video stream (e.g., camera is off); typically used for the user's avatar or a placeholder image |
 
 ## API Documentation
 
 For detailed information on all public interfaces, properties, and methods of [CoGuestStore](https://tencent-rtc.github.io/TUIKit_Android/-atomic-x%20-core%20-a-p-i/io.trtc.tuikit.atomicxcore.api.live/-co-guest-store/index.html) and related classes, refer to the official API documentation included with the [AtomicXCore](https://tencent-rtc.github.io/TUIKit_Android/index.html) framework. The relevant stores used in this guide include:
-<table>
-<tr>
-<td rowspan="1" colSpan="1" >**Store/Component**</td>
-
-<td rowspan="1" colSpan="1" >**Function Description**</td>
-
-<td rowspan="1" colSpan="1" >**API Documentation**</td>
-</tr>
-
-<tr>
-<td rowspan="1" colSpan="1" >LiveCoreView</td>
-
-<td rowspan="1" colSpan="1" >Core view component for live video stream display and interaction. Handles video rendering and widget management, supporting host streaming, audience co-hosting, host connections, and more.</td>
-
-<td rowspan="1" colSpan="1" >[API Documentation](https://tencent-rtc.github.io/TUIKit_Android/-atomic-x%20-core%20-a-p-i/io.trtc.tuikit.atomicxcore.api.view/-live-core-view/index.html)</td>
-</tr>
-
-<tr>
-<td rowspan="1" colSpan="1" >DeviceStore</td>
-
-<td rowspan="1" colSpan="1" >Audio and video device control: microphone (on/off, volume), camera (on/off, switch, quality), screen sharing, real-time device status monitoring.</td>
-
-<td rowspan="1" colSpan="1" >[API Documentation](https://tencent-rtc.github.io/TUIKit_Android/-atomic-x%20-core%20-a-p-i/io.trtc.tuikit.atomicxcore.api.device/-device-store/index.html)</td>
-</tr>
-
-<tr>
-<td rowspan="1" colSpan="1" >CoGuestStore</td>
-
-<td rowspan="1" colSpan="1" >Audience co-hosting management: request/invite/accept/reject co-hosting, permission control (microphone/camera), state synchronization.</td>
-
-<td rowspan="1" colSpan="1" >[API Documentation](https://tencent-rtc.github.io/TUIKit_Android/-atomic-x%20-core%20-a-p-i/io.trtc.tuikit.atomicxcore.api.live/-co-guest-store/index.html)</td>
-</tr>
-</table>
-
+| **Store/Component** | **Function Description** | **API Documentation** |
+| --- | --- | --- |
+| LiveCoreView | Core view component for live video stream display and interaction. Handles video rendering and widget management, supporting host streaming, audience co-hosting, host connections, and more. | [API Documentation](https://tencent-rtc.github.io/TUIKit_Android/-atomic-x%20-core%20-a-p-i/io.trtc.tuikit.atomicxcore.api.view/-live-core-view/index.html) |
+| DeviceStore | Audio and video device control: microphone (on/off, volume), camera (on/off, switch, quality), screen sharing, real-time device status monitoring. | [API Documentation](https://tencent-rtc.github.io/TUIKit_Android/-atomic-x%20-core%20-a-p-i/io.trtc.tuikit.atomicxcore.api.device/-device-store/index.html) |
+| CoGuestStore | Audience co-hosting management: request/invite/accept/reject co-hosting, permission control (microphone/camera), state synchronization. | [API Documentation](https://tencent-rtc.github.io/TUIKit_Android/-atomic-x%20-core%20-a-p-i/io.trtc.tuikit.atomicxcore.api.live/-co-guest-store/index.html) |
 
 ## FAQs
 
@@ -620,7 +487,6 @@ The viewLayer parameter distinguishes between foreground and background widgets:
 
 - `BACKGROUND`: Background layer, displayed only when the user has no video stream (e.g., camera is off); typically used to show the user's avatar or a placeholder image.
 
-
 ### Why is my custom view not showing up?
 - **Check adapter settings**: Ensure you have called liveCoreView.setVideoViewAdapter(this) and set the adapter successfully.