跳到主要内容
版本:v4

开发指南

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

提示

PC 端云存档功能,使用前需接入启动校验,具体参考 TapTap PC 端集成 文档

权限说明

集成前准备

参考 准备工作 创建应用、开启云存档服务。

SDK 获取

由于 TapSDK V4 依赖于 TapTapCore 核心库以及 TapTapLogin 登录,所以需要在 TapTapCore 的基础上,另外添加 TapTapCloudSaveTapTapLogin 模块:

第一步:添加 SDK 所需的外部依赖

SDK 内部使用了部分第三方库,开发者接入时需先确保 SDK 外部依赖库已正常接入,具体设置如下:

  1. SDK 使用的 JSON 解析库为 Newtonsoft-json,如果当前工程已接入该依赖库,则不需额外处理,否则需在 Packages/manifest.json 添加如下依赖:
"com.unity.nuget.newtonsoft-json":"3.2.1"
  1. SDK 使用 com.google.external-dependency-manager 管理 Android、iOS 依赖,如果当前工程已接入该依赖库,则不需额外处理,否则需在 Packages/manifest.json 添加如下依赖:
{
"dependencies": {
"com.google.external-dependency-manager": "1.2.179"
},
"scopedRegistries": [
{
"name": "package.openupm.com",
"url": "https://package.openupm.com",
"scopes": [
"com.google.external-dependency-manager"
]
}
]
}

第二步:添加 SDK 依赖

SDK 支持 Unity Package Manager本地文件导入两种集成方式,开发者根据需求选择其中一种即可,推荐使用远程依赖。

远程依赖

SDK 支持通过 NPMJS 及 GitHub 两种方式,开发者选择其中一种即可。

1. NPMJS 接入

在项目的 Packages/manifest.json 文件中添加以下依赖:

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

但需要注意的是,需在 Packages/manifest.jsondependencies 同级下声明 scopedRegistries

"scopedRegistries":[
{
"name": "NPMJS",
"url": "https://registry.npmjs.org/",
"scopes": ["com.taptap"]
}
]
2. GitHub 接入

在项目的 Packages/manifest.json 文件中添加以下依赖:

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

说明:自 4.7.2 起,Unity Packages 仓库已统一为大仓 tapsdk-unity-dist,所有包通过目录区分并使用 ?path= 指定子目录、# 指定版本标签。例如 Core 模块:

"com.taptap.sdk.core": "https://github.com/taptap/tapsdk-unity-dist.git?path=/Core#4.7.2"

在 Unity 顶部菜单中选择 Window > Package Manager 可查看已经安装在项目中的包。

本地文件导入

  1. 下载页 下载下列模块对应 unitypackage 文件,并在 Unity 项目中依次通过 Assets > Import Packages > Custom Packages 进行导入,包括:
  • TapSDK_Core.unitypackage TapTapSDK 核心模块,必选
  • TapSDK_Login.unitypackage TapTapSDK 登录模块,必选
  • TapSDK_CloudSave.unitypackage TapTapSDK 云存档模块,必选
  1. 如果当前项目已集成 Newtonsoft.Json 依赖,则忽略该步骤,否则在 NuGet.org Newtonsoft.Json 页面中通过点击右侧 「Download package」 下载库文件,并将下载的文件后缀从.nupkg 修改为 .zip,同时解压该文件并复制内部的 Newtonsoft.Json.dll 文件拷贝到工程 AssetsPlugins 目录下,另外为了避免导出 IL2CPP 平台时删除必要数据,需在 Assets 目录下创建 link.xml 文件(如果已有该文件,则添加如下内容),其内容如下:
<linker>
<assembly fullname="System.Core">
<type fullname="System.Linq.Expressions.Interpreter.LightLambda" preserve="all" />
</assembly>
</linker>

SDK 初始化

详见 TapTapSDK 初始化文档

TapTapSdkOptions 详细参数见 入门指南#快速开始

using TapSDK.Core;
using TapSDK.CloudSave;

// 核心配置 详细参数见 [TapTapSDK]
TapTapSdkOptions coreOptions = new TapTapSdkOptions();
// TapSDK 初始化
TapTapSDK.Init(coreOptions, otherOptions);

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

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

using TapSDK.CloudSave;

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

class TapCloudSaveCallback : ITapCloudSaveCallback
{
public TapCloudSaveCallback(){}

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

创建存档

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

信息

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

存档摘要 (summary) 以及额外信息 (extra) 无此限制

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

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

// 存档元信息
ArchiveMetadata metadata = new ArchiveMetadata(
archiveName: "存档名称",
archiveSummary: "存档描述",
archiveExtra: "额外信息",
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);
// 处理存档创建成功
}
catch (TapException ex)
{
// 处理错误,可使用 ex.Code 与 ex.Message
}

获取存档列表

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

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
}

下载存档

下载指定的存档文件。

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
}

更新存档

更新指定的存档文件。

信息

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

存档摘要 (summary) 以及额外信息 (extra) 无此限制

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

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

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

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

删除存档

删除指定的存档文件。

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
}

获取存档封面

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

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
}

结果码说明

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

请求错误码

用于 onRequestError(errorCode, errorMessage) 回调中的 errorCode

错误码说明
400000非法的存档文件/封面大小
400001存档上传频率超限
400002指定的存档不存在
400003单个应用下存档数量超限
400004单个应用下使用存储空间超限
400005总使用存储空间超限
400006非法的操作令牌,通常是由于网络卡顿,创建/更新存档耗时过长导致
400007不允许并发调用
400008找不到可用的 OSS 供应商
400009存档名称不合法

国际化

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