集成 SDK 与连接管理
集成前准备
- 参考 开发者中心配置 创建应用、配置包名与签名证书
- 参考集成指南(Unity、Android、iOS)完成对应平台或引擎的基础接入,对于 Windows 平台,使用前还需接入启动校验
- 多人联机 SDK 依赖 TapTap 登录 SDK ,接入前需确保已接入
权限声明
该模块依赖权限如下:
| 权限 | 使用目的 | 权限申请时机 |
|---|---|---|
| 网络权限 | 用于正常网络访问 | 用户首次使用该功能时会申请权限 |
SDK 获取
- Unity
- Android
- iOS
远程依赖示例
NPMJS 方式:在 Packages/manifest.json 中添加:
"dependencies":{
"com.taptap.sdk.core":"4.10.7",
"com.taptap.sdk.login":"4.10.7",
"com.taptap.sdk.onlinebattle":"4.10.7"
}
GitHub 方式:在 Packages/manifest.json 中添加:
"dependencies":{
"com.taptap.sdk.core":"https://github.com/taptap/tapsdk-unity-dist.git?path=/Core#4.10.7",
"com.taptap.sdk.login":"https://github.com/taptap/tapsdk-unity-dist.git?path=/Login#4.10.7",
"com.taptap.sdk.onlinebattle":"https://github.com/taptap/tapsdk-unity-dist.git?path=/OnlineBattle#4.10.7"
}
本地文件导入
在 下载页 下载并导入以下 unitypackage 文件:
TapSDK_Core.unitypackage(TapTapSDK 核心模块,必选)TapSDK_Login.unitypackage(TapTapSDK 登录模块,必选)TapSDK_OnlineBattle.unitypackage(TapTapSDK 多人联机模块,必选)
在 app module 的 build.gradle 中添加对应依赖:
dependencies {
implementation 'com.taptap.sdk:tap-core:4.10.7'
implementation 'com.taptap.sdk:tap-login:4.10.7'
implementation 'com.taptap.sdk:tap-battle:4.10.7'
}
在 Podfile 文件中添加:
pod 'TapTapSDK/Battle', '~> 4.10.7'
注册回调
通过实现 SDK 通知回调接口(Unity 为 ITapOnlineBattleCallback,Android / iOS 为 TapOnlineBattleCallback)来接收玩家、房间信息及同步消息回调,渲染对应场景游戏页面,示例如下:
- Unity
- Android Java
- Android Kotlin
- iOS Swift
- iOS Objective-C
using TapSDK.OnlineBattle;
public class OnlineBattlePanel : DemoBaseController, ITapOnlineBattleCallback
{
/// 注册回调
public void RegisterCallback()
{
TapTapOnlineBattle.RegisterOnlineBattleCallback(this);
}
#region SDK 回调实现
/// <summary>
/// 收到玩家自定义消息
/// </summary>
/// <param name="playerId"> 消息发送者玩家ID </param>
/// <param name="msg"> 自定义消息,格式由开发者决定,必须是utf8字符串,最大2048字节 </param>
public void OnCustomMessageReceived(string playerId, string msg)
{
// TODO: 解析 msg,渲染对战状态或其他信息
}
/// <summary>
/// 与服务端连接断开,建议当错误码为网络异常时进行重连
/// </summary>
/// <param name="code"> 错误码,参考 <see cref="TapOnlineBattleConstant"/> </param>
/// <param name="msg"> 错误信息 </param>
public void OnDisconnected(int code, string msg)
{
// 当错误码为网络异常时进行重连
}
/// <summary>
/// 玩家更新自定义属性
/// </summary>
/// <param name="playerId"> 更新了自定义属性的玩家ID </param>
/// <param name="properties"> 新的属性值 </param>
public void OnPlayerCustomPropertiesChanged(string playerId, string properties)
{
LogMessage($"receive OnPlayerCustomPropertiesChanged {playerId}:{properties}");
}
/// <summary>
/// 玩家更新自定义状态
/// </summary>
/// <param name="playerId"> 更新了自定义状态的玩家ID </param>
/// <param name="status"> 新的状态 </param>
public void OnPlayerCustomStatusChanged(string playerId, int status)
{
LogMessage($"receive OnPlayerCustomStatusChanged {playerId}:{status}");
}
/// <summary>
/// 玩家进入房间
/// </summary>
/// <param name="roomId"> 房间ID </param>
/// <param name="playerInfo"> 玩家信息 </param>
public void OnPlayerEntered(string roomId, TapSDK.OnlineBattle.PlayerInfo playerInfo)
{
LogMessage(
$"receive OnPlayerEntered {roomId}:{JsonConvert.SerializeObject(playerInfo)}"
);
}
/// <summary>
/// 玩家被踢出
/// </summary>
/// <param name="roomId"> 被踢玩家所属房间ID </param>
/// <param name="playerId"> 被踢玩家ID </param>
public void OnPlayerKicked(string roomId, string playerId)
{
LogMessage($"receive OnPlayerKicked {roomId}:{playerId}");
}
/// <summary>
/// 玩家离开房间
/// </summary>
/// <param name="roomId"> 房间ID </param>
/// <param name="roomOwnerId"> 房主ID。如果离开的是房主,则roomOwnerId为新房主ID;反之,为原房主ID</param>
/// <param name="playerId"> 离开房间的玩家ID </param>
public void OnPlayerLeft(string roomId, string roomOwnerId, string playerId)
{
LogMessage($"receive OnPlayerLeft {roomId}:{roomOwnerId}:{playerId}");
}
/// <summary>
/// 玩家离线
/// </summary>
/// <param name="roomId"> 房间ID </param>
/// <param name="roomOwnerId"> 房主ID。如果离线的是房主,则roomOwnerId为新房主ID;反之,为原房主ID</param>
/// <param name="playerId"> 离线玩家ID </param>
public void OnPlayerOffline(string roomId, string roomOwnerId, string playerId)
{
LogMessage($"receive OnPlayerOffline {roomId}:{roomOwnerId}:{playerId}");
}
/// <summary>
/// 房间属性变更
/// </summary>
/// <param name="id"> 房间 ID </param>
/// <param name="name"> 房间名称 </param>
/// <param name="customProperties"> 房间自定义属性 </param>
public void OnRoomPropertiesChanged(string id, string name, string customProperties)
{
LogMessage($"receive OnRoomPropertiesChanged {id}:{name}:{customProperties}");
}
/// <summary>
/// 开始帧同步
/// </summary>
/// <param name="frameSyncInfo"> 帧同步基础信息 </param>
public void OnFrameSyncStarted(FrameSyncInfo frameSyncInfo)
{
LogMessage($"receive OnFrameSyncStarted {JsonConvert.SerializeObject(frameSyncInfo)}");
}
/// <summary>
/// 收到帧同步数据回调
/// </summary>
/// <param name="frameData"> 帧数据 </param>
public void OnFrameReceived(FrameData frameData)
{
if (frameData != null && frameData.inputs != null && frameData.inputs.Count > 0)
{
LogMessage($"receive OnFrameReceived {JsonConvert.SerializeObject(frameData)}");
}
}
/// <summary>
/// 停止帧同步
/// </summary>
/// <param name="roomId"> 房间 ID </param>
/// <param name="frameSyncId"> 帧同步 ID,房间内唯一 </param>
/// <param name="reason"> 原因 0:房主主动结束,1:因30分钟超时结束 </param>
public void OnFrameSyncStopped(string roomId, int frameSyncId, int reason)
{
LogMessage($"receive OnFrameSyncStopped {roomId}:{frameSyncId}:{reason}");
}
/// <summary>
/// 对战服务端异常,开发者需要退出对战、房间、队伍等状态,此时处于 connect 之后的状态
/// </summary>
public void OnBattleServiceError()
{
LogMessage("receive OnBattleServiceError");
}
#endregion
}
import com.taptap.sdk.battle.TapTapOnlineBattle;
import com.taptap.sdk.battle.TapOnlineBattleCallback;
import com.taptap.sdk.battle.model.FrameData;
import com.taptap.sdk.battle.model.FrameSyncInfo;
import com.taptap.sdk.battle.model.PlayerInfo;
public class MainActivity extends AppCompatActivity implements TapOnlineBattleCallback {
// 注册回调
public void registerCallback() {
TapTapOnlineBattle.registerOnlineBattleCallback(this);
}
// SDK 回调实现
// 收到玩家自定义消息
@Override
public void onCustomMessageReceived(String playerId, String msg) {
// TODO: 解析 msg,渲染对战状态或其他信息
}
// 与服务端连接断开,建议当错误码为网络异常时进行重连
@Override
public void onDisconnected(int code, String msg) {
// 当错误码为网络异常时进行重连
}
// 玩家更新自定义属性
@Override
public void onPlayerCustomPropertiesChanged(String playerId, String properties) {
Log.d("Battle", "receive onPlayerCustomPropertiesChanged " + playerId + ":" + properties);
}
// 玩家更新自定义状态
@Override
public void onPlayerCustomStatusChanged(String playerId, int status) {
Log.d("Battle", "receive onPlayerCustomStatusChanged " + playerId + ":" + status);
}
// 玩家进入房间
@Override
public void onPlayerEntered(String roomId, PlayerInfo playerInfo) {
Log.d("Battle", "receive onPlayerEntered " + roomId + ":" + playerInfo);
}
// 玩家被踢出
@Override
public void onPlayerKicked(String roomId, String playerId) {
Log.d("Battle", "receive onPlayerKicked " + roomId + ":" + playerId);
}
// 玩家离开房间
@Override
public void onPlayerLeft(String roomId, String roomOwnerId, String playerId) {
Log.d("Battle", "receive onPlayerLeft " + roomId + ":" + roomOwnerId + ":" + playerId);
}
// 玩家离线
@Override
public void onPlayerOffline(String roomId, String roomOwnerId, String playerId) {
Log.d("Battle", "receive onPlayerOffline " + roomId + ":" + roomOwnerId + ":" + playerId);
}
// 房间属性变更
@Override
public void onRoomPropertiesChanged(String id, String name, String customProperties) {
Log.d("Battle", "receive onRoomPropertiesChanged " + id + ":" + name + ":" + customProperties);
}
// 开始帧同步
@Override
public void onFrameSyncStarted(FrameSyncInfo frameSyncInfo) {
Log.d("Battle", "receive onFrameSyncStarted " + frameSyncInfo);
}
// 收到帧同步数据回调
@Override
public void onFrameReceived(FrameData frameData) {
if (!frameData.getInputs().isEmpty()) {
Log.d("Battle", "receive onFrameReceived " + frameData);
}
}
// 停止帧同步
@Override
public void onFrameSyncStopped(String roomId, int frameSyncId, int reason) {
Log.d("Battle", "receive onFrameSyncStopped " + roomId + ":" + frameSyncId + ":" + reason);
}
// 对战服务端异常,开发者需要退出对战、房间、队伍等状态,此时处于 connect 之后的状态
@Override
public void onBattleServiceError() {
Log.d("Battle", "receive onBattleServiceError");
}
}
import com.taptap.sdk.battle.TapTapOnlineBattle
import com.taptap.sdk.battle.TapOnlineBattleCallback
import com.taptap.sdk.battle.model.FrameData
import com.taptap.sdk.battle.model.FrameSyncInfo
import com.taptap.sdk.battle.model.PlayerInfo
import android.util.Log
class MainActivity : AppCompatActivity(), TapOnlineBattleCallback {
// 注册回调
fun registerCallback() {
TapTapOnlineBattle.registerOnlineBattleCallback(this)
}
// SDK 回调实现(接口方法均有默认空实现,按需重写即可)
// 收到玩家自定义消息
override fun onCustomMessageReceived(playerId: String, msg: String) {
// TODO: 解析 msg,渲染对战状态或其他信息
}
// 与服务端连接断开,建议当错误码为网络异常时进行重连
override fun onDisconnected(code: Int, msg: String) {
// 当错误码为网络异常时进行重连
}
// 玩家更新自定义属性
override fun onPlayerCustomPropertiesChanged(playerId: String, properties: String) {
Log.d("Battle", "receive onPlayerCustomPropertiesChanged $playerId:$properties")
}
// 玩家更新自定义状态
override fun onPlayerCustomStatusChanged(playerId: String, status: Int) {
Log.d("Battle", "receive onPlayerCustomStatusChanged $playerId:$status")
}
// 玩家进入房间
override fun onPlayerEntered(roomId: String, playerInfo: PlayerInfo) {
Log.d("Battle", "receive onPlayerEntered $roomId:$playerInfo")
}
// 玩家被踢出
override fun onPlayerKicked(roomId: String, playerId: String) {
Log.d("Battle", "receive onPlayerKicked $roomId:$playerId")
}
// 玩家离开房间
override fun onPlayerLeft(roomId: String, roomOwnerId: String, playerId: String) {
Log.d("Battle", "receive onPlayerLeft $roomId:$roomOwnerId:$playerId")
}
// 玩家离线
override fun onPlayerOffline(roomId: String, roomOwnerId: String, playerId: String) {
Log.d("Battle", "receive onPlayerOffline $roomId:$roomOwnerId:$playerId")
}
// 房间属性变更
override fun onRoomPropertiesChanged(id: String, name: String, customProperties: String) {
Log.d("Battle", "receive onRoomPropertiesChanged $id:$name:$customProperties")
}
// 开始帧同步
override fun onFrameSyncStarted(frameSyncInfo: FrameSyncInfo) {
Log.d("Battle", "receive onFrameSyncStarted $frameSyncInfo")
}
// 收到帧同步数据回调
override fun onFrameReceived(frameData: FrameData) {
if (frameData.inputs.isNotEmpty()) {
Log.d("Battle", "receive onFrameReceived $frameData")
}
}
// 停止帧同步
override fun onFrameSyncStopped(roomId: String, frameSyncId: Int, reason: Int) {
Log.d("Battle", "receive onFrameSyncStopped $roomId:$frameSyncId:$reason")
}
// 对战服务端异常,开发者需要退出对战、房间、队伍等状态,此时处于 connect 之后的状态
override fun onBattleServiceError() {
Log.d("Battle", "receive onBattleServiceError")
}
}
import TapOnlineBattleSDK
// 通知回调协议继承自 NSObjectProtocol,实现类需继承 NSObject
class BattleManager: NSObject, TapOnlineBattleCallback {
// 注册回调
func registerCallback() {
TapTapOnlineBattle.registerOnlineBattleCallback(self)
}
// SDK 回调实现(协议方法均为 optional,按需实现即可)
// 收到玩家自定义消息
func onCustomMessageReceived(playerId: String, msg: String) {
// TODO: 解析 msg,渲染对战状态或其他信息
}
// 与服务端连接断开,建议当错误码为网络异常时进行重连
func onDisconnected(code: Int, msg: String) {
// 当错误码为网络异常时进行重连
}
// 玩家更新自定义属性
func onPlayerCustomPropertiesChanged(playerId: String, properties: String) {
print("receive onPlayerCustomPropertiesChanged \(playerId):\(properties)")
}
// 玩家更新自定义状态
func onPlayerCustomStatusChanged(playerId: String, status: Int) {
print("receive onPlayerCustomStatusChanged \(playerId):\(status)")
}
// 玩家进入房间
func onPlayerEntered(roomId: String, playerInfo: PlayerInfo) {
print("receive onPlayerEntered \(roomId):\(playerInfo)")
}
// 玩家被踢出
func onPlayerKicked(roomId: String, playerId: String) {
print("receive onPlayerKicked \(roomId):\(playerId)")
}
// 玩家离开房间
func onPlayerLeft(roomId: String, roomOwnerId: String, playerId: String) {
print("receive onPlayerLeft \(roomId):\(roomOwnerId):\(playerId)")
}
// 玩家离线
func onPlayerOffline(roomId: String, roomOwnerId: String, playerId: String) {
print("receive onPlayerOffline \(roomId):\(roomOwnerId):\(playerId)")
}
// 房间属性变更
func onRoomPropertiesChanged(id: String, name: String, customProperties: String) {
print("receive onRoomPropertiesChanged \(id):\(name):\(customProperties)")
}
// 开始帧同步
func onFrameSyncStarted(frameSyncInfo: FrameSyncInfo) {
print("receive onFrameSyncStarted \(frameSyncInfo)")
}
// 收到帧同步数据回调
func onFrameReceived(frameData: FrameData) {
if !frameData.inputs.isEmpty {
print("receive onFrameReceived \(frameData)")
}
}
// 停止帧同步
func onFrameSyncStopped(roomId: String, frameSyncId: Int, reason: Int) {
print("receive onFrameSyncStopped \(roomId):\(frameSyncId):\(reason)")
}
// 对战服务端异常,开发者需要退出对战、房间、队伍等状态,此时处于 connect 之后的状态
func onBattleServiceError() {
print("receive onBattleServiceError")
}
}
#import <TapOnlineBattleSDK/TapOnlineBattleSDK-Swift.h>
@interface BattleManager : NSObject <TapOnlineBattleCallback>
@end
@implementation BattleManager
// 注册回调
- (void)registerCallback {
[TapTapOnlineBattle registerOnlineBattleCallback:self];
}
// SDK 回调实现(所有方法均可选)
// 收到玩家自定义消息
- (void)onCustomMessageReceivedWithPlayerId:(NSString *)playerId msg:(NSString *)msg {
// TODO: 解析 msg,渲染对战状态或其他信息
}
// 与服务端连接断开,建议当错误码为网络异常时进行重连
- (void)onDisconnectedWithCode:(NSInteger)code msg:(NSString *)msg {
// 当错误码为网络异常时进行重连
}
// 玩家更新自定义属性
- (void)onPlayerCustomPropertiesChangedWithPlayerId:(NSString *)playerId properties:(NSString *)properties {
NSLog(@"receive onPlayerCustomPropertiesChanged %@:%@", playerId, properties);
}
// 玩家更新自定义状态
- (void)onPlayerCustomStatusChangedWithPlayerId:(NSString *)playerId status:(NSInteger)status {
NSLog(@"receive onPlayerCustomStatusChanged %@:%ld", playerId, (long)status);
}
// 玩家进入房间
- (void)onPlayerEnteredWithRoomId:(NSString *)roomId playerInfo:(PlayerInfo *)playerInfo {
NSLog(@"receive onPlayerEntered %@:%@", roomId, playerInfo);
}
// 玩家被踢出
- (void)onPlayerKickedWithRoomId:(NSString *)roomId playerId:(NSString *)playerId {
NSLog(@"receive onPlayerKicked %@:%@", roomId, playerId);
}
// 玩家离开房间
- (void)onPlayerLeftWithRoomId:(NSString *)roomId roomOwnerId:(NSString *)roomOwnerId playerId:(NSString *)playerId {
NSLog(@"receive onPlayerLeft %@:%@:%@", roomId, roomOwnerId, playerId);
}
// 玩家离线
- (void)onPlayerOfflineWithRoomId:(NSString *)roomId roomOwnerId:(NSString *)roomOwnerId playerId:(NSString *)playerId {
NSLog(@"receive onPlayerOffline %@:%@:%@", roomId, roomOwnerId, playerId);
}
// 房间属性变更
- (void)onRoomPropertiesChangedWithId:(NSString *)id name:(NSString *)name customProperties:(NSString *)customProperties {
NSLog(@"receive onRoomPropertiesChanged %@:%@:%@", id, name, customProperties);
}
// 开始帧同步
- (void)onFrameSyncStartedWithFrameSyncInfo:(FrameSyncInfo *)frameSyncInfo {
NSLog(@"receive onFrameSyncStarted %@", frameSyncInfo);
}
// 收到帧同步数据回调
- (void)onFrameReceivedWithFrameData:(FrameData *)frameData {
if (frameData.inputs.count > 0) {
NSLog(@"receive onFrameReceived %@", frameData);
}
}
// 停止帧同步
- (void)onFrameSyncStoppedWithRoomId:(NSString *)roomId frameSyncId:(NSInteger)frameSyncId reason:(NSInteger)reason {
NSLog(@"receive onFrameSyncStopped %@:%ld:%ld", roomId, (long)frameSyncId, (long)reason);
}
// 对战服务端异常,开发者需要退出对战、房间、队伍等状态,此时处于 connect 之后的状态
- (void)onBattleServiceError {
NSLog(@"receive onBattleServiceError");
}
@end
建立连接
当玩家登录成功后,需建立连接后才能调用其他主要 API 业务接口,连接成功时会返回用户 ID 。示例如下:
- Unity
- Android Java
- Android Kotlin
- iOS Swift
- iOS Objective-C
using TapSDK.OnlineBattle;
try
{
string playerId = await TapTapOnlineBattle.Connect();
LogMessage("Connect success " + playerId);
}
catch (TapException e)
{
LogMessage($"Connect error {e.Code} {e.Message}");
}
import com.taptap.sdk.battle.TapTapOnlineBattle;
import com.taptap.sdk.battle.ConnectListener;
import com.taptap.sdk.battle.model.ErrorResponse;
TapTapOnlineBattle.connect(new ConnectListener() {
@Override
public void onSuccess(String playerId) {
Log.d("Battle", "Connect success " + playerId);
}
@Override
public void onFailure(ErrorResponse error) {
Log.e("Battle", "Connect error " + error.getCode() + " " + error.getMsg());
}
});
import com.taptap.sdk.battle.TapTapOnlineBattle
import com.taptap.sdk.battle.ConnectListener
import com.taptap.sdk.battle.model.ErrorResponse
import android.util.Log
TapTapOnlineBattle.connect(object : ConnectListener {
override fun onSuccess(playerId: String) {
Log.d("Battle", "Connect success $playerId")
}
override fun onFailure(error: ErrorResponse) {
Log.e("Battle", "Connect error ${error.code} ${error.msg}")
}
})
import TapOnlineBattleSDK
class MyConnectListener: ConnectListener {
func onSuccess(playerId: String) {
print("Connect success \(playerId)")
}
func onFailure(error: ErrorResponse) {
print("Connect error \(error.code) \(error.msg)")
}
}
TapTapOnlineBattle.connect(listener: MyConnectListener())
#import <TapOnlineBattleSDK/TapOnlineBattleSDK-Swift.h>
@interface MyConnectListener : NSObject <ConnectListener>
@end
@implementation MyConnectListener
- (void)onSuccessWithPlayerId:(NSString *)playerId {
NSLog(@"Connect success %@", playerId);
}
- (void)onFailureWithError:(ErrorResponse *)error {
NSLog(@"Connect error %ld %@", (long)error.code, error.msg);
}
@end
// 建立连接
[TapTapOnlineBattle connectWithListener:[[MyConnectListener alloc] init]];
断开连接
当用户不再需要使用对战服务时,可调用该接口断开连接。当用户登出、重新登录时, SDK 会自动调用该接口断开连接。
- Unity
- Android Java
- Android Kotlin
- iOS Swift
- iOS Objective-C
using TapSDK.OnlineBattle;
try
{
await TapTapOnlineBattle.Disconnect();
LogMessage(" Disconnect success ");
}
catch (TapException e)
{
LogMessage($"Disconnect error {e.Code} {e.Message}");
}
import com.taptap.sdk.battle.TapTapOnlineBattle;
import com.taptap.sdk.battle.DisconnectListener;
import com.taptap.sdk.battle.model.ErrorResponse;
TapTapOnlineBattle.disconnect(new DisconnectListener() {
@Override
public void onSuccess() {
Log.d("Battle", "Disconnect success");
}
@Override
public void onFailure(ErrorResponse error) {
Log.e("Battle", "Disconnect error " + error.getCode() + " " + error.getMsg());
}
});
import com.taptap.sdk.battle.TapTapOnlineBattle
import com.taptap.sdk.battle.DisconnectListener
import com.taptap.sdk.battle.model.ErrorResponse
import android.util.Log
TapTapOnlineBattle.disconnect(object : DisconnectListener {
override fun onSuccess() {
Log.d("Battle", "Disconnect success")
}
override fun onFailure(error: ErrorResponse) {
Log.e("Battle", "Disconnect error ${error.code} ${error.msg}")
}
})
import TapOnlineBattleSDK
class MyDisconnectListener: DisconnectListener {
func onSuccess() {
print("Disconnect success")
}
func onFailure(error: ErrorResponse) {
print("Disconnect error \(error.code) \(error.msg)")
}
}
TapTapOnlineBattle.disconnect(listener: MyDisconnectListener())
#import <TapOnlineBattleSDK/TapOnlineBattleSDK-Swift.h>
@interface MyDisconnectListener : NSObject <DisconnectListener>
@end
@implementation MyDisconnectListener
- (void)onSuccess {
NSLog(@"Disconnect success");
}
- (void)onFailureWithError:(ErrorResponse *)error {
NSLog(@"Disconnect error %ld %@", (long)error.code, error.msg);
}
@end
// 断开连接
[TapTapOnlineBattle disconnectWithListener:[[MyDisconnectListener alloc] init]];