SDK对接文档

主题

存档接口 ​

上传本地存档 ​

C#
//上传数据到云 唯一标识是deviceId SDK已经处理，此处只用传业务key即可
//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}]");
    }
}

获取云端存档 ​

C#
//code说明：（0：失败 1：成功  -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}]");
    }
}

无登录 ​

无登录流程图 ​


无登录设计原理 ​

  1. 安装之后只用下拉一次成功 这个是用于手机卸载重装时候使用恢复卸载前的数据。常见的做法为是：一个 app 安装只需拉取一次成功的即可，在拉取成功前不执行上传操作。

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

  3. 下拉时机详细优化

  • 游戏启动时拉取 key，分为 3 种情况：
    • 网络错误等原因无法拉取成功
    • 正确连上服务器拉取数据为空
    • 正确连上服务器拉取数据有值
      • 情况 1：最好给玩家提示网络问题，否则有可能发生，直接进游戏，后续触发上报，把数据冲掉了。
      • 情况 2：无需任何处理，直接进游戏。
      • 情况 3：和 app 数据本地的各种信息比较，看服务器数据和本地数据的差异化，提醒玩家是否服务器数据覆盖本地数据。
  1. 上报流程的优化 切勿频繁上报。最好在关键信息触发时上报，例如关卡结束金币结算，人物等级经验变化，关卡数据变化等等，一次性用同一个 key 标记进行 value 上报。频率控制在30s左右一次即可

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

无登录流程设计 ​

  1. 游戏首次启动
  • 首次启动：
    • 步骤：使用 DeviceID 或者设备标识符调用 获取云端存档接口 以获取存档数据。
    • 判断结果：
      • 网络错误：
        • 强联网游戏处理：提示玩家检查网络连接，建议稍后再试。不进入游戏。
        • 非强联网游戏处理：可以先进入游戏，继续拉取存档，拉取到存档后和本地数据比对，并弹出提示让用户选择存档，需要标明未选择存档会永久丢失
      • 数据为空：
        • 处理：直接进入游戏，无需任何提示。
      • 数据有值：
        • 直接写入本地
  1. 游戏内事件与状态变更
  • 关卡结束：
    • 步骤：收集当前关卡得分、奖励、完成时间等数据。
  • 角色升级：
    • 步骤：当玩家角色升级时，收集新等级、经验值等信息。
  • 物品获取/使用：
    • 步骤：玩家获取新道具或使用道具时，记录相关数据。
  1. 定期存档
  • 定期自动上报：
    • 策略：在游戏进行中定期（例如每 5 分钟）自动上报当前状态，以防止数据丢失。
    • 实现：使用定时器触发 上传本地存档接口，确保关键数据如金币、进度等被记录。
  1. 卸载与重装
  • 重装后首次启动：
    • 步骤：再次调用 获取云端存档接口 获取存档数据。
    • 判断：与首次启动时相同，处理网络问题、数据为空或有值的情况。
  1. 网络状态监测
  • 网络恢复后尝试上传：
    • 步骤：使用网络状态监听，检测网络恢复后尝试上传之前未能上传的数据。
    • 实现：若上传失败，记录失败状态，网络恢复时重新尝试。
  1. 数据冲突与合并处理
  • 冲突处理：
    • 情况：若服务器和本地数据存在冲突。
    • 处理策略：
      • 优先使用最新的数据，或提示玩家选择使用本地或云端数据。
      • 提供比较界面，显示两者的差异，供玩家决定。
  1. 游戏退出时的自动存档 和 玩家手动存档
  • 退出时上传和手动上传：
    • 步骤：在玩家选择退出游戏时，和玩家点击存档时上传当前状态数据。
    • 实现：若玩家选择上传，则调用 上传本地存档接口。如果上传失败，应给予玩家提示
  1. 数据完整性与错误处理
  • 数据完整性检查：
    • 步骤：在上传和拉取数据时，进行完整性校验（如数据格式、类型）。
    • 处理：若发现错误，记录错误信息，提示玩家尝试重试或联系客服。
  1. 版本兼容性处理
  • 版本检查：
    • 步骤：当游戏版本更新时，检查存档数据格式是否兼容。
    • 处理：若不兼容，提供数据迁移工具或说明，帮助玩家转换数据。
  1. 注意项
  • 本地存档位置：本地存档尽量持久化存储，以文件形式保存最安全。
  • 上传时机：在拉取存档成功前一定不要上传，否则会导致本地存档覆盖云存档
  • 拉取间隔：如果初次拉取失败，重新拉取的间隔时间推荐为 5s，10s，20s，40s，60s，60s，60s，初期间隔时间可以短一些，尽可能保证用户能第一时间拉取到存档，如果前几次失败，后面则保持 1 分钟一次的频率即可，如果拉取到了存档，在上传前一定要让用户主动选择使用本地存档还是云存档

有登录 ​

有登录流程图 ​


有登录设计原理 ​

  1. 登录之后下拉一次成功 每次登录都最好拉取一次存档，在拉取成功前不执行上传操作。

有登录流程优化设计 ​

  1. 登录流程
  • 玩家启动游戏并选择登录。
  • 调用登录接口，验证账号信息。
  • 登录成功后，立即调用获取云端存档接口，拉取存档数据。
    • 处理拉取结果：
      • 网络错误：
        • 强联网游戏：提示玩家检查网络连接，建议稍后再试，不进入游戏。
        • 非强联网游戏：先进入游戏，继续尝试拉取存档，拉取到存档后与本地数据比对，并弹出提示让用户选择存档，标明未选择存档会永久丢失。
      • 数据为空：
        • 直接进入游戏，无需任何提示。
      • 数据有值：
        • 将云端数据写入本地，并提示玩家是否覆盖本地数据。
  1. 注销流程
  • 玩家选择注销账号。
  • 调用上传本地存档接口，上传当前游戏数据。
    • 上传成功: 清除本地登录状态，并返回到登录界面。
    • 上传失败: 提示玩家存档未成功保存，建议重试或检查网络。
  1. 顶号处理
  • 检测到当前账号在其他设备登录（顶号）。
  • 立即调用上传本地存档接口，上传当前游戏数据。
  • 上传成功: 提示玩家账号在其他设备登录，并强制退出到登录界面。
  • 上传失败: 提示玩家存档未成功保存，建议重试或检查网络。
点我快速对接