tencent cloud

Tencent Real-Time Communication

DocumentationTencent Real-Time CommunicationLegacy DocumentationRTC RoomEngine SDK（Old）Basic FeaturesHost Competition

Host Competition

Download
Focus Mode
Font Size
Last updated: 2025-04-30 11:24:30
this document primarily introduces how to use RTC Room Engine SDK to implement Anchor PK Feature.

Prerequisites

Before using the RTC RoomEngine SDK, you need to log in to the SDK first so that subsequent features can be used normally.

User Guide

Note:
When using the PK Function, ensure you have started broadcasting.

PK Request

First, you need to obtain the TUILiveBattleManager plug-in through the getLiveBattleManager API.
Then reuse the requestBattle API of the TUILiveBattleManager plug-in to implement the feature, inputting three parameters: PK configuration message, the user Id of the inviting PK anchor, and timeout duration.
PK configuration message is a structure of TUIBattleConfig. When configuring, you generally just need to set the PK duration duration.
Take inviting an anchor with user Id 100001 for PK as an example:
iOS
Android
import RTCRoomEngine

let battleManager = TUIRoomEngine.sharedInstance().getLiveBattleManager()
let config = TUIBattleConfig()
config.duration = 30        // Please replace it with your PK duration, in seconds
let userIds = ["100001"]    // Please replace it with the user ID of the anchor you want to PK with
let timeout = 30    // Please replace this with your timeout period for requesting to speak, in seconds. If set to 0, the SDK will not perform timeout detection or avoid triggering a timeout callback.

battleManager.requestBattle(config: config, 
                            userIdList: userIds,
                            timeout: TimeInterval(timeout)) { battleInfo, battleResults in
    // PK request initiated successfully, battleId: battleInfo.battleId
} onError: { code, message in
    // PK request initiation failed
}
TUILiveBattleManager battleManager = TUIRoomEngine.sharedInstance().getLiveBattleManager();
TUILiveBattleManager.BattleConfig config = new TUILiveBattleManager.BattleConfig();
config.duration = 30;        // Please replace it with your PK duration, in seconds.
List<String> userIds = Collections.singletonList("100001");   // Please replace it with the user ID of the anchor you want to PK with
int timeout = 30;    // Please replace this with your timeout period for requesting to speak, in seconds. If set to 0, the SDK will not perform timeout detection or avoid triggering a timeout callback.


battleManager.requestBattle(config, userIds, timeout, new TUILiveBattleManager.BattleRequestCallback() {
    @Override
    public void onSuccess(TUILiveBattleManager.BattleInfo battleInfo, Map<String, TUILiveBattleManager.BattleCode> resultMap) {
        // PK request initiated successfully, battleId: battleInfo.battleId
    }
    @Override
    public void onError(TUICommonDefine.Error error, String message) {
        // PK request initiation failed
    }
});
If you become an observer of the TUILiveBattleManager plug-in through the addObserver API, you will receive the onBattleRequestReceived callback when someone applies to connect with you. You can accept or reject the request via the acceptBattle / rejectBattle APIs.
iOS
Android
func onBattleRequestReceived(battleInfo: TUIBattleInfo,
                             inviter: TUIBattleUser,
                             invitee: TUIBattleUser) {
    // Accept PK request
    let battleManager = TUIRoomEngine.sharedInstance().getLiveBattleManager()
    battleManager.acceptBattle(battleId: battleInfo.battleId) {
        // PK request accepted successfully
    } onError: { code, message in
        // PK request acceptance failed
    }

    // Reject PK request
    battleManager.rejectBattle(battleId: battleInfo.battleId) {
        // Successfully reject PK request
    } onError: { code, message in
        // Failed to reject PK request
    }
}
public void onBattleRequestReceived(TUILiveBattleManager.BattleInfo battleInfo, TUILiveBattleManager.BattleUser inviter, TUILiveBattleManager.BattleUser invitee) {
    // Accept PK request
    TUILiveBattleManager battleManager = TUIRoomEngine.sharedInstance().getLiveBattleManager();
    battleManager.acceptBattle(battleInfo.battleId, new TUIRoomDefine.ActionCallback() {
        @Override
        public void onSuccess() {
            // PK request accepted successfully
        }
        @Override
        public void onError(TUICommonDefine.Error error, String message) {
            // PK request acceptance failed
        }
    });

    // Reject PK request
    battleManager.rejectBattle(battleInfo.battleId, new TUIRoomDefine.ActionCallback() {
        @Override
        public void onSuccess() {
            // Successfully reject PK request
        }

        @Override
        public void onError(TUICommonDefine.Error error, String message) {
            // Failed to reject PK request
        }
    });
}

Give Up PK Request

First, you need to obtain the TUILiveBattleManager plug-in through the getLiveBattleManager API.
Then reuse the cancelBattleRequest API of the TUILiveBattleManager plug-in to implement the feature, inputting two parameters: the battleId of battleInfo after initiating a PK Request successfully and the user Id of the anchor who cancels the PK invitation.
Take giving up the PK request with the anchor whose user Id is 100001 as an example:
iOS
Android
let battleManager = TUIRoomEngine.sharedInstance().getLiveBattleManager()
let battleId = ""         // Replace it with the battleId value in battleInfo after the PK request is initiated successfully by calling the requestBattle request
let userIds = ["100001"]  // Please replace it with the user ID of the host to be invited for PK
battleManager.cancelBattleRequest(battleId: battleId, userIdList: userIds) {
    // PK request abandoned successfully
} onError: { code, message in
    // Failed to abandon PK request
}
TUILiveBattleManager battleManager = TUIRoomEngine.sharedInstance().getLiveBattleManager();
String battleId = "";         // Replace it with the battleId value in battleInfo after the PK request is initiated successfully by calling the requestBattle request
List<String> userIds = Collections.singletonList("100001"); // Please replace it with the user ID of the host to be invited for PK.
battleManager.cancelBattleRequest(battleId, userIds, new TUIRoomDefine.ActionCallback() {
    @Override
    public void onSuccess() {
        // PK request abandoned successfully
    }
    @Override
    public void onError(TUICommonDefine.Error error, String message) {
        // Failed to abandon PK request
    }
});

Exit PK

First, you need to obtain the TUILiveBattleManager plug-in through the getLiveBattleManager API.
Then use the exitBattle API of the TUILiveBattleManager plug-in. Input parameter: the battleId in battleInfo after thePK Request is initiated successfully, to exit the ongoing PK.
iOS
Android
import RTCRoomEngine

let battleManager = TUIRoomEngine.sharedInstance().getLiveBattleManager()
let battleId = ""         // Replace it with the battleId value in battleInfo after the PK request is initiated successfully by calling the requestBattle request
battleManager.exitBattle(battleId: battleId) {
    // PK exited successfully
} onError: { code, message in
    // PK exit failed
}
TUILiveBattleManager battleManager = TUIRoomEngine.sharedInstance().getLiveBattleManager();
String battleId = "";         // Replace it with the battleId value in battleInfo after the PK request is initiated successfully by calling the requestBattle request
battleManager.exitBattle(battleId, new TUIRoomDefine.ActionCallback() {
    @Override
    public void onSuccess() {
        // PK exited successfully
    }
    @Override
    public void onError(TUICommonDefine.Error error, String message) {
        // PK exit failed
    }
});

Listening Callback

iOS
Android
You can become an observer of TUILiveBattleManager by calling addObserver to listen for PK-related callbacks.
Take AnchorBattleController becoming an observer as an example:
import RTCRoomEngine

class AnchorBattleController: NSObject, TUILiveBattleObserver {
    override init() {
        super.init()
        TUIRoomEngine.sharedInstance().getLiveBattleManager().addObserver(self)
    }
    
    deinit {
        TUIRoomEngine.sharedInstance().getLiveBattleManager().removeObserver(self)
    }
    
    // Triggered when PK starts
    func onBattleStarted(battleInfo: TUIBattleInfo) {
        // PK started, battleId: battleInfo.battleId
    }
    // Triggered when PK ends
    func onBattleEnded(battleInfo: TUIBattleInfo, reason: TUIBattleStoppedReason) {
        // PK ended, battleId: battleInfo.battleId
    }
    // Triggered when a new host joins PK
    func onUserJoinBattle(battleId: String, battleUser: TUIBattleUser) {
        // battleUser.userName joined PK
    }
    // Triggered when the host who is having a PK leaves the PK
    func onUserExitBattle(battleId: String, battleUser: TUIBattleUser) {
        // battleUser.userName left the PK
    }
    // Triggered when PK scores change
    func onBattleScoreChanged(battleId: String, battleUserList: [TUIBattleUser]) {
        // PK score changed. The score of the first user is: battleUserList.first?.score
    }
    // Triggered when a PK invitation is received
    func onBattleRequestReceived(battleInfo: TUIBattleInfo, inviter: TUIBattleUser, invitee: TUIBattleUser) {
        // Received a PK invitation from inviter.userName
    }
    // Triggered when a received PK invitation is canceled
    func onBattleRequestCancelled(battleInfo: TUIBattleInfo, inviter: TUIBattleUser, invitee: TUIBattleUser) {
        // PK invitation from inviter.userName has been cancelled
    }
You can become an observer of TUILiveConnectionManager by calling addObserver to listen to connection-related callbacks.
Take CoHostObserver becoming an observer as an example:
class CoHostObserver extends TUILiveConnectionManager.Observer {
    CoHostObserver() {
        TUIRoomEngine.sharedInstance().getLiveConnectionManager().addObserver(this);
    }


    // Trigger when the connected user list changes
    @Override
    public void onConnectionUserListChanged(List<TUILiveConnectionManager.ConnectionUser> connectedList,
                                            List<TUILiveConnectionManager.ConnectionUser> joinedList,
                                            List<TUILiveConnectionManager.ConnectionUser> leavedList) {
        // The connection list has changed. The latest connection list: connectedList. The list of newly connected users: joinedList. The list of users whose connections were interrupted: leavedList.
    }
    // Triggered when a connection invitation is received
    @Override
    public void onConnectionRequestReceived(TUILiveConnectionManager.ConnectionUser inviter,
                                            List<TUILiveConnectionManager.ConnectionUser> inviteeList,
                                            String extensionInfo) {
        // A connection invitation has been received from inviter.userName.
    }
    // Triggered when a connection invitation is canceled
    @Override
    public void onConnectionRequestCancelled(TUILiveConnectionManager.ConnectionUser inviter) {
        // The connection invitation from inviter.userName has been cancelled.
    }
    // Triggered when a connection invitation is accepted
    @Override
    public void onConnectionRequestAccept(TUILiveConnectionManager.ConnectionUser invitee) {
        // Your connection invitation to invitee.userName has been accepted.
    }
    // Triggered when a connection invitation is rejected
    @Override
    public void onConnectionRequestReject(TUILiveConnectionManager.ConnectionUser invitee) {
        // Your connection invitation to invitee.userName has been rejected.
    }
    // Triggered when a connection invitation times out
    @Override
    public void onConnectionRequestTimeout(TUILiveConnectionManager.ConnectionUser inviter,
                                           TUILiveConnectionManager.ConnectionUser invitee) {
        // The connection invitation from inviter.userName has timed out.
    }
}
Previous Topic: Anchor ConnectionNext Topic: Room List

Help and Support

Was this page helpful?

Help us improve! Rate your documentation experience in 5 mins.

Feedback