跳到主要内容
版本:v4

Unity SDK 开发指南

本文介绍如何在游戏中加入云存档功能。

集成前准备​

  1. 参考 开发者中心配置 创建应用、开启云存档服务
  2. 参考 Unity 集成指南 完成基础接入,对于 Tap PC 平台,使用前还需接入启动校验
  3. 云存档模块依赖于 TapTap 登录模块,开发者接入前应先完成 TapTap 登录的接入

权限说明​

Android 权限说明​

该模块在 Android 平台需要如下权限:

权限使用目的权限申请时机
网络权限用于访问网络数据用户首次使用该功能时会申请权限
网络状态权限用于检查网络连接状态(如 Wi-Fi 或移动数据是否可用)用户首次使用该功能时会申请权限

该模块将在 Android 应用中添加如下权限:

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

SDK 获取​

远程依赖​

NPMJS 方式:在 Packages/manifest.json 中添加:

"dependencies":{
"com.taptap.sdk.core":"4.11.1",
"com.taptap.sdk.login":"4.11.1",
"com.taptap.sdk.cloudsave":"4.11.1"
}

GitHub 方式:在 Packages/manifest.json 中添加:

"dependencies":{
"com.taptap.sdk.core":"https://github.com/taptap/tapsdk-unity-dist.git?path=/Core#4.11.1",
"com.taptap.sdk.login":"https://github.com/taptap/tapsdk-unity-dist.git?path=/Login#4.11.1",
"com.taptap.sdk.cloudsave":"https://github.com/taptap/tapsdk-unity-dist.git?path=/CloudSave#4.11.1"
}

本地文件导入​

在 下载页 下载并导入以下 unitypackage 文件:

  • TapSDK_Core.unitypackage (TapTapSDK 核心模块,必选)
  • TapSDK_Login.unitypackage(TapTapSDK 登录模块,必选)
  • TapSDK_CloudSave.unitypackage (TapTapSDK 云存档模块,必选)

注册/注销统一状态码监听回调​

统一状态回调,不同 code 代表不同的状态。

using TapSDK.CloudSave;

TapCloudSaveCallback callback = new TapCloudSaveCallback();
TapTapCloudSave.RegisterCloudSaveCallback(callback);

// 不需要接收回调时,传入同一个回调对象注销
TapTapCloudSave.UnregisterCloudSaveCallback(callback);

class TapCloudSaveCallback : ITapCloudSaveCallback
{
public TapCloudSaveCallback(){}

public void OnResult(int resultCode)
{
// 处理状态码
// 300001:需要登录
// 300002:初始化失败 需要重新初始化
}
}

参数说明:

方法参数类型说明
RegisterCloudSaveCallbackcallbackITapCloudSaveCallback接收需要登录、初始化失败等模块状态。
UnregisterCloudSaveCallbackcallbackITapCloudSaveCallback注销状态回调,需传入注册时的同一个对象。

状态码取值见结果码说明。状态回调不返回单次创建、下载等请求的结果;各请求结果由接口返回的 Task 提供。

创建存档​

创建游戏存档并上传云端。

信息

存档名称仅支持【英文/数字/下划线/中划线】,不支持中文

存档摘要 (summary) 以及额外信息 (extra) 无此限制,但 summary 不能为空字符串

一分钟内最多可调用 60 次(与更新存档共享冷却时间)

using System.Threading.Tasks;
using TapSDK.Core;
using TapSDK.CloudSave;

// 存档元信息
ArchiveMetadata metadata = new ArchiveMetadata(
archiveName: "archive_name", // 存档名称
archiveSummary: "archive_desc", // 存档描述
archiveExtra: "extra_info", // 额外信息
archivePlaytime: 0 // 游戏时长(秒)
);
// 存档文件路径(单个存档文件大小不超过10MB)
string archiveFilePath = "path/to/archive/file";
// 存档封面路径(可选,封面大小不超过512KB)
string archiveCoverPath = "path/to/cover/image";

try
{
ArchiveData archive = await TapTapCloudSave.CreateArchive(metadata, archiveFilePath, archiveCoverPath);
// 创建成功,archive.Uuid 为云存档唯一标识
// archive.FileId 为存档文件标识
}
catch (TapException ex)
{
// 处理错误,可使用 ex.Code 与 ex.Message
}

参数说明:

参数类型必填说明
metadataArchiveMetadata是存档元信息,字段说明见下表。
archiveFilePathString是本地存档文件路径。SDK 会读取该路径对应的文件并上传,文件大小不能超过 10 MB。
archiveCoverPathString否本地封面文件路径。传入空值或空字符串表示不上传封面,封面大小不能超过 512 KB。

ArchiveMetadata 字段:

字段类型必填说明
archiveNameString是存档名称,不能为空,最多 60 字节;仅支持英文字母、数字、下划线和中划线。
archiveSummaryString是存档描述,不能为空,最多 500 字节。
archiveExtraString否开发者自定义信息,最多 1000 字节,允许为空。可用于记录存档版本等业务信息。
archivePlaytimeInteger是当前存档对应的游戏时长,单位为秒,必须是非负数。

创建成功后返回 ArchiveData:

字段类型说明
UuidString云存档的唯一标识,用于更新或删除存档。
FileIdString存档文件标识,与 Uuid 一起用于下载存档数据或封面。
NameString存档名称。创建结果不保证返回该字段。
SummaryString存档描述。创建结果不保证返回该字段。
ExtraString开发者写入的自定义信息。创建结果不保证返回该字段。
PlaytimeInteger游戏时长,单位为秒。创建结果不保证返回该字段。
ArchiveFileSizeInteger存档文件大小,单位为字节。创建结果不保证返回该字段。
ArchiveCoverSizeInteger存档封面大小,单位为字节。创建结果不保证返回该字段。
CreatedTimeInteger存档创建时间,秒级时间戳。创建结果不保证返回该字段。
ModifiedTimeInteger存档最后修改时间,秒级时间戳。创建结果不保证返回该字段。

如需读取完整的存档元信息,请调用获取存档列表接口。

获取存档列表​

获取当前用户的存档列表。

using System.Collections.Generic;
using System.Threading.Tasks;
using TapSDK.Core;
using TapSDK.CloudSave;

try
{
List<ArchiveData> archives = await TapTapCloudSave.GetArchiveList();
// 处理存档列表
}
catch (TapException ex)
{
// 处理错误,可使用 ex.Code 与 ex.Message
}

参数说明:无。

返回存档数据列表;列表中的每一项均为 ArchiveData,字段说明见创建存档中的返回字段表。没有存档时返回空列表。

下载存档​

下载指定的存档文件。

using System.Threading.Tasks;
using TapSDK.Core;
using TapSDK.CloudSave;

// 存档UUID
string archiveUuid = "archive_uuid";
// 存档文件ID
string archiveFileId = "archive_file_id";

try
{
byte[] data = await TapTapCloudSave.GetArchiveData(archiveUuid, archiveFileId);
// 处理下载的存档数据
}
catch (TapException ex)
{
// 处理错误,可使用 ex.Code 与 ex.Message
}

参数说明:

参数类型必填说明
archiveUuidString是云存档的唯一标识,即 ArchiveData.Uuid。
archiveFileIdString是存档文件标识,即 ArchiveData.FileId。

接口返回存档文件的原始二进制数据,游戏需要自行解析数据或写入本地文件。

更新存档​

更新指定的存档文件。

信息

存档名称仅支持【英文/数字/下划线/中划线】,不支持中文

存档摘要 (summary) 以及额外信息 (extra) 无此限制,但 summary 不能为空字符串

一分钟内最多可调用 60 次(与创建存档共享冷却时间)

using System.Threading.Tasks;
using TapSDK.Core;
using TapSDK.CloudSave;

// 存档UUID
string archiveUuid = "archive_uuid";
// 存档元信息
ArchiveMetadata metadata = new ArchiveMetadata(
archiveName: "new_archive_name", // 更新后的存档名称
archiveSummary: "new_archive_desc", // 更新后的存档描述
archiveExtra: "extra", // 额外信息
archivePlaytime: 0
);
// 新的存档文件路径(单个存档文件大小不超过10MB)
string archiveFilePath = "path/to/new/archive/file";
// 新的存档封面路径(可选,封面大小不超过512KB)
string archiveCoverPath = "path/to/new/cover/image";

try
{
ArchiveData updated = await TapTapCloudSave.UpdateArchive(archiveUuid, metadata, archiveFilePath, archiveCoverPath);
// 处理存档更新成功
}
catch (TapException ex)
{
// 处理错误,可使用 ex.Code 与 ex.Message
}

参数说明:

参数类型必填说明
archiveUuidString是要更新的云存档唯一标识,即 ArchiveData.Uuid。
metadataArchiveMetadata是更新后的存档元信息,字段说明见创建存档中的 ArchiveMetadata 字段表。
archiveFilePathString是更新后的本地存档文件路径。SDK 会读取该路径对应的文件并上传,文件大小不能超过 10 MB。
archiveCoverPathString否更新后的本地封面文件路径。传入空值或空字符串表示不上传封面,封面大小不能超过 512 KB。

接口返回更新后的 ArchiveData。

删除存档​

删除指定的存档文件。

using System.Threading.Tasks;
using TapSDK.Core;
using TapSDK.CloudSave;

// 存档UUID
string archiveUuid = "archive_uuid";

try
{
ArchiveData deleted = await TapTapCloudSave.DeleteArchive(archiveUuid);
// 处理存档删除成功
}
catch (TapException ex)
{
// 处理错误,可使用 ex.Code 与 ex.Message
}

参数说明:

参数类型必填说明
archiveUuidString是要删除的云存档唯一标识,即 ArchiveData.Uuid。

接口返回已删除存档的 ArchiveData。

获取存档封面​

获取指定存档的封面图片。

using System.Threading.Tasks;
using TapSDK.Core;
using TapSDK.CloudSave;

// 存档UUID
string archiveUuid = "archive_uuid";
// 存档文件ID
string archiveFileId = "archive_file_id";

try
{
byte[] cover = await TapTapCloudSave.GetArchiveCover(archiveUuid, archiveFileId);
// 处理封面数据
}
catch (TapException ex)
{
// 处理错误,可使用 ex.Code 与 ex.Message
}

参数说明:

参数类型必填说明
archiveUuidString是云存档的唯一标识,即 ArchiveData.Uuid。
archiveFileIdString是存档文件标识,即 ArchiveData.FileId。

接口返回封面文件的原始二进制数据。

结果码说明​

结果码说明
300001需要登录
300002初始化失败,需要重新初始化

请求错误码​

请求失败时会抛出 TapException,以下错误码通过 ex.Code 返回。

错误码说明
400000非法的存档文件/封面大小
400001存档上传频率超限
400002指定的存档不存在
400003单个应用下存档数量超限
400004单个应用下使用存储空间超限
400005总使用存储空间超限
400006创建/更新云存档超时,通常是由于网络卡顿,耗时过长导致
400007上传云存档并发调用次数超过 10 个,或者并发更新同一个云存档
400008找不到可用的 OSS 供应商
400009存档名称不合法
400010禁止同一台机器同一个ClientID多个进程使用同一账号

国际化​

TapTapCloudSave 支持设置语言:目前只支持简体中文