跳到主要内容
版本：v4

Android SDK 开发指南

本文介绍如何在 Android 原生项目中接入多人联机。

集成 SDK​

集成前准备​

  1. 参考 开发者中心配置 创建应用、配置包名与签名证书
  2. 参考 Android 集成指南 完成基础接入
  3. 多人联机 SDK 依赖 TapTap 登录开发指南 ，接入前需确保已接入

权限说明​

该模块需要如下权限：

权限使用目的权限申请时机
网络权限用于正常网络访问用户首次使用该功能时会申请权限

SDK 获取​

在 app module 的 build.gradle 中添加对应依赖：

dependencies {
  implementation 'com.taptap.sdk:tap-core:4.11.0'
  implementation 'com.taptap.sdk:tap-login:4.11.0'
  implementation 'com.taptap.sdk:tap-battle:4.11.0'
}

业务流程接入​

主要业务模块及流程如下图，开发者可根据该图了解不同功能接口调用时机：

TapTap

连接管理​

注册回调​

通过实现 SDK 通知回调接口 TapOnlineBattleCallback 来接收玩家、房间信息及同步消息回调，渲染对应场景游戏页面，示例如下：

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");
    }
}

建立连接​

当玩家登录成功后，需建立连接后才能调用其他主要 API 业务接口，连接成功时会返回用户 ID 。示例如下：

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());
    }
});

断开连接​

当用户不再需要使用对战服务时，可调用该接口断开连接。当用户登出、重新登录时， SDK 会自动调用该接口断开连接。

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());
    }
});

房间管理​

房间流程

  • 房间：玩家联机的虚拟空间，每个房间有唯一的房间 ID
  • 房主：创建房间的玩家，拥有踢人、修改房间属性等权限；房主离开后，服务端会自动选择房间内一个玩家为新房主
  • 监听回调：玩家进入或离开房间时，SDK 会通过回调通知房间内其他玩家

房间信息​

当通过不同方式进入房间后，SDK 会返回房间内具体信息，包括房间属性和房间内所有玩家属性，具体参数如下：

参数名类型说明
idstring房间 ID
namestring房间名称，如果创建或更新时未设置，默认为空字符串
typestring房间类型
ownerIdstring房主 ID ，当原房主离开房间且房间内有其他玩家时，该值会变更为房间内其他玩家
statusint0-未开始帧同步，1-帧同步中
customPropertiesstring自定义房间属性
maxPlayerCountint房间最大支持人数
playersList房间内玩家信息集合
createTimestring房间创建时间，1970 年开始的秒数

其中玩家信息如下：

参数名类型说明
idstring玩家 ID
statusint玩家状态：0-离线、1-在线
customStatusint自定义玩家状态，开发者可随意设置任何值，意义由开发者自行判断
customPropertiesstring自定义玩家属性，开发者可以随意设置任何数据，最大为 2048 字节

进入房间​

进入房间有三种不同的方式，创建房间、匹配房间以及获取房间列表后加入指定房间等，通过创建房间加入时会自动成为房主。

创建房间​

在创建和匹配房间时，需要设置房间配置（必选）和玩家配置（可选），具体参数如下：

房间配置​
参数名类型说明是否必选
maxPlayerCountint房间最大支持人数，取值范围为 1 ~ 20是
typestring房间类型，最大 32 字节是
namestring房间名称，最大 64 字节，当匹配房间时，无需设置该参数否
customPropertiesstring自定义房间属性，最大 2048 字节否
matchParamsDictionary房间匹配参数，最大支持 3 个 K/V 对, K/V 取值由开发者决定，K 最大 32 字节，V 最大 64 字节否
玩家配置​
参数名类型说明是否必选
customStatusint自定义玩家状态，开发者可随意设置任何值，意义由开发者自行判断否
customPropertiesstring自定义玩家属性，开发者可以随意设置任何数据，最大为 2048 字节否

请求成功后，会返回对应房间的具体信息，示例如下：

import com.taptap.sdk.battle.TapTapOnlineBattle;
import com.taptap.sdk.battle.CreateRoomListener;
import com.taptap.sdk.battle.model.CreateRoomConfig;
import com.taptap.sdk.battle.model.RoomConfig;
import com.taptap.sdk.battle.model.PlayerConfig;
import com.taptap.sdk.battle.model.RoomInfo;
import com.taptap.sdk.battle.model.ErrorResponse;
import java.util.HashMap;
import java.util.Map;

// 定义匹配参数
Map<String, String> matchParams = new HashMap<>();
// 定义房间配置，构造参数顺序：maxPlayerCount, type, matchParams, name, customProperties
RoomConfig roomConfig = new RoomConfig(
    roomMaxPlayerCount, // 房间最大支持人数，取值范围为[1, 20]，必填
    roomType,           // 房间类型，最大32字节，必填
    matchParams,        // 房间匹配参数，选填，最大支持3个K/V对, K最大32字节，V最大64字节
    roomName,           // 房间名称，最大64个字节，选填
    roomProperty        // 自定义房间属性，最大2048字节，选填
);

// 定义玩家配置，构造参数顺序：customStatus, customProperties
PlayerConfig playerConfig = new PlayerConfig(
    playerCustomStatus, // 自定义玩家状态，整型，选填
    playerProperty      // 自定义玩家属性，选填
);

// 创建房间配置
CreateRoomConfig config = new CreateRoomConfig(roomConfig, playerConfig);

TapTapOnlineBattle.createRoom(config, new CreateRoomListener() {
    @Override
    public void onSuccess(RoomInfo roomInfo) {
        Log.d("Battle", "创建房间成功 " + roomInfo);
    }

    @Override
    public void onFailure(ErrorResponse error) {
        Log.e("Battle", "创建房间 error " + error.getCode() + " " + error.getMsg());
    }
});

匹配房间​

匹配房间时使用的配置参数和创建房间一致，当没有满足条件的房间存在时，会自动创建一个新房间， 匹配成功后返回对应的房间信息。

import com.taptap.sdk.battle.TapTapOnlineBattle;
import com.taptap.sdk.battle.MatchRoomListener;
import com.taptap.sdk.battle.model.MatchRoomConfig;
import com.taptap.sdk.battle.model.RoomConfig;
import com.taptap.sdk.battle.model.PlayerConfig;
import com.taptap.sdk.battle.model.RoomInfo;
import com.taptap.sdk.battle.model.ErrorResponse;
import java.util.HashMap;
import java.util.Map;

// 定义匹配参数
Map<String, String> matchParams = new HashMap<>();
// 定义房间配置，构造参数顺序：maxPlayerCount, type, matchParams, name, customProperties
RoomConfig roomConfig = new RoomConfig(
    roomMaxPlayerCount, // 房间最大支持人数，取值范围为[1, 20]，必填
    roomType,           // 房间类型，最大32字节，必填
    matchParams,        // 房间匹配参数，选填
    "",                 // 房间名称，匹配房间时无需设置
    roomProperty        // 自定义房间属性，最大2048字节，选填
);

// 定义玩家配置，构造参数顺序：customStatus, customProperties
PlayerConfig playerConfig = new PlayerConfig(
    playerCustomStatus, // 自定义玩家状态，整型，选填
    playerProperty      // 自定义玩家属性，选填
);

// 匹配房间配置
MatchRoomConfig config = new MatchRoomConfig(roomConfig, playerConfig);

TapTapOnlineBattle.matchRoom(config, new MatchRoomListener() {
    @Override
    public void onSuccess(RoomInfo roomInfo) {
        Log.d("Battle", "匹配房间成功 " + roomInfo);
        // 如果此时是加入已存在的房间，房间内其他玩家会通过 onPlayerEntered 回调收到通知
    }

    @Override
    public void onFailure(ErrorResponse error) {
        Log.e("Battle", "匹配房间 error " + error.getCode() + " " + error.getMsg());
    }
});

如果此时是加入已存在的房间，房间内其他玩家会通过 SDK 的 OnPlayerEntered 回调收到通知：

// 玩家进入房间
@Override
public void onPlayerEntered(String roomId, PlayerInfo playerInfo) {
    Log.d("Battle", "receive OnPlayerEntered " + roomId + ":" + playerInfo.toString());
}

获取房间列表​

开发者可通过具体房间类型获取对应房间列表数据，示例如下：

import com.taptap.sdk.battle.TapTapOnlineBattle;
import com.taptap.sdk.battle.GetRoomListListener;
import com.taptap.sdk.battle.model.RoomListData;
import com.taptap.sdk.battle.model.ErrorResponse;

TapTapOnlineBattle.getRoomList(roomType, offset, limit, new GetRoomListListener() {
    @Override
    public void onSuccess(RoomListData data) {
        Log.d("Battle", "查询房间列表成功 " + data);
    }

    @Override
    public void onFailure(ErrorResponse error) {
        Log.e("Battle", "查询房间列表 error " + error.getCode() + " " + error.getMsg());
    }
});

首次请求时，请求参数中 offset 传 0 即可。拉取下一页房间列表时，请传递上一次请求结果中的 offset 字段的值。 返回结果 RoomListData 包含三个字段 ：

  • offset：用于请求下一页房间列表的 offset 值
  • hasMore：表示是否还有更多房间，true 表示有更多房间，false 表示没有
  • rooms: 房间列表数据，包含对应类型房间的信息集合

rooms 中各房间信息字段如下：

参数名类型说明
idstring房间 ID
namestring房间名称，如果创建或更新时未设置，默认为空字符串
typestring房间类型
statusint0-未开始帧同步，1-帧同步中
customPropertiesstring自定义房间属性
maxPlayerCountint房间最大支持人数
createTimestring房间创建时间，1970 年开始的秒数

加入房间​

使用目标房间的房间 ID 可加入对应房间，成功后，会返回包含所有玩家的具体房间信息。示例如下：

import com.taptap.sdk.battle.TapTapOnlineBattle;
import com.taptap.sdk.battle.JoinRoomListener;
import com.taptap.sdk.battle.model.PlayerConfig;
import com.taptap.sdk.battle.model.RoomInfo;
import com.taptap.sdk.battle.model.ErrorResponse;

// 玩家配置
PlayerConfig playerConfig = new PlayerConfig(
    joinPlayerStatus,    // 自定义玩家状态，整形，选填
    joinPlayerProperty   // 自定义玩家属性，选填
);

TapTapOnlineBattle.joinRoom(joinRoomId, playerConfig, new JoinRoomListener() {
    @Override
    public void onSuccess(RoomInfo roomInfo) {
        Log.d("Battle", "加入房间成功 " + roomInfo);
        // 其他玩家会通过 onPlayerEntered 回调收到通知
    }

    @Override
    public void onFailure(ErrorResponse error) {
        Log.e("Battle", "加入房间 error " + error.getCode() + " " + error.getMsg());
    }
});

加入成功后其他玩家也会通过 OnPlayerEntered 回调收到通知：

// 玩家进入房间
@Override
public void onPlayerEntered(String roomId, PlayerInfo playerInfo) {
    Log.d("Battle", "receive OnPlayerEntered " + roomId + ":" + playerInfo.toString());
}

管理房间​

更新房间信息​

只有房主可更新当前房间信息，包含名称和自定义属性等，示例如下：

import com.taptap.sdk.battle.TapTapOnlineBattle;
import com.taptap.sdk.battle.UpdateRoomPropertiesListener;
import com.taptap.sdk.battle.model.ErrorResponse;

TapTapOnlineBattle.updateRoomProperties(updateRoomName, updateRoomProperty, new UpdateRoomPropertiesListener() {
    @Override
    public void onSuccess() {
        Log.d("Battle", "更新房间属性 成功");
        // 所有玩家会通过 onRoomPropertiesChanged 回调收到通知
    }

    @Override
    public void onFailure(ErrorResponse error) {
        Log.e("Battle", "更新房间属性 error " + error.getCode() + " " + error.getMsg());
    }
});

更新成功后所有玩家会通过 SDK 的 OnRoomPropertiesChanged 回调收到通知：

// 房间属性变更
@Override
public void onRoomPropertiesChanged(String id, String name, String customProperties) {
    Log.d("Battle", "receive OnRoomPropertiesChanged " + id + ":" + name + ":" + customProperties);
}

更新玩家自定义状态​

每个玩家均可更新自身的当前自定义状态，用于标识玩家在房间或对战过程中的关键状态，例如未就绪、已就绪等，示例如下：

import com.taptap.sdk.battle.TapTapOnlineBattle;
import com.taptap.sdk.battle.UpdatePlayerCustomStatusListener;
import com.taptap.sdk.battle.model.ErrorResponse;

// updatePlayerStatus 玩家自定义状态，例如 0 未就绪 1 已就绪
TapTapOnlineBattle.updatePlayerCustomStatus(updatePlayerStatus, new UpdatePlayerCustomStatusListener() {
    @Override
    public void onSuccess() {
        Log.d("Battle", "更新玩家状态 成功");
        // 房间内玩家会通过 onPlayerCustomStatusChanged 回调收到通知
    }

    @Override
    public void onFailure(ErrorResponse error) {
        Log.e("Battle", "更新玩家状态 error " + error.getCode() + " " + error.getMsg());
    }
});

更新成功后，房间内玩家会通过 SDK 的 OnPlayerCustomStatusChanged 回调收到通知：

// 玩家更新自定义状态
@Override
public void onPlayerCustomStatusChanged(String playerId, int status) {
    Log.d("Battle", "receive OnPlayerCustomStatusChanged " + playerId + ":" + status);
}

更新玩家自定义属性​

每个玩家均可更新自身的自定义属性数据，可用于设置玩家的基础用户信息、游戏等级等数据，示例如下：

import com.taptap.sdk.battle.TapTapOnlineBattle;
import com.taptap.sdk.battle.UpdatePlayerCustomPropertiesListener;
import com.taptap.sdk.battle.model.ErrorResponse;

TapTapOnlineBattle.updatePlayerCustomProperties(updatePlayerProperty, new UpdatePlayerCustomPropertiesListener() {
    @Override
    public void onSuccess() {
        Log.d("Battle", "更新玩家属性 成功");
        // 房间内玩家会通过 onPlayerCustomPropertiesChanged 回调收到通知
    }

    @Override
    public void onFailure(ErrorResponse error) {
        Log.e("Battle", "更新玩家属性 error " + error.getCode() + " " + error.getMsg());
    }
});

更新成功后，房间内玩家会通过 SDK 的 OnPlayerCustomPropertiesChanged 回调收到通知：

// 玩家更新自定义属性
@Override
public void onPlayerCustomPropertiesChanged(String playerId, String properties) {
    Log.d("Battle", "receive OnPlayerCustomPropertiesChanged " + playerId + ":" + properties);
}

离开房间​

当房间内玩家需要离开当前房间时，可调用如下接口：

import com.taptap.sdk.battle.TapTapOnlineBattle;
import com.taptap.sdk.battle.LeaveRoomListener;
import com.taptap.sdk.battle.model.ErrorResponse;

TapTapOnlineBattle.leaveRoom(new LeaveRoomListener() {
    @Override
    public void onSuccess() {
        Log.d("Battle", "离开房间成功");
        // 房间内其他玩家通过 onPlayerLeft 收到通知
    }

    @Override
    public void onFailure(ErrorResponse error) {
        Log.e("Battle", "离开房间 error " + error.getCode() + " " + error.getMsg());
    }
});

调用成功后，房间内其他玩家通过 SDK 的 OnPlayerLeft 收到通知，如果离开的玩家是房主，则会重新指定房间内其他玩家为房主。

// 玩家离开房间
@Override
public void onPlayerLeft(String roomId, String roomOwnerId, String playerId) {
    Log.d("Battle", "receive OnPlayerLeft " + roomId + ":" + roomOwnerId + ":" + playerId);
}

踢出玩家​

当房主需要将玩家踢出房间时，可调用如下接口：

import com.taptap.sdk.battle.TapTapOnlineBattle;
import com.taptap.sdk.battle.KickRoomPlayerListener;
import com.taptap.sdk.battle.model.ErrorResponse;

// kickPlayerId 玩家 ID
TapTapOnlineBattle.kickRoomPlayer(kickPlayerId, new KickRoomPlayerListener() {
    @Override
    public void onSuccess() {
        Log.d("Battle", "踢出玩家 成功");
    }

    @Override
    public void onFailure(ErrorResponse error) {
        Log.e("Battle", "踢出玩家 error " + error.getCode() + " " + error.getMsg());
    }
});

调用成功后，对应玩家会通过 SDK 的 OnPlayerKicked 回调收到通知：

// 玩家被踢出
@Override
public void onPlayerKicked(String roomId, String playerId) {
    Log.d("Battle", "receive OnPlayerKicked " + roomId + ":" + playerId);
}

房间内数据传输​

进入房间后，可通过发送自定义消息或发送帧输入（房主开启帧同步后）同步游戏数据。

  • 自定义消息：适合回合制、棋牌等对实时性要求不高的场景
  • 帧同步：适合格斗、MOBA、FPS 等高实时性游戏

详细用法见数据传输。