Android SDK 开发指南
本文介绍如何在游戏中加入云存档功能。
集成前准备
- 参考 开发者中心配置 创建应用、开启云存档服务
- 参考 Android 集成指南 完成基础接入
- 云存档模块依赖于 TapTap 登录模块,开发者接入前应先完成 TapTap 登录的接入
权限说明
该模块需要如下权限:
| 权限 | 使用目的 | 权限申请时机 |
|---|---|---|
| 网络权限 | 用于访问网络数据 | 用户首次使用该功能时会申请权限 |
| 网络状态权限 | 用于检查网络连接状态(如 Wi-Fi 或移动数据是否可用) | 用户首次使用该功能时会申请权限 |
该模块将在应用中添加如下权限:
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
SDK 获取
在 app module 的 build.gradle 中添加对应依赖:
dependencies {
implementation 'com.taptap.sdk:tap-core:4.11.1'
implementation 'com.taptap.sdk:tap-login:4.11.1'
implementation 'com.taptap.sdk:tap-cloudsave:4.11.1'
}
注册/注销统一状态码监听回调
统一状态回调,不同 code 代表不同的状态。
- Android Java
- Android Kotlin
import com.taptap.sdk.cloudsave.internal.TapCloudSaveCallback;
import com.taptap.sdk.cloudsave.TapTapCloudSave;
TapCloudSaveCallback callback = new TapCloudSaveCallback(){
@Override
public void onResult(int resultCode) {
// 处理云存档的状态码
// 300001:需要登录
// 300002:初始化失败 需重新初始化
}
};
TapTapCloudSave.registerCloudSaveCallback(callback);
// 不再接收状态时,传入同一个回调对象注销
TapTapCloudSave.unregisterCloudSaveCallback(callback);
import com.taptap.sdk.cloudsave.internal.TapCloudSaveCallback
import com.taptap.sdk.cloudsave.TapTapCloudSave
private val cloudSaveCallback = object : TapCloudSaveCallback {
override fun onResult(resultCode: Int) {
// 处理云存档的状态码
// 300001:需要登录
// 300002:初始化失败 需重新初始化
}
}
TapTapCloudSave.registerCloudSaveCallback(cloudSaveCallback)
// 不再接收状态时,传入同一个回调对象注销
TapTapCloudSave.unregisterCloudSaveCallback(cloudSaveCallback)
参数说明:
| 方法 | 参数 | 类型 | 说明 |
|---|---|---|---|
registerCloudSaveCallback | callback | TapCloudSaveCallback | 接收需要登录、初始化失败等模块状态。当前实现只保留最近一次注册的状态回调。 |
unregisterCloudSaveCallback | callback | TapCloudSaveCallback | 注销状态回调,需传入注册时的同一个对象。 |
状态码取值见结果码说明。状态回调不返回单次创建、下载等请求的结果;各请求结果由 TapCloudSaveRequestCallback 返回。
创建存档
创建游戏存档并上传云端。
存档名称仅支持【英文/数字/下划线/中划线】,不支持中文
存档摘要 (summary) 以及额外信息 (extra) 无此限制,但 summary 不能为空字符串
一分钟内最多可调用 60 次(与更新存档共享冷却时间)
- Android Java
- Android Kotlin
import androidx.annotation.NonNull;
import com.taptap.sdk.cloudsave.ArchiveData;
import com.taptap.sdk.cloudsave.ArchiveMetadata;
import com.taptap.sdk.cloudsave.TapTapCloudSave;
import com.taptap.sdk.cloudsave.internal.TapCloudSaveRequestCallback;
// 存档元信息
ArchiveMetadata metadata = new ArchiveMetadata.Builder()
.setName("archive_name") // 存档名称
.setSummary("archive_desc") // 存档描述
.setExtra("extra_info") // 额外信息
.setPlaytime(0) // 游戏时长(秒)
.build();
// 存档文件路径(单个存档文件大小不超过10MB)
String archiveFilePath = "path/to/archive/file";
// 存档封面路径(可选,封面大小不超过512KB)
String archiveCoverPath = "path/to/cover/image";
// 请求回调
TapCloudSaveRequestCallback callback = new TapCloudSaveRequestCallback() {
@Override
public void onRequestError(int errorCode, @NonNull String errorMessage) {
// 处理请求错误
}
@Override
public void onArchiveCreated(@NonNull ArchiveData archive) {
// 创建成功,archive.uuid 为云存档唯一标识
// archive.fileId 为存档文件标识
}
};
TapTapCloudSave.createArchive(metadata, archiveFilePath, archiveCoverPath, callback);
import com.taptap.sdk.cloudsave.ArchiveData
import com.taptap.sdk.cloudsave.ArchiveMetadata
import com.taptap.sdk.cloudsave.TapTapCloudSave
import com.taptap.sdk.cloudsave.internal.TapCloudSaveRequestCallback
// 存档元信息
val metadata = ArchiveMetadata.Builder()
.setName("archive_name") // 存档名称
.setSummary("archive_desc") // 存档描述
.setExtra("extra_info") // 额外信息
.setPlaytime(0) // 游戏时长(秒)
.build()
// 存档文件路径(单个存档文件大小不超过10MB)
val archiveFilePath = "path/to/archive/file"
// 存档封面路径(可选,封面大小不超过512KB)
val archiveCoverPath = "path/to/cover/image"
// 请求回调
val callback = object : TapCloudSaveRequestCallback {
override fun onRequestError(errorCode: Int, errorMessage: String) {
// 处理请求错误
}
override fun onArchiveCreated(archive: ArchiveData) {
// 创建成功,archive.uuid 为云存档唯一标识
// archive.fileId 为存档文件标识
}
}
TapTapCloudSave.createArchive(metadata, archiveFilePath, archiveCoverPath, callback)
参数说明:
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
archiveMetadata | ArchiveMetadata | 是 | 存档元信息,字段说明见下表。 |
archiveFilePath | String | 是 | 本地存档文件路径。SDK 会读取该路径对应的文件并上传,文件大小不能超过 10 MB。 |
archiveCoverPath | String | 否 | 本地封面文件路径。传入 null 或空字符串表示不上传封面,封面大小不能超过 512 KB。 |
callback | TapCloudSaveRequestCallback | 是 | 接收创建存档的成功或失败结果。 |
ArchiveMetadata.Builder 字段:
| Builder 方法 | 字段类型 | 必填 | 说明 |
|---|---|---|---|
setName(name) | String | 是 | 存档名称,不能为空,最多 60 字节;仅支持英文字母、数字、下划线和中划线。 |
setSummary(summary) | String | 是 | 存档描述,不能为空,最多 500 字节。 |
setExtra(extra) | String | 否 | 开发者自定义信息,最多 1000 字节,允许为空。可用于记录存档版本等业务信息。 |
setPlaytime(playtime) | Int | 是 | 当前存档对应的游戏时长,单位为秒,必须是非负数。Builder 默认值为 -1,因此需要显式设置。 |
创建成功后返回 ArchiveData。其中 uuid 和 fileId 由服务端生成,name、summary、extra 和 playtime 由 SDK 从本次请求的元信息中补充:
| 字段 | 类型 | 说明 |
|---|---|---|
uuid | String | 云存档的唯一标识,用于更新或删除存档。 |
fileId | String | 存档文件标识,与 uuid 一起用于下载存档数据或封面。 |
name | String | 存档名称。 |
summary | String | 存档描述。 |
extra | String | 开发者写入的自定义信息。 |
playtime | Int | 游戏时长,单位为秒。 |
saveSize | Long | 存档文件大小,单位为字节。创建结果不保证返回该字段,未返回时为 -1。 |
coverSize | Long | 存档封面大小,单位为字节。创建结果不保证返回该字段,未返回时为 -1。 |
createdTime | Long | 存档创建时间,秒级时间戳。创建结果不保证返回该字段,未返回时为 -1。 |
modifiedTime | Long | 存档最后修改时间,秒级时间戳。创建结果不保证返回该字段,未返回时为 -1。 |
如需读取包含文件大小和时间信息的完整存档数据,请调用获取存档列表接口。
获取存档列表
获取当前用户的存档列表。
- Android Java
- Android Kotlin
import androidx.annotation.NonNull;
import com.taptap.sdk.cloudsave.ArchiveData;
import com.taptap.sdk.cloudsave.TapTapCloudSave;
import com.taptap.sdk.cloudsave.internal.TapCloudSaveRequestCallback;
import java.util.List;
TapCloudSaveRequestCallback callback = new TapCloudSaveRequestCallback() {
@Override
public void onArchiveListResult(@NonNull List<ArchiveData> archiveList) {
// 处理存档列表
}
@Override
public void onRequestError(int errorCode, @NonNull String errorMessage) {
// 处理请求错误
}
};
TapTapCloudSave.getArchiveList(callback);
import com.taptap.sdk.cloudsave.ArchiveData
import com.taptap.sdk.cloudsave.TapTapCloudSave
import com.taptap.sdk.cloudsave.internal.TapCloudSaveRequestCallback
val callback = object : TapCloudSaveRequestCallback {
override fun onArchiveListResult(archiveList: List<ArchiveData>) {
// 处理存档列表
}
override fun onRequestError(errorCode: Int, errorMessage: String) {
// 处理请求错误
}
}
TapTapCloudSave.getArchiveList(callback)
参数说明:
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
callback | TapCloudSaveRequestCallback | 是 | 接收存档列表或请求失败结果;没有存档时列表为空。 |
列表中的每一项均为 ArchiveData,字段说明见创建存档中的返回字段表。
下载存档
下载指定的存档文件。
- Android Java
- Android Kotlin
import androidx.annotation.NonNull;
import com.taptap.sdk.cloudsave.TapTapCloudSave;
import com.taptap.sdk.cloudsave.internal.TapCloudSaveRequestCallback;
// 存档UUID
String archiveUuid = "archive_uuid";
// 存档文件ID
String archiveFileId = "archive_file_id";
TapCloudSaveRequestCallback callback = new TapCloudSaveRequestCallback() {
@Override
public void onArchiveDataResult(@NonNull byte[] archiveData) {
// 处理下载的存档数据
}
@Override
public void onRequestError(int errorCode, @NonNull String errorMessage) {
// 处理请求错误
}
};
TapTapCloudSave.getArchiveData(archiveUuid, archiveFileId, callback);
import com.taptap.sdk.cloudsave.TapTapCloudSave
import com.taptap.sdk.cloudsave.internal.TapCloudSaveRequestCallback
// 存档UUID
val archiveUuid = "archive_uuid"
// 存档文件ID
val archiveFileId = "archive_file_id"
val callback = object : TapCloudSaveRequestCallback {
override fun onArchiveDataResult(archiveData: ByteArray) {
// 处理下载的存档数据
}
override fun onRequestError(errorCode: Int, errorMessage: String) {
// 处理请求错误
}
}
TapTapCloudSave.getArchiveData(archiveUuid, archiveFileId, callback)
参数说明:
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
archiveUUID | String | 是 | 云存档唯一标识,使用创建存档或获取存档列表时返回的 ArchiveData.uuid。 |
archiveFileID | String | 是 | 存档文件标识,使用同一条 ArchiveData 中的 fileId。 |
callback | TapCloudSaveRequestCallback | 是 | 接收存档文件的原始字节数据或请求失败结果;游戏需要自行解析数据或写入本地文件。 |
更新存档
更新指定的存档文件。
存档名称仅支持【英文/数字/下划线/中划线】,不支持中文
存档摘要 (summary) 以及额外信息 (extra) 无此限制,但 summary 不能为空字符串
一分钟内最多可调用 60 次(与创建存档共享冷却时间)
- Android Java
- Android Kotlin
import androidx.annotation.NonNull;
import com.taptap.sdk.cloudsave.ArchiveData;
import com.taptap.sdk.cloudsave.ArchiveMetadata;
import com.taptap.sdk.cloudsave.TapTapCloudSave;
import com.taptap.sdk.cloudsave.internal.TapCloudSaveRequestCallback;
// 存档UUID
String archiveUuid = "archive_uuid";
// 存档元信息
ArchiveMetadata metadata = new ArchiveMetadata.Builder()
.setName("new_archive_name") // 更新后的存档名称
.setSummary("new_archive_desc") // 更新后的存档描述
.setExtra("extra") // 额外信息
.setPlaytime(0) // 游戏时长(秒)
.build();
// 新的存档文件路径(单个存档文件大小不超过10MB)
String archiveFilePath = "path/to/new/archive/file";
// 新的存档封面路径(可选,封面大小不超过512KB)
String archiveCoverPath = "path/to/new/cover/image";
TapCloudSaveRequestCallback callback = new TapCloudSaveRequestCallback() {
@Override
public void onArchiveUpdated(@NonNull ArchiveData archive) {
// 处理存档更新成功
}
@Override
public void onRequestError(int errorCode, @NonNull String errorMessage) {
// 处理请求错误
}
};
TapTapCloudSave.updateArchive(archiveUuid, metadata, archiveFilePath, archiveCoverPath, callback);
import com.taptap.sdk.cloudsave.ArchiveData
import com.taptap.sdk.cloudsave.ArchiveMetadata
import com.taptap.sdk.cloudsave.TapTapCloudSave
import com.taptap.sdk.cloudsave.internal.TapCloudSaveRequestCallback
// 存档UUID
val archiveUuid = "archive_uuid"
// 存档元信息
val metadata = ArchiveMetadata.Builder()
.setName("new_archive_name") // 更新后的存档名称
.setSummary("new_archive_desc") // 更新后的存档描述
.setExtra("extra") // 额外信息
.setPlaytime(0) // 游戏时长(秒)
.build()
// 新的存档文件路径(单个存档文件大小不超过10MB)
val archiveFilePath = "path/to/new/archive/file"
// 新的存档封面路径(可选,封面大小不超过512KB)
val archiveCoverPath = "path/to/new/cover/image"
val callback = object : TapCloudSaveRequestCallback {
override fun onArchiveUpdated(archive: ArchiveData) {
// 处理存档更新成功
}
override fun onRequestError(errorCode: Int, errorMessage: String) {
// 处理请求错误
}
}
TapTapCloudSave.updateArchive(archiveUuid, metadata, archiveFilePath, archiveCoverPath, callback)
参数说明:
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
archiveUUID | String | 是 | 要更新的云存档唯一标识,使用创建存档或获取存档列表时返回的 ArchiveData.uuid。 |
archiveMetadata | ArchiveMetadata | 是 | 更新后的完整存档元信息,字段限制与创建存档一致。 |
archiveFilePath | String | 是 | 新的本地存档文件路径。SDK 会读取并上传该文件,文件大小不能超过 10 MB。 |
archiveCoverPath | String | 否 | 新的本地封面文件路径。传入 null 或空字符串表示不上传封面,封面大小不能超过 512 KB。 |
callback | TapCloudSaveRequestCallback | 是 | 接收更新后的存档数据或请求失败结果;后续操作应使用成功结果中的 uuid 和 fileId。 |
删除存档
删除指定的存档文件。
- Android Java
- Android Kotlin
import androidx.annotation.NonNull;
import com.taptap.sdk.cloudsave.ArchiveData;
import com.taptap.sdk.cloudsave.TapTapCloudSave;
import com.taptap.sdk.cloudsave.internal.TapCloudSaveRequestCallback;
// 存档UUID
String archiveUuid = "archive_uuid";
TapCloudSaveRequestCallback callback = new TapCloudSaveRequestCallback() {
@Override
public void onArchiveDeleted(@NonNull ArchiveData archive) {
// 处理存档删除成功
}
@Override
public void onRequestError(int errorCode, @NonNull String errorMessage) {
// 处理请求错误
}
};
TapTapCloudSave.deleteArchive(archiveUuid, callback);
import com.taptap.sdk.cloudsave.ArchiveData
import com.taptap.sdk.cloudsave.TapTapCloudSave
import com.taptap.sdk.cloudsave.internal.TapCloudSaveRequestCallback
// 存档UUID
val archiveUuid = "archive_uuid"
val callback = object : TapCloudSaveRequestCallback {
override fun onArchiveDeleted(archive: ArchiveData) {
// 处理存档删除成功
}
override fun onRequestError(errorCode: Int, errorMessage: String) {
// 处理请求错误
}
}
TapTapCloudSave.deleteArchive(archiveUuid, callback)
参数说明:
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
archiveUUID | String | 是 | 要删除的云存档唯一标识,使用创建存档或获取存档列表时返回的 ArchiveData.uuid。 |
callback | TapCloudSaveRequestCallback | 是 | 接收被删除的存档数据或请求失败结果。 |
获取存档封面
获取指定存档的封面图片。
- Android Java
- Android Kotlin
import androidx.annotation.NonNull;
import com.taptap.sdk.cloudsave.TapTapCloudSave;
import com.taptap.sdk.cloudsave.internal.TapCloudSaveRequestCallback;
// 存档UUID
String archiveUuid = "archive_uuid";
// 存档文件ID
String archiveFileId = "archive_file_id";
TapCloudSaveRequestCallback callback = new TapCloudSaveRequestCallback() {
@Override
public void onArchiveCoverResult(@NonNull byte[] coverData) {
// 处理封面数据
}
@Override
public void onRequestError(int errorCode, @NonNull String errorMessage) {
// 处理请求错误
}
};
TapTapCloudSave.getArchiveCover(archiveUuid, archiveFileId, callback);
import com.taptap.sdk.cloudsave.TapTapCloudSave
import com.taptap.sdk.cloudsave.internal.TapCloudSaveRequestCallback
// 存档UUID
val archiveUuid = "archive_uuid"
// 存档文件ID
val archiveFileId = "archive_file_id"
val callback = object : TapCloudSaveRequestCallback {
override fun onArchiveCoverResult(coverData: ByteArray) {
// 处理封面数据
}
override fun onRequestError(errorCode: Int, errorMessage: String) {
// 处理请求错误
}
}
TapTapCloudSave.getArchiveCover(archiveUuid, archiveFileId, callback)
参数说明:
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
archiveUUID | String | 是 | 云存档唯一标识,使用创建存档或获取存档列表时返回的 ArchiveData.uuid。 |
archiveFileID | String | 是 | 存档文件标识,使用同一条 ArchiveData 中的 fileId。 |
callback | TapCloudSaveRequestCallback | 是 | 接收封面文件的原始字节数据或请求失败结果;游戏需要自行解码数据或写入本地文件。 |
云存档请求异步执行。若需要在回调中更新界面,请先切换到 Android 主线程。
结果码说明
| 结果码 | 说明 |
|---|---|
| 300001 | 需要登录 |
| 300002 | 初始化失败,需要重新初始化 |
请求错误码
以下错误码会在请求失败时返回。
| 错误码 | 说明 |
|---|---|
| 400000 | 非法的存档文件/封面大小 |
| 400001 | 存档上传频率超限 |
| 400002 | 指定的存档不存在 |
| 400003 | 单个应用下存档数量超限 |
| 400004 | 单个应用下使用存储空间超限 |
| 400005 | 总使用存储空间超限 |
| 400006 | 创建/更新云存档超时,通常是由于网络卡顿,耗时过长导致 |
| 400007 | 上传云存档并发调用次数超过 10 个,或者并发更新同一个云存档 |
| 400008 | 找不到可用的 OSS 供应商 |
| 400009 | 存档名称不合法 |
| 400010 | 禁止同一台机器同一个ClientID多个进程使用同一账号 |
国际化
TapTapCloudSave 支持设置语言:目前只支持简体中文