@tencent-rtc/mcp 1.6.3 → 1.6.5

package/resource/integration/livekit/preset/live/ios/live-host-integration.md

@@ -0,0 +1,369 @@
+UILiveKit's host streaming page offers a comprehensive, ready-to-use interface for live streaming scenarios. It enables rapid integration of essential features for hosts to start streaming, allowing you to efficiently build your live streaming workflow without the complexity of custom UI or business logic.
+
+> **Note:**
+>
+> This guide covers the host start process using UI components (including a complete interactive UI). If you prefer to build your own host interface with the Core SDK, see Host Start (Core SDK).
+>
+
+## Feature Overview
+- **Pre-Stream Preview:** Configure room name, background, video preview, beauty effects, audio effects, layout templates, and more before going live.
+
+- **Co-hosting Interaction:** Engage in real-time with audience members or other hosts across different live rooms during the stream.
+
+- **Audience Interaction:** Includes rich engagement features such as live comments and gift support.
+
+- **Live Room Management:** View the online user list and manage participants with actions like muting or removing users from the live room.
+
+   |**Pre-stream Setup**|**Co-Host Interaction**|**Audience Interaction**|**Live Room Management**|
+   |---------|---------|---------|---------|
+   ||||<br>|
+
+## Quick Integration
+
+### Step 1. Activate the Service
+
+Refer to the Activate Service document to  enable the **trial version** or activate the **Pro Edition** package.
+
+### Step 2. Integrate the SDK
+
+Refer to Preparations guide to integrate the `TUILiveKit` SDK.
+
+### Step 3. Add the Pre-stream Preparation Page
+
+The `AnchorPrepareView` component includes camera preview, audio effect settings, layout configuration, and other built-in features. Create and load the host streaming preparation view as shown below:
+
+【Swift】
+``` swift
+import UIKit
+import Snapkit
+import TUILiveKit
+import AtomicXCore
+
+// YourAnchorPrepareViewController represents the view controller for loading the host start page
+class YourAnchorPrepareViewController: UIViewController {
+    private let roomId = "testLiveId"
+
+    // Lazy load AnchorPrepareView
+    private lazy var prepareView: AnchorPrepareView = {
+        //  Pass roomId when initializing AnchorPrepareView
+        let view = AnchorPrepareView(roomId: roomId)
+        return view
+    }()
+
+    public override func viewDidLoad() {
+        super.viewDidLoad()
+        //  Add prepareView to the view
+        view.addSubview(prepareView)
+        prepareView.snp.makeConstraints { make in
+            make.edges.equalToSuperview()
+        }
+    }
+}
+```
+
+### Step 4. Add the Host Streaming Page
+
+The `AnchorView` component brings together audio/video streaming, audience co-hosting, interactive features, and live room management. Simply create and load `AnchorView` as shown below:
+
+【Swift】
+``` swift
+import UIKit
+import Snapkit
+import TUILiveKit
+import AtomicXCore
+
+// YourAnchorPrepareViewController represents the view controller for loading the host start page
+class YourAnchorViewController: UIViewController {
+    // Core view component
+    private let coreView: LiveCoreView
+
+    //  Declare anchorView instance
+    private let anchorView: AnchorView
+
+    public init(liveInfo: LiveInfo, coreView: LiveCoreView? = nil, behavior: RoomBehavior = .createRoom) {
+        if let coreView = coreView {
+            self.coreView = coreView
+        } else {
+            self.coreView = LiveCoreView(viewType: .pushView)
+        }
+        //  Instantiate the host start page
+        self.anchorView = AnchorView(liveInfo: liveInfo, coreView: self.coreView, behavior: behavior)
+        super.init(nibName: nil, bundle: nil)
+    }
+
+    required init?(coder: NSCoder) {
+        fatalError("init(coder:) has not been implemented")
+    }
+
+    public override func viewDidLoad() {
+        super.viewDidLoad()
+        //  Add anchorView to the view
+        view.addSubview(anchorView)
+        anchorView.snp.makeConstraints { make in
+            make.edges.equalToSuperview()
+        }
+    }
+}
+```
+
+### Step 5. Event Callback Customization
+
+AnchorView supports a delegate (AnchorViewDelegate) for listening to core lifecycle events such as successful live start, stream end with statistics, floating window clicks, and more. Set the delegate after creating AnchorView in Step 4:
+
+|Method|Description|
+|---------|---------|
+|func onStartLiving()|Called when the host has successfully started streaming (room created/joined, streaming started).|
+|func onEndLiving(state: AnchorState)|Called when the host ends the stream. state includes live statistics: totalDuration (duration), totalViewers(audience count), totalMessageSent (live comments), totalGiftCoins (gift revenue), totalGiftUniqueSenders (gifters), totalLikesReceived (likes), liveEndedReason (end reason)—useful for displaying the live summary page.|
+|func onClickFloatWindow()|Called when the user clicks the floating window.|
+
+``` swift
+import UIKit
+import Snapkit
+import TUILiveKit
+import AtomicXCore
+
+// YourAnchorViewController handles loading the host start streaming page
+class YourAnchorViewController: UIViewController {
+    // Core view component
+    private let coreView: LiveCoreView
+    private let liveID: String
+    // AnchorView instance
+    private let anchorView: AnchorView
+
+    public init(liveInfo: LiveInfo, coreView: LiveCoreView? = nil, behavior: RoomBehavior = .createRoom) {
+        if let coreView = coreView {
+            self.coreView = coreView
+        } else {
+            self.coreView = LiveCoreView(viewType: .pushView)
+        }
+        self.liveID = liveInfo.liveID
+        // Initialize the host start streaming page
+        self.anchorView = AnchorView(liveInfo: liveInfo, coreView: self.coreView, behavior: behavior)
+        super.init(nibName: nil, bundle: nil)
+        // Set delegate to listen for host page events
+        anchorView.delegate = self
+    }
+
+    required init?(coder: NSCoder) {
+        fatalError("init(coder:) has not been implemented")
+    }
+
+    public override func viewDidLoad() {
+        super.viewDidLoad()
+        // Add anchorView to the view
+        view.addSubview(anchorView)
+        anchorView.snp.makeConstraints { make in
+            make.edges.equalToSuperview()
+        }
+    }
+}
+
+// Implement AnchorViewDelegate callbacks
+extension YourAnchorViewController: AnchorViewDelegate {
+    // Host has successfully started streaming
+    func onStartLiving() {
+    }
+
+    // Host ends the stream, display the SDK built-in live summary page
+    func onEndLiving(state: AnchorState) {
+        let endInfo = AnchorEndStatisticsViewInfo(roomId: liveID,
+                                                  liveDuration: state.totalDuration,
+                                                  viewCount: state.totalViewers,
+                                                  messageCount: state.totalMessageSent,
+                                                  giftTotalCoins: state.totalGiftCoins,
+                                                  giftTotalUniqueSender: state.totalGiftUniqueSenders,
+                                                  likeTotalUniqueSender: state.totalLikesReceived,
+                                                  liveEndedReason: state.liveEndedReason)
+        let anchorEndView = AnchorEndStatisticsView(endViewInfo: endInfo)
+        anchorEndView.delegate = self
+        view.addSubview(anchorEndView)
+        anchorEndView.snp.makeConstraints { make in
+            make.edges.equalToSuperview()
+        }
+    }
+
+    // User clicked the floating window
+    func onClickFloatWindow() {
+        FloatWindow.shared.showFloatWindow(controller: self, provider: self)
+    }
+}
+
+// Implement FloatWindowProvider callbacks
+extension YourAnchorViewController: FloatWindowProvider {
+    public func getRoomId() -> String {
+        liveID
+    }
+
+    public func getOwnerId() -> String {
+        LiveListStore.shared.state.value.currentLive.liveOwner.userID
+    }
+
+    public func getCoreView() -> AtomicXCore.LiveCoreView {
+        coreView
+    }
+
+    public func relayoutCoreView() {
+        anchorView.relayoutCoreView()
+    }
+
+    public func getIsLinking() -> Bool {
+        let connectedSeats = CoGuestStore.create(liveID: liveID).state.value.connected
+        let selfUserID = LoginStore.shared.state.value.loginUserInfo?.userID ?? ""
+        return connectedSeats.contains(where: { $0.userID == selfUserID })
+    }
+}
+```
+
+### Step 6. Navigate from Preparation Page to Streaming Page
+
+Implement the delegate methods for the `AnchorPrepareView` component, as described in Step 3, to handle navigation from the preparation page to the host streaming page. Example code:
+
+【Swift】
+``` swift
+import UIKit
+import TUILiveKit
+import AtomicXCore
+
+//  Set delegate when initializing AnchorPrepareView
+class YourAnchorPrepareViewController: UIViewController {
+    private lazy var prepareView: AnchorPrepareView = {
+        let view = AnchorPrepareView(roomId: roomId)
+        // Set delegate
+        view.delegate = self
+        return view
+    }()
+}
+
+//  Implement AnchorPrepareViewDelegate callback
+extension YourAnchorPrepareViewController : AnchorPrepareViewDelegate {
+    // Handle start button click event
+    // - state: PrepareState encapsulates camera, audio effects, and other settings for the host start page. You only need to configure as shown in the sample code below.
+    public func onClickStartButton(state: PrepareState) {
+        // Navigate to the host start page
+        // Initialize live stream information
+        var liveInfo = LiveInfo(seatTemplate: .videoDynamicGrid9Seats)
+        // If you used Server APIs to pre-create the room, fill in the RoomId returned by the server here.
+        liveInfo.liveID = roomId
+        liveInfo.liveName = state.roomName
+        liveInfo.coverURL = state.coverUrl
+        liveInfo.isPublicVisible = state.privacyMode == .public
+        liveInfo.backgroundURL = state.coverUrl
+
+        // Instantiate your host start view controller
+        let anchorVC = YourAnchorViewController(liveInfo: liveInfo, coreView: prepareView.getCoreView())
+        anchorVC.modalPresentationStyle = .fullScreen
+
+        // Destroy the preparation page when going live: do not stack the streaming page on top of the preparation page
+        guard let presenter = presentingViewController else {
+            present(anchorVC, animated: false)
+            return
+        }
+        presenter.dismiss(animated: false) {
+            presenter.present(anchorVC, animated: false)
+        }
+    }
+
+    // Handle back button click event
+    public func onClickBackButton() {
+        if let nav = navigationController {
+            nav.popViewController(animated: true)
+        } else {
+            dismiss(animated: true)
+        }
+    }
+}
+```
+
+## Customize Your UI Layout
+
+TUILiveKit provides flexible options for customizing features and styles on both the preparation and streaming pages. You can adjust layouts or hide/show feature modules based on your business requirements.
+
+### Select Live Stream Layout Templates
+
+TUILiveKit includes **4 live stream layout templates**. Select your preferred style from the **"Layout"** option in the host preparation page UI:
+
+#### Layout Template Overview
+
+|**Layout**|**Dynamic Grid Layout**|**Floating Window Layout**|**Fixed Grid Layout**|**Fixed Floating Window Layout**|
+|---------|---------|---------|---------|---------|
+|**Template Value**|`.videoDynamicGrid9Seats`|`.videoDynamicFloat7Seats`|`.videoFixedGrid9Seats`|`.videoFixedFloat7Seats`|
+|**Description**|Default layout. The grid size adjusts dynamically based on the number of co-hosts.|Co-hosts are shown in floating windows.|The number of co-hosts is fixed. Each guest occupies a dedicated grid cell.|The number of co-hosts is fixed. Guests appear in fixed floating windows.|
+|**Preview**|||||
+
+### Customize Preparation Page
+
+Use the API on the `prepareView` created in Step 3 to hide the entire operation area or specific features on the preparation page.
+
+【Swift】
+``` swift
+import UIKit
+import Snapkit
+import TUILiveKit
+import AtomicXCore
+
+// YourAnchorPrepareViewController represents the view controller for loading the host start page
+class YourAnchorPrepareViewController: UIViewController {
+    private let roomId = "testLiveId"
+    private lazy var prepareView: AnchorPrepareView = {
+        let view = AnchorPrepareView(roomId: roomId)
+        view.delegate = self
+        return view
+    }()
+
+    public override func viewDidLoad() {
+        super.viewDidLoad()
+        // Add prepareView to the view
+        view.addSubview(prepareView)
+        prepareView.snp.makeConstraints { make in
+            make.edges.equalToSuperview()
+        }
+        // Customize feature area - Example: Hide beauty feature
+        prepareView.disableMenuBeauty(true)
+    }
+}
+```
+
+|**API**|**Description**|
+|---------|---------|
+|`disableFeatureMenu(true)`|Hide the entire feature area|
+|`disableMenuBeauty(true)`|Hide the beauty button|
+|`disableMenuAudioEffect(true)`|Hide the audio effect button|
+|`disableMenuSwitchCamera(true)`|Hide the camera switch button|
+
+### Customize Host Streaming Page UI
+- For host UI customization, refer to Host Core Page. Modify styles and add custom business components in `AnchorView`.
+
+- To adjust video stream widgets, see Adjust Video Stream Widgets. Update display elements such as names and avatars on video slots within `AnchorView`.
+
+### Customize Texts
+
+TUILiveKit manages UI text through the [Apple Strings Catalog](https://developer.apple.com/documentation/xcode/localizing-and-varying-text-with-a-string-catalog), allowing you to visually edit copywriting with Xcode's graphical tools.
+
+> **Note：**
+>
+> [Apple Strings Catalog](https://developer.apple.com/documentation/xcode/localizing-and-varying-text-with-a-string-catalog) (.xcstrings) is a localization format introduced in Xcode 15. It supports structured formats for plurals, device-specific variants, and more. This is now the recommended approach for managing localization in iOS and macOS apps.
+>
+
+### Customize Icons
+
+TUILiveKit uses `TUILiveKit.xcassets` to manage UI image resources. Customize icons for your interface quickly using Xcode's graphical asset tools.
+
+## Next Steps
+
+Congratulations! You have successfully integrated the **host streaming** feature. Next, you can add capabilities such as **audience viewing**, **live stream list**, and **gift system**. See the table below for more information:
+
+|**Feature**|**Description**|**Integration Guide**|
+|---------|---------|---------|
+|**Audience Viewing**|Allow audience to join the host's live room and watch the stream, including audience co-hosting, live room info, online audience list, and live comments display.|Audience Viewing|
+|**Live Stream List**|Show the live stream list interface and features, including live stream list and room info display.|Live Stream List|
+|**Gift System**|Configure custom gift assets, integrate billing, enable PK interactions, and more.|Gift System|
+
+## FAQs
+
+### No video after starting the stream?
+
+Open your phone's **Settings** > **App** > **Camera** and verify that camera permissions are enabled. See the image below:
+
+### Unable to start streaming after clicking the start button, showing "Not logged in"?
+
+Review the Login Guide and confirm that the login feature has been integrated.

package/resource/integration/livekit/preset/live/ios/live-list-integration.md

@@ -0,0 +1,229 @@
+## Feature Preview
+
+This document provides a detailed introduction to the **Live Stream List Page** in TUILiveKit. You can directly integrate our pre-built live stream list page into your existing project, or deeply customize the page style, layout, and features according to your specific needs.
+- **Double-Column Waterfall Flow**: Default view, simultaneously displaying previews for 2 live rooms.
+
+- **Single-Column Waterfall Flow**: Default view, simultaneously displaying a preview for 1 live room.
+
+| <strong>Double-Column Waterfall Flow</strong> | <strong>Single-Column Waterfall Flow</strong> |
+| --- | --- |
+|  | ### |
+
+   > **Note:**
+   >
+   > When previewing live room screens, the preview duration is counted into the viewer's audio/video duration. For detailed billing information, please refer to [Pricing](https://www.tencentcloud.com/document/product/647/66078).
+   >
+
+## Quick Start
+
+### Step 1. Activate the Service
+
+Refer to the Activate Service document to enable the Free trial or official package.
+
+### Step 2. Code Integration
+
+Refer to  Preparations  guide to integrate the TUILiveKit SDK.
+
+### Step 3. Add the Live Stream List Page
+
+The **LiveListView** component is a dedicated view for displaying the live stream list. It automatically pulls the live room list, supports different display styles (**single-column** and **double-column**).
+
+【Swift】
+``` swift
+// Example: YourLiveListViewController is the view controller representing your live stream list waterfall layout
+class YourLiveListViewController: UIViewController {
+
+    // 1. Declare liveListView as a member variable
+    //        - style: .doubleColumn // Two-column waterfall layout
+    //        - style: .singleColumn // Single-column waterfall layout
+    // Example shows a two-column waterfall layout, if needed input .singleColumn just
+    private let liveListView = LiveListView(style: .doubleColumn)
+
+    public override func viewDidLoad() {
+        super.viewDidLoad()
+        // 2. Add liveListView to view
+        view.addSubview(liveListView)
+        liveListView.snp.makeConstraints { make in
+            make.edges.equalToSuperview()
+        }
+        // 3. Set the click event delegate for the list
+        liveListView.itemClickDelegate = self
+    }
+}
+```
+
+### Step 4. Navigate to the Audience Viewing Page
+
+ You can customize the page navigation by setting a click listener. For audience viewing page implementation, see Audience Viewing:
+
+**Example Code**:
+
+【Swift】
+``` swift
+// Implement OnItemClickDelegate in your live stream list view controller, for example: YourLiveListViewController
+extension YourLiveListViewController: OnItemClickDelegate {
+
+    func onItemClick(liveInfo: LiveInfo, frame: CGRect) {
+        // 1. Instantiate your audience view controller
+        let audienceVC = YourAudienceViewController(roomId: liveInfo.roomId)
+        audienceVC.modalPresentationStyle = .fullScreen
+        // 2. Navigate to your audience view controller
+        present(audienceVC, animated: false)
+    }
+
+}
+```
+
+### Step 5. Optimizing Page Transitions for `LiveListView` Interaction
+
+To ensure a more complete and smooth experience during page transitions, the `LiveListView` component, combined with iOS page routing system attributes, provides the `refreshLiveList` and `onRouteToNextPage` methods. With just one line of code, you can optimize live list display and video stream playback. The optimization method is as follows:
+
+【Swift】
+``` swift
+// Implement in your live stream list view controller, for example: YourLiveListViewController
+class YourLiveListViewController: UIViewController {
+
+    override func viewDidAppear(_ animated: Bool) {
+        super.viewDidAppear(animated)
+        // refreshLiveList: Call this method in viewDidAppear to ensure getting the latest list every time returning to current page
+        liveListView.refreshLiveList()
+    }
+
+    override func viewWillDisappear(_ animated: Bool) {
+        super.viewWillDisappear(animated)
+        // onRouteToNextPage: Call this method in viewWillDisappear to stop the video stream playback on current live list page when entering another page
+        liveListView.onRouteToNextPage()
+    }
+}
+```
+
+## Customize Your UI Layout
+
+**TUILiveKit** provides flexible interfaces to customize the live list waterfall component. You can customize the data source and list item styles according to your business needs.
+
+### Customize Data Source
+
+If your backend has a separate live list data, you can customize the data source by implementing the `LiveListDataSource` interface instead of using the component's default list data.
+
+【Swift】
+``` swift
+// Example: YourLiveListViewController is the view controller representing your live stream list waterfall layout
+class YourLiveListViewController: UIViewController {
+
+    private let liveListView: LiveListView = LiveListView(style: .doubleColumn)
+
+    public override func viewDidLoad() {
+        super.viewDidLoad()
+        view.addSubview(liveListView)
+        liveListView.snp.makeConstraints { make in
+            make.edges.equalToSuperview()
+        }
+        liveListView.itemClickDelegate = self
+        // 1. Set custom data source agent
+        liveListView.dataSource = self
+    }
+}
+
+// 2. Implement custom data source agent: LiveListDataSource
+extension YourLiveListViewController: LiveListDataSource {
+
+    public func fetchLiveList(cursor: String, onSuccess: @escaping LiveListBlock, onError: @escaping TUIErrorBlock) {
+        // 3. Connect to your own backend business and return data to the UI component in the following format
+        var liveInfoList: [LiveInfo] = []
+        var liveInfo = LiveInfo()
+        liveInfo.roomId = "live_123456"
+        liveInfo.name = "live_123456"
+        liveInfoList.append(liveInfo)
+        let cursor = "aabbccdd"
+        onSuccess(cursor, liveInfoList)
+    }
+}
+```
+
+### Custom View
+
+The bottom of the waterfall list items displays the video stream or live cover by default. If you need to customize the UI elements at the top of the list items (such as the host's avatar, live title, etc.), you can do so by implementing the `LiveListViewAdapter` interface.
+
+【Swift】
+``` swift
+// Example: YourLiveListViewController is the view controller representing your live stream list waterfall layout
+class YourLiveListViewController: UIViewController {
+
+    private let liveListView: LiveListView = LiveListView(style: .doubleColumn)
+
+    public override func viewDidLoad() {
+        super.viewDidLoad()
+        view.addSubview(liveListView)
+        liveListView.snp.makeConstraints { make in
+            make.edges.equalToSuperview()
+        }
+        liveListView.itemClickDelegate = self
+        liveListView.dataSource = self
+        // 1. Set adapter
+        liveListView.adapter = self
+    }
+}
+
+// 2. Implement custom widget agent
+extension YourLiveListViewController: LiveListViewAdapter {
+    public func createLiveInfoView(info: LiveInfo) -> UIView {
+        // Custom view
+        return YourCustomView(liveInfo: info)
+    }
+
+    public func updateLiveInfoView(view: UIView, info: LiveInfo) {
+        if let infoView = view as? YourCustomView {
+            // Custom view update data
+            infoView.updateView(liveInfo: info)
+        }
+    }
+}
+```
+
+### Custom Transition Animation
+
+**Double-Column Waterfall Flow** and **Single-Column Waterfall Flow** to navigate to the audience viewing page, custom transition animation is often needed for better transition effects. `TUILiveKit` has open-sourced the live stream transition animation [LiveTransitioningDelegate](https://github.com/Tencent-RTC/TUILiveKit/blob/main/iOS/TUILiveKit/Sources/TUILiveListViewController.swift#L193) in the **GitHub** repository. You just need to set `audienceVC.transitioningDelegate` to achieve the same transition animation as TUILiveKit.
+
+【Swift】
+``` swift
+// Implement OnItemClickDelegate in your live stream waterfall layout list view controller, for example: YourLiveListViewController
+extension YourLiveListViewController: OnItemClickDelegate {
+
+    func onItemClick(liveInfo: LiveInfo, frame: CGRect) {
+        let audienceVC = YourAudienceViewController(roomId: liveInfo.roomId)
+        audienceVC.modalPresentationStyle = .fullScreen
+        // Set the transition animation delegate
+        audienceVC.transitioningDelegate = LiveTransitioningDelegate(originFrame: frame)
+        present(audienceVC, animated: false)
+    }
+
+}
+```
+
+|**Double-Column Waterfall Transition Animation**|**Single-Column Waterfall Transition Animation**|
+|---------|---------|
+|||
+
+## Next Steps
+
+Congratulations! You have successfully integrated the **Live Stream List** feature. Next, you can implement features such as **Host Live Streaming** and **Audience Viewing**. Please refer to the table below:
+| <strong>Feature</strong> | <strong>Description</strong> | <strong>Integration Guide</strong> |
+| --- | --- | --- |
+| <strong>Host Streaming</strong> | The complete workflow for a host to start a stream, including pre-stream setup and various in-stream interactions. | Host Streaming |
+| <strong>Audience Viewing</strong> | Audience can watch live streaming after entering the anchor's live streaming room, with features like audience mic connection, live room information, online audience, and bullet screen display. | Audience Viewing |
+
+## FAQs
+
+### What should I do if the page shows no live streams after integrating the live list feature?
+
+If you see a blank page, you need to check if you have completed the Complete Login. To test this feature, you can use two devices: one device to start a broadcast, and the other on the live list page to pull the list of ongoing live streams.
+
+### What is the difference between single-column and double-column waterfall flows?
+
+A single-column waterfall flow previews one live room at a time, while a double-column waterfall flow previews two live rooms simultaneously. You can choose the appropriate layout based on your design requirements.
+
+### Is there a charge for previewing live streams?
+
+Yes, the duration of previewing a live room is counted towards the audience's audio/video duration, which is a paid service. For detailed
+
+Pricing, you can refer to the relevant content in the documentation.