Skip to main content
Version: v4

开发指南

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

tip

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

权限说明​

集成前准备​

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

SDK 获取​

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

第一步：添加 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.2",
   "com.taptap.sdk.login":"4.8.2",
   "com.taptap.sdk.cloudsave":"4.8.2",
}

但需要注意的是，需在 Packages/manifest.json 中 dependencies 同级下声明 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.2",
   "com.taptap.sdk.login":"https://github.com/taptap/tapsdk-unity-dist.git?path=/Login#4.8.2",
   "com.taptap.sdk.cloudsave":"https://github.com/taptap/tapsdk-unity-dist.git?path=/CloudSave#4.8.2",
}

说明：自 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 文件拷贝到工程 Assets 的 Plugins 目录下，另外为了避免导出 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：初始化失败 需要重新初始化
    }
}

创建存档​

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

info

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

存档摘要 (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
    }

更新存档​

更新指定的存档文件。

info

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

存档摘要 (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 支持设置语言：目前只支持简体中文