存档接口

为了方便快速集成，我们的存档系统分成了两套，一套是无需接入登录依赖于用户设备id(DeviceID)的无登录存档接口，另一套是基于登录后获取到渠道的openId的有登录存档接口。

无登录

无登录上传存档接口

唯一标识是deviceId，SDK已经处理，直接上传存档键值对即可

//code-0失败 1-成功
ZMYSDKManager.I.Sdk.UploadCloudArchive(key,value);

ZMYSDKManager.I.UploadCloudArchiveCallBack += UploadCloudArchiveCallBack;

// 上传游戏存档回调
void UploadCloudArchiveCallBack(UpLoadCloudArchiveResult result)
{
    Debug.Log("游戏收到数据上传回调UploadCloudArchiveCallBack："+result.code);
    if (result.code==0)
    {
        m_resultTxt.text = "游戏数据上传失败" + result.msg;
        Debug.LogError("游戏数据上传失败"+result.msg);
    }else if (result.code==1)
    {
        m_resultTxt.text = $"游戏数据上传成功[{result.key}]";
        Debug.Log($"游戏数据上传成功[{result.key}]");
    }
}

//上传数据到云 唯一标识是deviceId SDK已经处理，此处只用传业务key即可
//code-0失败 1-成功
public uploadCloudArchive(key : string , value : string, callback : (code : number, key : string, msg : string) => void) {}

无登录下载存档接口

//code说明：（0：失败 1：成功  -6:存档不存在；-10：拉取数据为空；-9999：服务器异常报错）
// -6 指的是该游戏第一次接入存档，在没有上传存档的情况下拉取存档，会因为数据库都还没有建立，导致拉取失败
// -10 指的是非第一次存档，在该用户没有上传存档的情况下拉取存档，会因为没有数据拉取失败
// -9999 就是指咱们服务器异常，请求接口无响应导致的拉取失败
// 其他errorCode可统一失败处理
ZMYSDKManager.I.Sdk.PullCloudArchive(key);

ZMYSDKManager.I.PullCloudArchiveCallBack += PullCloudArchiveCallBack;

// 下载游戏存档回调
void PullCloudArchiveCallBack(PullCloudArchiveResult result)
{
    Debug.Log("游戏收到数据获取回调PullCloudArchiveCallBack：" + result.code);
    if (result.code == 0)
    {
        m_resultTxt.text = "游戏数据获取失败" + result.msg;
        Debug.LogError("游戏数据获取失败" + result.msg);
    }
    else if (result.code == 1)
    {
        m_resultTxt.text = $"游戏数据获取成功：{result.value}";
        Debug.Log($"游戏数据获取成功:Key=[{result.key}] value=[{result.value}]");
    }
}

//code说明：（0：失败 1：成功  -6:存档不存在；-10：拉取数据为空；-9999：服务器异常报错）
// -6 指的是该游戏第一次接入存档，在没有上传存档的情况下拉取存档，会因为数据库都还没有建立，导致拉取失败
// -10 指的是非第一次存档，在该用户没有上传存档的情况下拉取存档，会因为没有数据拉取失败
// -9999 就是指咱们服务器异常，请求接口无响应导致的拉取失败
// 其他errorCode可统一失败处理
public pullCloudArchive(key : string, callback : (code : number, value : string, msg : string) => void) {}

无登录流程图

注意事项

重点一：在一次应用的生命周期中()，只能够成功拉取一次存档，拉取存档成功后，只做上传操作，来确保存档的稳定性，避免回档情况。

重点二：在应用启动之后，立刻开始尝试拉取存档，拉取成功后，如果本地有数据，则需要和本地数据对比，可以让用户选择，也可以考虑根据关卡进度来自动取舍。

重点三：建议使用一个 key 来存储游戏数据 通常情况下不建议一个 app 存储过多的 key，尽量把数据集中封装下。反例：金币一个 key-1，关卡一个 key-2，等级一个 key-3，这些不合适。可以缩减成一个 key，里面 value 是个 map 继续开发者自己对应。

重点四：上报流程的优化 切勿频繁上报。最好在关键信息触发时上报，例如关卡结束金币结算，人物等级经验变化，关卡数据变化等等，一次性用同一个 key 标记进行 value 上报。频率控制在30s左右一次即可

根据设计原理，我们总结了以下这些情况的推荐存档方式

无登录流程设计

1. 游戏首次启动

• 首次启动：
  • 步骤：使用 DeviceID 或者设备标识符调用 获取云端存档接口 以获取存档数据。
  • 判断结果：
    • 网络错误：
      • 强联网游戏处理：提示玩家检查网络连接，建议稍后再试。不进入游戏。
      • 非强联网游戏处理：可以先进入游戏，继续拉取存档，拉取到存档后和本地数据比对，并弹出提示让用户选择存档，需要标明未选择存档会永久丢失
    • 数据为空：
      • 处理：直接进入游戏，无需任何提示。
    • 数据有值：
      • 直接写入本地

2. 游戏内事件与状态变更

• 关卡结束：
  • 步骤：收集当前关卡得分、奖励、完成时间等数据。
• 角色升级：
  • 步骤：当玩家角色升级时，收集新等级、经验值等信息。
• 物品获取/使用：
  • 步骤：玩家获取新道具或使用道具时，记录相关数据。

3. 定期存档

• 定期自动上报：
  • 策略：在游戏进行中定期（例如每 5 分钟）自动上报当前状态，以防止数据丢失。
  • 实现：使用定时器触发 上传本地存档接口，确保关键数据如金币、进度等被记录。

4. 卸载与重装

• 重装后首次启动：
  • 步骤：再次调用 获取云端存档接口 获取存档数据。
  • 判断：与首次启动时相同，处理网络问题、数据为空或有值的情况。

5. 网络状态监测

• 网络恢复后尝试上传：
  • 步骤：使用网络状态监听，检测网络恢复后尝试上传之前未能上传的数据。
  • 实现：若上传失败，记录失败状态，网络恢复时重新尝试。

6. 数据冲突与合并处理

• 冲突处理：
  • 情况：若服务器和本地数据存在冲突。
  • 处理策略：
    • 优先使用最新的数据，或提示玩家选择使用本地或云端数据。
    • 提供比较界面，显示两者的差异，供玩家决定。

7. 游戏退出时的自动存档 和 玩家手动存档

• 退出时上传和手动上传：
  • 步骤：在玩家选择退出游戏时，和玩家点击存档时上传当前状态数据。
  • 实现：若玩家选择上传，则调用 上传本地存档接口。如果上传失败，应给予玩家提示

8. 数据完整性与错误处理

• 数据完整性检查：
  • 步骤：在上传和拉取数据时，进行完整性校验（如数据格式、类型）。
  • 处理：若发现错误，记录错误信息，提示玩家尝试重试或联系客服。

9. 版本兼容性处理

• 版本检查：
  • 步骤：当游戏版本更新时，检查存档数据格式是否兼容。
  • 处理：若不兼容，提供数据迁移工具或说明，帮助玩家转换数据。

10. 注意项

• 本地存档位置：本地存档尽量持久化存储，以文件形式保存最安全。
• 上传时机：在拉取存档成功前一定不要上传，否则会导致本地存档覆盖云存档
• 拉取间隔：如果初次拉取失败，重新拉取的间隔时间推荐为 5s，10s，20s，40s，60s，60s，60s，初期间隔时间可以短一些，尽可能保证用户能第一时间拉取到存档，如果前几次失败，后面则保持 1 分钟一次的频率即可，如果拉取到了存档，在上传前一定要让用户主动选择使用本地存档还是云存档

有登录

有登录上传存档接口

// 上传存档
 ZMYSDKManager.I.Sdk.ServerLoginUploadDataStatic(string keyInfo,string valueInfo);

// 监听上传存档成功
 ZMYSDKManager.I.Login_UpLoadData += upLoadDataCallBack;
void upLoadDataCallBack(UploadDataResult dataResult)
{
    if (dataResult.code==1)
    {
        Debug.Log($"上报Key[{dataResult.key}] 成功");
    }
    else
    {
        Debug.Log($"上报Key[{dataResult.key}] 失败");
    }
}

    //---上传数据---
    //code表示keyInfo是否上传成功，code-0获取失败  1-获取成功 2-再次调用登录方法
    //注意，如果此过程服务器结果为被踢掉线了，那么PUB_loginServerState也会改变状态为0
    public loginUploadUserDataStatic(key: string, value: string, callback: (code: number, key: string) => void, invalidCallback? : () => void) {}

有登录拉取存档接口

// 下载存档
ZMYSDKManager.I.Sdk.ServerLoginGetDataStatic(string keyInfo);

// 监听下载存档成功
ZMYSDKManager.I.Login_DownData += downDataCallBack;
void downDataCallBack(DownDataResult dataResult)
{
    if (dataResult.code == 1)
    {
        Debug.Log($"下拉Key[{dataResult.key}] 成功 Value=[{dataResult.value}]");
    }
    else
    {
        Debug.Log($"下拉Key[{dataResult.key}] 失败");
    }
}

    /**
    * 下拉数据
    * @param callback
    * ---下拉数据---
      说明：返回值为key-value字符串类型，code-0获取失败  1-获取成功 2-再次调用登录方法
      注意，如果此过程服务器结果为被踢掉线了，那么PUB_loginServerState也会改变状态为0
    * @returns
    */
    public loginGetUserDataStatic(keyInfo: string, callback: (code : number, key: string, value: string) => void, invalidCallback? : () => void) {}

有登录流程图

注意事项

重点一：在一次应用的生命周期中()，只能够成功拉取一次存档，拉取存档成功后，只做上传操作，来确保存档的稳定性，避免回档情况。

重点二：在应用启动之后，立刻开始尝试拉取存档，拉取成功后，如果本地有数据，则需要和本地数据对比，可以让用户选择，也可以考虑根据关卡进度来自动取舍。

重点三：建议使用一个 key 来存储游戏数据 通常情况下不建议一个 app 存储过多的 key，尽量把数据集中封装下。反例：金币一个 key-1，关卡一个 key-2，等级一个 key-3，这些不合适。可以缩减成一个 key，里面 value 是个 map 继续开发者自己对应。

重点四：上报流程的优化 切勿频繁上报。最好在关键信息触发时上报，例如关卡结束金币结算，人物等级经验变化，关卡数据变化等等，一次性用同一个 key 标记进行 value 上报。频率控制在30s左右一次即可

有登录设计原理

我们在有登录时，要特别注意，存档会分为两种类型，登录存档和非登录存档。这两种存档是可以共存的。同时每种存档又分为云存档和本地存档，当这两种存档同时存在时，一定要注意数据校验。

在没有登录情况下，使用非登录存档，非登录存档与设备id绑定，更换设备后无法迁移。在非登录状态下，第一次登录，可以将非登录存档转化为登录存档（CP方自行处理），转化后应当将本设备的非登录存档清空，防止一个非登录存档刷出多个登录存档。

在SDK内部，登录存档和非登录存档的存储形式不同，登录存档以数据库形式存储，单个key-value的value字段不可以超过100kb，而非登录存档以文件形式存储。

登出情况：允许退出登录后重新在本设备继续产生非登录存档，并且要保证非登录存档的上传和下载正常。如果已经登录，则优先使用登录存档。

顶号情况：如果出现了顶号的情况，在退出当前账号后，应该让用户能够正常以本设备非登录存档进度进行游戏。