文档概览/
Live/
SDK/
iOS/
API Usage Guide/
Basic Features/
Anchor Battle/

Anchor Battle

本文档主要介绍如何使用 RTC Room Engine SDK 实现 主播 PK 功能。

前提条件

在使用 RTC RoomEngine SDK前，您需要先调用 登录 SDK，以便后续功能正常使用。

使用指引

说明：
使用 PK 功能时，请确保您已开播。

发起 PK 请求

您首先需要通过 getLiveBattleManager 接口获取 TUILiveBattleManager插件。
然后再使用 TUILiveBattleManager 插件的 requestBattle 接口实现该功能，传入三个参数：PK 配置信息、邀请 PK 的主播的用户Id和超时时长。
PK 配置信息是一个 TUIBattleConfig 的结构体，在配置时，您一般只需设置其中的 PK 持续时间 duration 即可。
以邀请用户Id为 100001 的主播 PK 为例：
iOS
Android
import RTCRoomEngine

let battleManager = TUIRoomEngine.sharedInstance().getLiveBattleManager()
let config = TUIBattleConfig()
config.duration = 30        // 请将其替换为您的PK持续时间，单位为秒
let userIds = ["100001"]    // 请将其替换为您想与之PK的主播的用户Id
let timeout = 30    // 请将这里替换成您申请上麦的超时时间,单位秒，如果设置为 0，SDK 不会做超时检测，也不会触发超时回调

battleManager.requestBattle(config: config, 
                            userIdList: userIds,
                            timeout: TimeInterval(timeout)) { battleInfo, battleResults in
    // 发起 PK 请求成功, battleId:battleInfo.battleId
} onError: { code, message in
    // 发起 PK 请求失败
}
TUILiveBattleManager battleManager = TUIRoomEngine.sharedInstance().getLiveBattleManager();
TUILiveBattleManager.BattleConfig config = new TUILiveBattleManager.BattleConfig();
config.duration = 30;        // 请将其替换为您的PK持续时间，单位为秒
List<String> userIds = Collections.singletonList("100001");   // 请将其替换为您想与之PK的主播的用户Id
int timeout = 30;    // 请将这里替换成您申请上麦的超时时间,单位秒，如果设置为 0，SDK 不会做超时检测，也不会触发超时回调


battleManager.requestBattle(config, userIds, timeout, new TUILiveBattleManager.BattleRequestCallback() {
    @Override
    public void onSuccess(TUILiveBattleManager.BattleInfo battleInfo, Map<String, TUILiveBattleManager.BattleCode> resultMap) {
        // 发起 PK 请求成功, battleId:battleInfo.battleId
    }
    @Override
    public void onError(TUICommonDefine.Error error, String message) {
        // 发起 PK 请求失败
    }
});
若您通过 addObserver 接口成为了 TUILiveBattleManager 插件的观察者，则当有人申请和您连线时，您会收到 onBattleRequestReceived 回调，您可通过 acceptBattle / rejectBattle 接口接受或拒绝该请求。
iOS
Android
func onBattleRequestReceived(battleInfo: TUIBattleInfo,
                             inviter: TUIBattleUser,
                             invitee: TUIBattleUser) {
    // 接受 PK 请求
    let battleManager = TUIRoomEngine.sharedInstance().getLiveBattleManager()
    battleManager.acceptBattle(battleId: battleInfo.battleId) {
        // 接受 PK 请求成功
    } onError: { code, message in
        // 接受 PK 请求失败
    }

    // 拒绝 PK 请求
    battleManager.rejectBattle(battleId: battleInfo.battleId) {
        // 拒绝 PK 请求成功
    } onError: { code, message in
        // 拒绝 PK 请求失败
    }
}
public void onBattleRequestReceived(TUILiveBattleManager.BattleInfo battleInfo, TUILiveBattleManager.BattleUser inviter, TUILiveBattleManager.BattleUser invitee) {
    // 接受 PK 请求
    TUILiveBattleManager battleManager = TUIRoomEngine.sharedInstance().getLiveBattleManager();
    battleManager.acceptBattle(battleInfo.battleId, new TUIRoomDefine.ActionCallback() {
        @Override
        public void onSuccess() {
            // 接受 PK 请求成功
        }
        @Override
        public void onError(TUICommonDefine.Error error, String message) {
            // 接受 PK 请求失败
        }
    });

    // 拒绝 PK 请求
    battleManager.rejectBattle(battleInfo.battleId, new TUIRoomDefine.ActionCallback() {
        @Override
        public void onSuccess() {
            // 拒绝 PK 请求成功
        }

        @Override
        public void onError(TUICommonDefine.Error error, String message) {
            // 拒绝 PK 请求失败
        }
    });
}

放弃 PK 请求

您首先需要通过 getLiveBattleManager 接口获取 TUILiveBattleManager插件。
然后再使用 TUILiveBattleManager 插件的 cancelBattleRequest 接口实现该功能，传入两个参数：发起 PK 请求成功后battleInfo的battleId 和 放弃 PK 邀请的主播用户 Id。
以放弃和用户Id为 100001 的主播 PK 请求为例：
iOS
Android
let battleManager = TUIRoomEngine.sharedInstance().getLiveBattleManager()
let battleId = ""         // 请将其替换为您调用requestBattle请求PK成功后battleInfo中的battleId值
let userIds = ["100001"]  // 请将其替换为您邀请PK的主播的用户Id
battleManager.cancelBattleRequest(battleId: battleId, userIdList: userIds) {
    // 放弃 PK 请求成功
} onError: { code, message in
    // 放弃 PK 请求失败
}
TUILiveBattleManager battleManager = TUIRoomEngine.sharedInstance().getLiveBattleManager();
String battleId = "";         // 请将其替换为您调用requestBattle请求PK成功后battleInfo中的battleId值
List<String> userIds = Collections.singletonList("100001"); // 请将其替换为您邀请PK的主播的用户Id
battleManager.cancelBattleRequest(battleId, userIds, new TUIRoomDefine.ActionCallback() {
    @Override
    public void onSuccess() {
        // 放弃 PK 请求成功
    }
    @Override
    public void onError(TUICommonDefine.Error error, String message) {
        // 放弃 PK 请求失败
    }
});

退出 PK

您首先需要通过 getLiveBattleManager 接口获取 TUILiveBattleManager插件。
然后再使用 TUILiveBattleManager 插件的 exitBattle 接口，传入参数：发起 PK 请求成功后battleInfo的battleId ，实现退出当前正在进行的 PK。
iOS
Android
import RTCRoomEngine

let battleManager = TUIRoomEngine.sharedInstance().getLiveBattleManager()
let battleId = ""         // 请将其替换为您调用requestBattle请求PK成功后battleInfo中的battleId值
battleManager.exitBattle(battleId: battleId) {
    // 退出 PK 成功
} onError: { code, message in
    // 退出 PK 失败
}
TUILiveBattleManager battleManager = TUIRoomEngine.sharedInstance().getLiveBattleManager();
String battleId = "";         // 请将其替换为您调用requestBattle请求PK成功后battleInfo中的battleId值
battleManager.exitBattle(battleId, new TUIRoomDefine.ActionCallback() {
    @Override
    public void onSuccess() {
        // 退出 PK 成功
    }
    @Override
    public void onError(TUICommonDefine.Error error, String message) {
        // 退出 PK 失败
    }
});

监听回调

iOS
Android
您可通过调用 addObserver 成为 TUILiveBattleManager 的观察者，监听 PK 相关的回调。
以 AnchorBattleController 成为观察者为例：
import RTCRoomEngine

class AnchorBattleController: NSObject, TUILiveBattleObserver {
    override init() {
        super.init()
        TUIRoomEngine.sharedInstance().getLiveBattleManager().addObserver(self)
    }
    
    deinit {
        TUIRoomEngine.sharedInstance().getLiveBattleManager().removeObserver(self)
    }
    
    // PK 开始时触发
    func onBattleStarted(battleInfo: TUIBattleInfo) {
        // PK 开始了, battleId:battleInfo.battleId
    }
    // PK 结束时触发
    func onBattleEnded(battleInfo: TUIBattleInfo, reason: TUIBattleStoppedReason) {
        // PK 结束了, battleId:battleInfo.battleId
    }
    // 有新主播加入 PK 时触发
    func onUserJoinBattle(battleId: String, battleUser: TUIBattleUser) {
        // battleUser.userName加入了 PK
    }
    // 正在 PK 的主播离开了 PK 时触发
    func onUserExitBattle(battleId: String, battleUser: TUIBattleUser) {
        // battleUser.userName离开了 PK
    }
    // PK 得分变化时触发
    func onBattleScoreChanged(battleId: String, battleUserList: [TUIBattleUser]) {
        // PK 得分改变了，第一个用户的比分为: battleUserList.first?.score
    }
    // 收到 PK 邀请时触发
    func onBattleRequestReceived(battleInfo: TUIBattleInfo, inviter: TUIBattleUser, invitee: TUIBattleUser) {
        // 收到了来自inviter.userName的 PK 邀请
    }
    // 收到 PK 邀请被取消时触发
    func onBattleRequestCancelled(battleInfo: TUIBattleInfo, inviter: TUIBattleUser, invitee: TUIBattleUser) {
        // 来自inviter.userName的 PK 邀请被取消了
    }
    // 收到 PK 邀请超时触发
    func onBattleRequestTimeout(battleInfo: TUIBattleInfo, inviter: TUIBattleUser, invitee: TUIBattleUser) {
        // 来自inviter.userName的 PK 邀请超时了
    }
    // 发出的 PK 邀请被接受时触发
    func onBattleRequestAccept(battleInfo: TUIBattleInfo, inviter: TUIBattleUser, invitee: TUIBattleUser) {
        // 对invitee.userName的 PK 邀请被接受了
    }
    // 发出的 PK 邀请被拒绝时触发
    func onBattleRequestReject(battleInfo: TUIBattleInfo, inviter: TUIBattleUser, invitee: TUIBattleUser) {
        // 对invitee.userName的 PK 邀请被拒绝了
    }
}
您可通过调用 addObserver 成为 TUILiveBattleManager 的观察者，监听 PK 相关的回调。
以 AnchorBattleObserver 成为观察者为例：
class AnchorBattleObserver extends TUILiveBattleManager.Observer {
    AnchorBattleObserver() {

        TUIRoomEngine.sharedInstance().getLiveBattleManager().addObserver(this);
    }

    // PK 开始时触发
    @Override
    public void onBattleStarted(TUILiveBattleManager.BattleInfo battleInfo)  {
        // PK 开始了, battleId:battleInfo.battleId
    }
    // PK 结束时触发
    @Override
    public void onBattleEnded(TUILiveBattleManager.BattleInfo battleInfo, TUILiveBattleManager.BattleStoppedReason reason) {
        // PK 结束了, battleId:battleInfo.battleId
    }
    // 有新主播加入 PK 时触发
    @Override
    public void onUserJoinBattle(String battleId, TUILiveBattleManager.BattleUser battleUser)  {
        // battleUser.userName加入了 PK
    }
    // 正在 PK 的主播离开了 PK 时触发
    @Override
    public void onUserExitBattle(String battleId, TUILiveBattleManager.BattleUser battleUser) {
        // battleUser.userName离开了 PK
    }
    // PK 得分变化时触发
    @Override
    public void onBattleScoreChanged(String battleId, List<TUILiveBattleManager.BattleUser> battleUserList) {
        // PK 得分改变了，第一个用户的比分为: battleUserList.first?.score
    }
    // 收到 PK 邀请时触发
    @Override
    public void onBattleRequestReceived(TUILiveBattleManager.BattleInfo battleInfo, TUILiveBattleManager.BattleUser inviter, TUILiveBattleManager.BattleUser invitee) {
        // 收到了来自inviter.userName的 PK 邀请
    }
    // 收到 PK 邀请被取消时触发
    @Override
    public void onBattleRequestCancelled(TUILiveBattleManager.BattleInfo battleInfo, TUILiveBattleManager.BattleUser inviter, TUILiveBattleManager.BattleUser invitee) {
        // 来自inviter.userName的 PK 邀请被取消了
    }
    // 收到 PK 邀请超时触发
    @Override
    public void onBattleRequestTimeout(TUILiveBattleManager.BattleInfo battleInfo, TUILiveBattleManager.BattleUser inviter, TUILiveBattleManager.BattleUser invitee) {
        // 来自inviter.userName的 PK 邀请超时了
    }
    // 发出的 PK 邀请被接受时触发
    @Override
    public void onBattleRequestAccept(TUILiveBattleManager.BattleInfo battleInfo, TUILiveBattleManager.BattleUser inviter, TUILiveBattleManager.BattleUser invitee) {
        // 对invitee.userName的 PK 邀请被接受了
    }
    // 发出的 PK 邀请被拒绝时触发
    @Override
    public void onBattleRequestReject(TUILiveBattleManager.BattleInfo battleInfo, TUILiveBattleManager.BattleUser inviter, TUILiveBattleManager.BattleUser invitee) {
        // 对invitee.userName的 PK 邀请被拒绝了
    }
}