tencent cloud

PrevNext

Feedback

search by keyword

Recent Pages

Documentation
Tencent Real-Time Communication
    Documentation
    Download PDF

    Anchor PK

    Last updated: 2025-01-09 16:31:31
    Download PDF
      This document mainly introduces how to use the RTC Room Engine SDK to implement the host PK feature.

      Prerequisites

      Before using the RTC RoomEngine SDK, you need to call the SDK login to ensure the subsequent features work properly.

      User Guide

      Note:
      When using the PK feature, please ensure that you have started your live broadcast.

      Initiating a PK Request

      You first need to obtain the TUILiveBattleManager plugin through the getLiveBattleManager API.
      Then use the TUILiveBattleManager plugin's requestBattle API to implement this feature, passing in three parameters: PK configuration information, the user ID of the host to invite for PK, and the timeout duration.
      The PK configuration information is a TUIBattleConfig struct. When configuring, you generally only need to set the PK duration duration.
      For example, to invite the host with user ID 100001 for PK:
      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 host you want to PK with.
      let timeout = 30    // Please replace it with your application timeout in seconds. If set to 0, the SDK will not perform timeout detection or trigger timeout callbacks.
      
      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 host you want to PK with
      int timeout = 30;    // Please replace it with your application timeout in seconds. If set to 0, the SDK will not perform timeout detection or trigger timeout callbacks
      
      
      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 addObserver API for the TUILiveBattleManager plugin, you will receive the onBattleRequestReceived callback when someone requests to connect with you. You can accept or reject the request using 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 the PK request
          battleManager.rejectBattle(battleId: battleInfo.battleId) {
              // PK request rejected successfully
          } onError: { code, message in
              // PK request rejection failed
          }
      }
      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 the PK request
          battleManager.rejectBattle(battleInfo.battleId, new TUIRoomDefine.ActionCallback() {
              @Override
              public void onSuccess() {
                  // PK request rejected successfully
              }
      
              @Override
              public void onError(TUICommonDefine.Error error, String message) {
                  // PK request rejection failed
              }
          });
      }

      Abandoning a PK Request

      You first need to obtain the TUILiveBattleManager plugin through the getLiveBattleManager API.
      Then use the TUILiveBattleManager plugin's cancelBattleRequest API to implement this feature, passing in two parameters: the battleId from battleInfo after initiating a PK request successfully and the user ID of the host to abandon the PK invitation.
      For example, to abandon the PK request with the host whose user ID is 100001:
      iOS
      Android
      let battleManager = TUIRoomEngine.sharedInstance().getLiveBattleManager()
      let battleId = ""         // Please replace it with the battleId value from battleInfo after successfully calling the requestBattle API for PK.
      let userIds = ["100001"]  // Please replace it with the user ID of the host you invited for PK.
      battleManager.cancelBattleRequest(battleId: battleId, userIdList: userIds) {
          // PK request abandoned successfully
      } onError: { code, message in
          // PK request abandonment failed
      }
      TUILiveBattleManager battleManager = TUIRoomEngine.sharedInstance().getLiveBattleManager();
      String battleId = "";         // Please replace it with the battleId value from battleInfo after successfully calling the requestBattle API for PK.
      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) {
              // PK request abandonment failed
          }
      });

      Exiting PK

      You first need to obtain the TUILiveBattleManager plugin through the getLiveBattleManager API.
      Then use the TUILiveBattleManager plugin's exitBattle API, passing in the battleId from battleInfo after successfully initiating a PK request to exit the ongoing PK.
      iOS
      Android
      import RTCRoomEngine
      
      let battleManager = TUIRoomEngine.sharedInstance().getLiveBattleManager()
      let battleId = ""         // Please replace it with the battleId value from battleInfo after successfully calling the requestBattle API for PK.
      battleManager.exitBattle(battleId: battleId) {
          // PK exited successfully
      } onError: { code, message in
          // PK exit failed
      }
      TUILiveBattleManager battleManager = TUIRoomEngine.sharedInstance().getLiveBattleManager();
      String battleId = "";         // Please replace it with the battleId value from battleInfo after successfully calling the requestBattle API for PK.
      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 to Callbacks

      iOS
      Android
      You can call addObserver to become an observer of TUILiveBattleManager and listen for PK-related callbacks.
      Take AnchorBattleController as an example to become an observer:
      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 the PK
          func onUserJoinBattle(battleId: String, battleUser: TUIBattleUser) {
              // battleUser.userName joined the PK
          }
          // Triggered when a host in the PK leaves the PK
          func onUserExitBattle(battleId: String, battleUser: TUIBattleUser) {
              // battleUser.userName left the PK
          }
          // Triggered when PK score changes
          func onBattleScoreChanged(battleId: String, battleUserList: [TUIBattleUser]) {
              // PK score changed, the first user's score 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 PK invitation is canceled
          func onBattleRequestCancelled(battleInfo: TUIBattleInfo, inviter: TUIBattleUser, invitee: TUIBattleUser) {
              // PK invitation from inviter.userName was canceled
          }
          // Triggered when a PK invitation times out
          func onBattleRequestTimeout(battleInfo: TUIBattleInfo, inviter: TUIBattleUser, invitee: TUIBattleUser) {
              // PK invitation from inviter.userName timed out
          }
          // Triggered when a sent PK invitation is accepted
          func onBattleRequestAccept(battleInfo: TUIBattleInfo, inviter: TUIBattleUser, invitee: TUIBattleUser) {
              // PK invitation to invitee.userName was accepted
          }
          // Triggered when a sent PK invitation is rejected
          func onBattleRequestReject(battleInfo: TUIBattleInfo, inviter: TUIBattleUser, invitee: TUIBattleUser) {
              // The PK invitation to invitee.userName was rejected
          }
      }
      You can call addObserver to become an observer of TUILiveBattleManager and listen for PK-related callbacks.
      Take AnchorBattleObserver as an example to become an observer:
      class AnchorBattleObserver extends TUILiveBattleManager.Observer {
          AnchorBattleObserver() {
      
              TUIRoomEngine.sharedInstance().getLiveBattleManager().addObserver(this);
          }
      
          // Triggered when PK starts
          @Override
          public void onBattleStarted(TUILiveBattleManager.BattleInfo battleInfo)  {
              // PK started, battleId:battleInfo.battleId
          }
          // Triggered when PK ends
          @Override
          public void onBattleEnded(TUILiveBattleManager.BattleInfo battleInfo, TUILiveBattleManager.BattleStoppedReason reason) {
              // PK ended, battleId:battleInfo.battleId
          }
          // Triggered when a new host joins the PK
          @Override
          public void onUserJoinBattle(String battleId, TUILiveBattleManager.BattleUser battleUser)  {
              // battleUser.userName joined the PK
          }
          // Triggered when a host in the PK leaves the PK
          @Override
          public void onUserExitBattle(String battleId, TUILiveBattleManager.BattleUser battleUser) {
              // battleUser.userName left the PK
          }
          // Triggered when PK score changes
          @Override
          public void onBattleScoreChanged(String battleId, List<TUILiveBattleManager.BattleUser> battleUserList) {
              // PK score changed, the first user's score is: battleUserList.first?.score
          }
          // Triggered when a PK invitation is received
          @Override
          public void onBattleRequestReceived(TUILiveBattleManager.BattleInfo battleInfo, TUILiveBattleManager.BattleUser inviter, TUILiveBattleManager.BattleUser invitee) {
              // Received a PK invitation from inviter.userName
          }
          // Triggered when a PK invitation is canceled
          @Override
          public void onBattleRequestCancelled(TUILiveBattleManager.BattleInfo battleInfo, TUILiveBattleManager.BattleUser inviter, TUILiveBattleManager.BattleUser invitee) {
              // PK invitation from inviter.userName was canceled
          }
          // Triggered when a PK invitation times out
          @Override
          public void onBattleRequestTimeout(TUILiveBattleManager.BattleInfo battleInfo, TUILiveBattleManager.BattleUser inviter, TUILiveBattleManager.BattleUser invitee) {
              // PK invitation from inviter.userName timed out
          }
          // Triggered when a sent PK invitation is accepted
          @Override
          public void onBattleRequestAccept(TUILiveBattleManager.BattleInfo battleInfo, TUILiveBattleManager.BattleUser inviter, TUILiveBattleManager.BattleUser invitee) {
              // PK invitation to invitee.userName was accepted
          }
          // Triggered when a sent PK invitation is rejected
          @Override
          public void onBattleRequestReject(TUILiveBattleManager.BattleInfo battleInfo, TUILiveBattleManager.BattleUser inviter, TUILiveBattleManager.BattleUser invitee) {
              // The PK invitation to invitee.userName was rejected
          }
      }
      Contact Us

      Contact our sales team or business advisors to help your business.

      Contact Us
      Technical Support

      Open a ticket if you're looking for further assistance. Our Ticket is 7x24 avaliable.

      Submit a Ticket
      7x24 Phone Support
      Copyright © 2013-2025 Tencent Cloud. All Rights Reserved.
      Privacy PolicyLegalCookie Policy