Cloud Save 客户端SDK接入指南

来源：好游戏攻略时间：2024-11-26 08:50

1.使用 UOS Launcher 安装 SDK

UOS Launcher 是一个在 Unity Editor 中使用的管理工具，用于安装和管理 UOS 各个服务所要使用到的 Unity Package。

1.1.安装 UOS Launcher

在 Unity Editor 菜单栏中打开「Window -> Package Manager」，点击左上角的「+」，选择「Add package from git URL」，输入UOS Launcher 的 git 地址如下，点击「Add」等待安装完成。

https://e.coding.net/unitychina/uos/UOSLauncher.git

注意：该步骤要求当前环境已安装 git。注意：UOS Launcher 兼容的最低 Unity 版本为 2021.3 (LTS)。1.2.在 UOS Launcher 中连接 UOS APP

安装成功后通过 Unity Editor 菜单栏中「UOS -> Open Launcher」打开管理面板。在 UOS 面板中填写 AppID/AppSecret/AppServiceSecret，并点击「Link App」与 UOS APP 关联。

注：此处 AppId

、 AppSecret和 AppServiceSecret ，可在 UOS 网站上获取

1.3.开启服务，安装 SDK

在服务列表中，找到 Save，点击 Enable 开启服务。你也可以在当前网站上开启服务。如服务已开启，可忽略该步骤。

点击「Install SDK」，将服务 SDK 安装到当前项目中。详细步骤请查看「UOS Launcher 教程」。

2.初始化

初始化SDK

// 使用 UOS Launcher 方式初始化SDK, 更多SDK初始化方式见 sdk package sample 目录try{ await CloudSaveSDK.InitializeAsync();}catch (CloudSaveClientException e){ Debug.LogErrorFormat($"failed to initialize sdk, clientEx: {e}"); throw;}catch (CloudSaveServerException e){ Debug.LogErrorFormat($"failed to initialize sdk, serverEx: {e}"); throw;}SDK鉴权已使用「Passport Login SDK」的情况下，请确保在调用 CloudSaveSDK 提供的方法之前用户已经登录完成。未使用「Passport Login SDK」的情况下，请确保在调用 CloudSaveSDK 提供的方法之前已调用过ExternalLogin接口。

using Unity.UOS.Auth;// 用户登录（仅需登录一次）string userId = <userId>; // 需要登录的 UserIdstring personalId = <personalId>; // 可选需要登录的 PersonalIdstring personaDisplayName = <displayName>; // 可选, 需要登录的角色的昵称。await AuthTokenManager.ExternalLogin(userId, personalId, personaDisplayName);

3.存档集成示例

通过字节数组创建一个文件存档查看指定存档元数据信息获取存档文件内容

string saveId = <saveId>;try{ byte[] bytes = await CloudSaveSDK.Instance.Files.LoadBytesAsync(saveId);}catch (CloudSaveClientException e){ Debug.LogErrorFormat("failed to load file, id {0}, clientEx: {1}", saveId, e); throw;}catch (CloudSaveServerException e){ Debug.LogErrorFormat("failed to load file, id {0}, serverEx: {1}", saveId, e); throw;}更新存档删除存档

try{ string saveId = <saveId>; await CloudSaveSDK.Instance.Files.DeleteAsync(saveId);}catch (CloudSaveClientException e){ Debug.LogErrorFormat("failed to delete file, id {0}, clientEx: {1}", saveId, e); throw;}catch (CloudSaveServerException e){ Debug.LogErrorFormat("failed to delete file, id {0}, serverEx: {1}", saveId, e); throw;}列出所有存档元数据信息查看单存档元数据信息

// 获取指定命名空间和角色下单存档的元数据信息，为空表示该角色在此命名空间下无单存档string targetNamespace = <targetNamespace>; // 存档的命名空间string personaId = <personaId>; // 角色Idtry{ SaveItem saveItem = await CloudSaveSDK.Instance.Files.GetLinearAsync(targetNamespace, personaId);}catch (CloudSaveClientException e){ Debug.LogErrorFormat("failed to get metadata of linear save, clientEx: {0}", e); throw;}catch (CloudSaveServerException e){ Debug.LogErrorFormat("failed to get metadata of linear save, serverEx: {0}", e); throw;}保存单存档

// 对指定命名空间和角色下的单存档进行存档操作。若之前无单存档，会创建一个新的单存档。成功后返回存档Idstring targetNamespace = <targetNamespace>; // 存档的命名空间string personaId = <personaId>; // 角色IdUpdateOptions options = <options>; // 存档选项try{ string saveId = await CloudSaveSDK.Instance.Files.SaveLinearAsync(targetNamespace, personaId, options);}catch (CloudSaveClientException e){ Debug.LogErrorFormat("failed to create or update linear save, clientEx: {0}", e); throw;}catch (CloudSaveServerException e){ Debug.LogErrorFormat("failed to create or update linear save, serverEx: {0}", e); throw;}

3.头像集成示例

上传头像获取头像删除头像

try{ await CloudSaveSDK.Instance.Files.DeleteProfilePicturesAsync();}catch (CloudSaveClientException e){ Debug.LogErrorFormat("failed to delete user's profile picture, clientEx: {0}", e); throw;}catch (CloudSaveServerException e){ Debug.LogErrorFormat("failed to delete user's profile picture, serverEx: {0}", e); throw;}列出选定用户的头像信息列出开发者设置的默认头像

// 如果开发者未上传默认头像，将返回空列表try{ List<PFPItem> profilePictures = await CloudSaveSDK.Instance.Files.ListDefaultProfilePicturesAsync();}catch (CloudSaveClientException e){ Debug.LogErrorFormat("failed to list default profile pictures, clientEx: {0}", e); throw;}catch (CloudSaveServerException e){ Debug.LogErrorFormat("failed to list default profile pictures, serverEx: {0}", e); throw;}选择默认头像作为头像

// 选择默认头像作为用户头像 (仅在开发者配置成功默认头像后生效，开发者可以通过“用户头像”界面或使用服务端API上传默认头像)string id = <id>; // 用户选择的默认头像idtry{ await CloudSaveSDK.Instance.Files.SaveProfilePictureByIdAsync(id, options);}catch (CloudSaveClientException e){ Debug.LogErrorFormat( "failed to save user's profile picture by default picture, id {0}, clientEx: {1}", id, e); throw;}catch (CloudSaveServerException e){ Debug.LogErrorFormat( "failed to save user's profile picture by default picture, id {0}, serverEx: {1}", id, e); throw;}

附录

文件存档核心类&接口头像相关核心类&接口异常类

//抛出该异常时代表客户端错误，如认证失败，参数无效，文件大小超出限制等情况，详细错误信息可查看 exception messagepublic class CloudSaveClientException : CloudSaveException{ public CloudSaveClientException(int errorCode, string message, System.Exception innerException) : base(errorCode, message, innerException) { }} //抛出该异常时代表服务端异常，可稍后重试或联系我们public class CloudSaveServerException : CloudSaveException{ public CloudSaveServerException(int errorCode, string message, System.Exception innerException) : base(errorCode, message, innerException) { }}更多示例

更多 SDK 使用示例参见 SDK Package Sample 目录