UE5 SDK 开发指南
本文介绍如何在游戏中加入云存档功能。
集成前准备
- 参考开发者中心配置创建应用、开启云存档服务
- 参考 UE5 集成指南完成 TapSDK 基础接入;在 Tap PC 平台使用云存档前,还需接入启动校验
- 云存档模块依赖于 TapTap 登录模块,开发者接入前应先完成 TapTap 登录的接入
权限说明
Android 权限说明
该模块在 Android 平台需要如下权限:
| 权限 | 使用目的 | 权限申请时机 |
|---|---|---|
| 网络权限 | 用于访问网络数据 | 用户首次使用该功能时会申请权限 |
| 网络状态权限 | 用于检查网络连接状态(如 Wi-Fi 或移动数据是否可用) | 用户首次使用该功能时会申请权限 |
该模块将在 Android 应用中添加如下权限:
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
SDK 获取
参考 UE5 集成指南完成 TapCore 基础接入。再从下载页下载相同版本的 TapLogin、TapCloudSave,放入项目的 Plugins 目录并启用。
添加模块依赖
在游戏模块的 <GameModule>.Build.cs 中添加:
PublicDependencyModuleNames.AddRange(new string[]
{
"TapCore",
"TapLogin",
"TapCloudSave",
});
修改 Build.cs 后重新生成项目文件并编译。
注册/注销统一状态码监听回调
统一状态回调中,不同 ResultCode 代表不同的状态。
UE5 的回调对象需要实现 ITapCloudSaveCallback。
创建回调对象后,按以下方式注册:
#include "TapCloudSave.h"
#include "TapCloudSaveCallback.h"
void UMyCloudSaveCallback::OnResult_Implementation(int32 ResultCode)
{
// 处理云存档的状态码
// 300001:需要登录
// 300002:初始化失败,需要重新初始化
}
TScriptInterface<ITapCloudSaveCallback> Callback;
Callback.SetObject(CloudSaveCallbackObject);
Callback.SetInterface(Cast<ITapCloudSaveCallback>(CloudSaveCallbackObject));
UTapCloudSave::RegisterCloudSaveCallback(Callback);
// 不再接收状态时,使用同一个回调对象注销
UTapCloudSave::UnregisterCloudSaveCallback(Callback);
参数说明:
| 方法 | 参数 | 类型 | 说明 |
|---|---|---|---|
RegisterCloudSaveCallback | Callback | ITapCloudSaveCallback | 接收需要登录、初始化失败等模块状态。 |
UnregisterCloudSaveCallback | Callback | ITapCloudSaveCallback | 注销状态回调,需传入注册时的同一个对象。 |
请使用 UPROPERTY() 或其他 UObject 生命周期管理方式持有回调对象,避免对象在接收状态期间被回收。注销时需传入注册时的同一个对象。
状态码取值见结果码说明。状态回调不返回单次创建、下载等请求的结果;各请求结果由接口对应的成功或失败委托返回。
创建存档
创建游戏存档并上传云端。传入的存档文件必须已经写入本地磁盘。
存档名称仅支持【英文/数字/下划线/中划线】,不支持中文
存档摘要 (Summary) 以及额外信息 (Extra) 无此限制,但 Summary 不能为空字符串
一分钟内最多可调用 60 次(与更新存档共享冷却时间)
#include "TapCloudSave.h"
#include "Misc/Paths.h"
// 存档元信息
FTapArchiveMetadata Metadata;
Metadata.Name = TEXT("archive_name"); // 存档名称
Metadata.Summary = TEXT("archive_desc"); // 存档描述
Metadata.Extra = TEXT("extra_info"); // 额外信息
Metadata.Playtime = 0; // 游戏时长(秒)
// 存档文件路径(单个存档文件大小不超过 10 MB)
const FString ArchiveFilePath = FPaths::Combine(
FPaths::ProjectSavedDir(), TEXT("archive.sav"));
// 存档封面路径(可选,封面大小不超过 512 KB)
const FString ArchiveCoverPath = FPaths::Combine(
FPaths::ProjectSavedDir(), TEXT("archive.png"));
UTapCloudSave::CreateArchive(
Metadata,
ArchiveFilePath,
ArchiveCoverPath,
FTapOnArchiveResult::CreateLambda([](const FTapArchiveData& Archive)
{
// 处理存档创建成功
UE_LOG(LogTemp, Log, TEXT("Created: %s"), *Archive.Uuid);
}),
FTapOnArchiveError::CreateLambda([](int32 ErrorCode, const FString& ErrorMessage)
{
// 处理请求错误
UE_LOG(LogTemp, Error, TEXT("Cloud save failed [%d]: %s"), ErrorCode, *ErrorMessage);
}));
参数说明:
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
Metadata | FTapArchiveMetadata | 是 | 存档元信息,字段说明见下表。 |
ArchiveFilePath | String | 是 | 本地存档文件路径。SDK 会读取该路径对应的文件并上传,文件大小不能超过 10 MB。 |
CoverFilePath | String | 否 | 本地封面文件路径。传入空字符串表示不上传封面,封面大小不能超过 512 KB。 |
OnSuccess | FTapOnArchiveResult | 是 | 接收创建成功后的存档数据。 |
OnError | FTapOnArchiveError | 是 | 接收请求错误码和错误信息。 |
FTapArchiveMetadata 字段:
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
Name | String | 是 | 存档名称,不能为空,最多 60 字节;仅支持英文字母、数字、下划线和中划线。 |
Summary | String | 是 | 存档描述,不能为空,最多 500 字节。 |
Extra | String | 否 | 开发者自定义信息,最多 1000 字节,允许为空。可用于记录存档版本等业务信息。 |
Playtime | Integer | 是 | 当前存档对应的游戏时长,单位为秒,必须是非负数。 |
创建成功后返回 FTapArchiveData:
| 字段 | 类型 | 说明 |
|---|---|---|
Uuid | String | 云存档的唯一标识,用于更新或删除存档。 |
FileId | String | 存档文件标识,与 Uuid 一起用于下载存档数据或封面。 |
Name | String | 存档名称。创建结果不保证返回该字段。 |
Summary | String | 存档描述。创建结果不保证返回该字段。 |
Extra | String | 开发者写入的自定义信息。创建结果不保证返回该字段。 |
Playtime | Integer | 游戏时长,单位为秒。创建结果不保证返回该字段。 |
ArchiveFileSize | Integer | 存档文件大小,单位为字节。创建结果不保证返回该字段。 |
ArchiveCoverSize | Integer | 存档封面大小,单位为字节。创建结果不保证返回该字段。 |
CreatedTime | Integer | 存档创建时间,秒级时间戳。创建结果不保证返回该字段。 |
ModifiedTime | Integer | 存档最后修改时间,秒级时间戳。创建结果不保证返回该字段。 |
如需读取完整的存档元信息,请调用获取存档列表接口。
获取存档列表
获取当前用户的存档列表。
#include "TapCloudSave.h"
UTapCloudSave::GetArchiveList(
FTapOnArchiveListResult::CreateLambda([](const TArray<FTapArchiveData>& ArchiveList)
{
// 处理存档列表
UE_LOG(LogTemp, Log, TEXT("Archive count: %d"), ArchiveList.Num());
}),
FTapOnArchiveError::CreateLambda([](int32 ErrorCode, const FString& ErrorMessage)
{
// 处理请求错误
UE_LOG(LogTemp, Error, TEXT("Cloud save failed [%d]: %s"), ErrorCode, *ErrorMessage);
}));
参数说明:
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
OnSuccess | FTapOnArchiveListResult | 是 | 接收存档列表;没有存档时列表为空。 |
OnError | FTapOnArchiveError | 是 | 接收请求错误码和错误信息。 |
列表中的每一项均为 FTapArchiveData,字段说明见创建存档中的返回字段表。
下载存档
下载指定的存档文件。
#include "TapCloudSave.h"
// 存档 UUID
const FString ArchiveUuid = TEXT("archive_uuid");
// 存档文件 ID
const FString ArchiveFileId = TEXT("archive_file_id");
UTapCloudSave::GetArchiveData(
ArchiveUuid,
ArchiveFileId,
FTapOnArchiveBinaryResult::CreateLambda([](const TArray<uint8>& ArchiveData)
{
// 处理下载的存档数据
}),
FTapOnArchiveError::CreateLambda([](int32 ErrorCode, const FString& ErrorMessage)
{
// 处理请求错误
}));
参数说明:
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
Uuid | String | 是 | 云存档的唯一标识,即 FTapArchiveData.Uuid。 |
FileId | String | 是 | 存档文件标识,即 FTapArchiveData.FileId。 |
OnSuccess | FTapOnArchiveBinaryResult | 是 | 接收存档文件的原始二进制数据。 |
OnError | FTapOnArchiveError | 是 | 接收请求错误码和错误信息。 |
接口返回存档文件的原始二进制数据,游戏需要自行解析数据或写入本地文件。
更新存档
更新指定的存档文件。
存档名称仅支持【英文/数字/下划线/中划线】,不支持中文
存档摘要 (Summary) 以及额外信息 (Extra) 无此限制,但 Summary 不能为空字符串
一分钟内最多可调用 60 次(与创建存档共享冷却时间)
#include "TapCloudSave.h"
#include "Misc/Paths.h"
const FString ArchiveUuid = TEXT("archive_uuid");
// 存档元信息
FTapArchiveMetadata Metadata;
Metadata.Name = TEXT("new_archive_name"); // 更新后的存档名称
Metadata.Summary = TEXT("new_archive_desc"); // 更新后的存档描述
Metadata.Extra = TEXT("extra"); // 额外信息
Metadata.Playtime = 0; // 游戏时长(秒)
// 新的存档文件路径(单个存档文件大小不超过 10 MB)
const FString ArchiveFilePath = FPaths::Combine(
FPaths::ProjectSavedDir(), TEXT("new_archive.sav"));
// 新的存档封面路径(可选,封面大小不超过 512 KB)
const FString ArchiveCoverPath = FPaths::Combine(
FPaths::ProjectSavedDir(), TEXT("new_archive.png"));
UTapCloudSave::UpdateArchive(
ArchiveUuid,
Metadata,
ArchiveFilePath,
ArchiveCoverPath,
FTapOnArchiveResult::CreateLambda([](const FTapArchiveData& Archive)
{
// 处理存档更新成功
UE_LOG(LogTemp, Log, TEXT("Updated: %s"), *Archive.Uuid);
}),
FTapOnArchiveError::CreateLambda([](int32 ErrorCode, const FString& ErrorMessage)
{
// 处理请求错误
UE_LOG(LogTemp, Error, TEXT("Cloud save failed [%d]: %s"), ErrorCode, *ErrorMessage);
}));
参数说明:
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
Uuid | String | 是 | 要更新的云存档唯一标识,即 FTapArchiveData.Uuid。 |
Metadata | FTapArchiveMetadata | 是 | 更新后的存档元信息,字段说明见创建存档中的 FTapArchiveMetadata 字段表。 |
ArchiveFilePath | String | 是 | 更新后的本地存档文件路径。SDK 会读取该路径对应的文件并上传,文件大小不能超过 10 MB。 |
CoverFilePath | String | 否 | 更新后的本地封面文件路径。传入空字符串表示不上传封面,封面大小不能超过 512 KB。 |
OnSuccess | FTapOnArchiveResult | 是 | 接收更新后的存档数据。 |
OnError | FTapOnArchiveError | 是 | 接收请求错误码和错误信息。 |
删除存档
删除指定的存档文件。
#include "TapCloudSave.h"
const FString ArchiveUuid = TEXT("archive_uuid");
UTapCloudSave::DeleteArchive(
ArchiveUuid,
FTapOnArchiveResult::CreateLambda([](const FTapArchiveData& Archive)
{
// 处理存档删除成功
UE_LOG(LogTemp, Log, TEXT("Deleted: %s"), *Archive.Uuid);
}),
FTapOnArchiveError::CreateLambda([](int32 ErrorCode, const FString& ErrorMessage)
{
// 处理请求错误
UE_LOG(LogTemp, Error, TEXT("Cloud save failed [%d]: %s"), ErrorCode, *ErrorMessage);
}));
参数说明:
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
Uuid | String | 是 | 要删除的云存档唯一标识,即 FTapArchiveData.Uuid,不能使用本地文件名代替。 |
OnSuccess | FTapOnArchiveResult | 是 | 接收已删除存档的数据。 |
OnError | FTapOnArchiveError | 是 | 接收请求错误码和错误信息。 |
获取存档封面
获取指定存档的封面图片。
#include "TapCloudSave.h"
const FString ArchiveUuid = TEXT("archive_uuid");
const FString ArchiveFileId = TEXT("archive_file_id");
UTapCloudSave::GetArchiveCover(
ArchiveUuid,
ArchiveFileId,
FTapOnArchiveBinaryResult::CreateLambda([](const TArray<uint8>& CoverData)
{
// 处理封面数据
UE_LOG(LogTemp, Log, TEXT("Downloaded cover: %d bytes"), CoverData.Num());
}),
FTapOnArchiveError::CreateLambda([](int32 ErrorCode, const FString& ErrorMessage)
{
// 处理请求错误
UE_LOG(LogTemp, Error, TEXT("Cloud save failed [%d]: %s"), ErrorCode, *ErrorMessage);
}));
参数说明:
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
Uuid | String | 是 | 云存档的唯一标识,即 FTapArchiveData.Uuid。 |
FileId | String | 是 | 存档文件标识,即 FTapArchiveData.FileId。 |
OnSuccess | FTapOnArchiveBinaryResult | 是 | 接收封面文件的原始二进制数据。 |
OnError | FTapOnArchiveError | 是 | 接收请求错误码和错误信息。 |
接口返回封面文件的原始二进制数据。
结果码说明
| 结果码 | 说明 |
|---|---|
| 300001 | 需要登录 |
| 300002 | 初始化失败,需要重新初始化 |
请求错误码
用于 FTapOnArchiveError 回调中的 ErrorCode。
| 错误码 | 说明 |
|---|---|
| 100001 | UE5 传入的参数无效,或本地文件不存在 |
| 100002 | 当前平台的云存档实现不可用 |
| 400000 | 非法的存档文件/封面大小 |
| 400001 | 存档上传频率超限 |
| 400002 | 指定的存档不存在 |
| 400003 | 单个应用下存档数量超限 |
| 400004 | 单个应用下使用存储空间超限 |
| 400005 | 总使用存储空间超限 |
| 400006 | 创建/更新云存档超时,通常是由于网络卡顿,耗时过长导致 |
| 400007 | 上传云存档并发调用次数超过 10 个,或者并发更新同一个云存档 |
| 400008 | 找不到可用的 OSS 供应商 |
| 400009 | 存档名称不合法 |
| 400010 | 禁止同一台机器同一个ClientID多个进程使用同一账号 |
国际化
TapTapCloudSave 目前只支持简体中文。