文档中心 > 店铺动态卡片-开发指引

店铺动态卡片-开发指引

云存档

更新时间：2024/11/20 访问次数：2725

一、说明

本文档对手淘环境下的常见游戏数据存储方式的注意事项进行说明，避免在线上出现丢档的情况。本文档介绍三种存档方式：接入平台侧的云存档、游戏服务器保存、客户端本地缓存。

云存档：开放平台提供给小游戏的存档功能，可以解决无服务器游戏换手机后无存档的问题，加快游戏的接入速度。

游戏服务器保存：有服务器的游戏，优先建议自己实现存档能力，将存档数据保存在自己的服务器上。如果游戏选择游戏服务器保存存档，请确保支持玩家换手机后仍然有存档，且不允许将用户的存档数据存放在本地。

客户端本地缓存：客户端存储数据的本地存储能力。不允许单独接入该能力，必须配合云存档或游戏服务器保存，否则玩家更换手机后将丢失存档。

二、云存档

1. 类型定义

TBaseParams<T = void>

基础回调参数类型，用于定义接口请求的回调函数。

export type TBaseParams<T = void> = {
  complete (): void; // 请求完成后的回调，无论成功或失败
success(data: T): void; // 请求成功时的回调
fail (err: any): void; // 请求失败时的回调
};

KVData

表示键值对数据的类型。

export type KVData = {
  key: string; // 键名
  value:  string | number ; // 对应的值
};

TKVDataList

KVData 类型的数组。

1export type TKVDataList = KVData[];

TKeyList

键名的字符串数组。

export type TKeyList = string[];

2. 接口方法

getUserCloudStorage

获取用户云存储中的键值对列表。

getUserCloudStorage(params: TGetStorageParams): Promise<void>;

参数: TGetStorageParams

请求参数包括一个键列表和基础回调参数。

export type TGetStorageParams = { keyList: TKeyList } & TBaseParams<{ KVDataList: TKVDataList }>;


getUserCloudStorageKeys

获取用户云存储中所有的键名。

getUserCloudStorageKeys(params: TGetStorageKeys): Promise<void>;

参数: TGetStorageKeys

请求参数仅包括基础回调参数。

export type TGetStorageKeys = TBaseParams<{ keys: string[] }>;


setUserCloudStorage

设置用户云存储中的键值对列表。

setUserCloudStorage(params: TSetStorageParams): Promise<void>;

参数: TSetStorageParams

请求参数包括键值对列表和基础回调参数。

export type TSetStorageParams = { KVDataList: TKVDataList } & TBaseParams;


removeUserCloudStorage

从用户云存储中移除指定的键。

removeUserCloudStorage(params: TRemoveStorageParams): Promise<void>;

参数: TRemoveStorageParams

请求参数包括一个键列表和基础回调参数。

export type TRemoveStorageParams = { keyList: TKeyList } & TBaseParams;

3. 使用方式

前置条件

（1）联系淘宝小二呱太申请云存档权限包；

（2）可通过以下三个步骤确认是否开启了云存档功能，再继续后续（3）的操作：

步骤1：点击控制台-点击应用管理的云服务后，若进入下图页面，说明该游戏尚未创建云应用。点击云应用套件，即可前往创建云应用。创建云应用步骤详情请参考开发小游戏（服务端开发看）。

步骤2: 针对已创建云应用的小游戏，选择【云服务】——【云应用套件】，若如下图展示【小程序云存储】则表明功能正常开通。

步骤3: 现在可以在【云托管】——【小程序云存储】中找到自己对应的应用了，可继续进行后续操作。

（3）通过云存储后台可以查看存储数据。路径：小程序ID/用户openId/definePath/

示例

@tbmp/mp-cloud-sdk": "^1.5.7

import cloud from '@tbmp/mp-cloud-sdk'

cloud.init({
  env:'online',
  options:{}
})

const userCloudStore = cloud.userCloudStore;

// 备份路径，可不填，如果不填，采用默认路径"default"
userCloudStore.definePath = 'xxxx';

userCloudStore.getUserCloudStorage({
  keyList:['a','b'],
  success(data) {console.log('[cc getUserCloudStorage',data) },
})

userCloudStore.getUserCloudStorageKeys({
  success(data) {console.log('[cc getUserCloudStorageKeys',data) },
})

userCloudStore.removeUserCloudStorage({
  keyList:['b'],
  success(data) {console.log('[cc removeUserCloudStorage',data) },
})

userCloudStore.setUserCloudStorage({
  success(data) {console.log('[cccc',data) },
  fail() { },
  KVDataList: [{
    key: 'a',
    value: 123
  },
               {
                 key: 'b',
                 value: 222
               },
               {
                 key: 'baa',
                 value: '222mu'
               },
              ]
})

注意事项
① 如果你要在cocos中使用空应用的话，需要参考《Cocos/Laya引擎适配》文档的FAQ关于空应用的内容。
② 单个角色的数据不建议超过3M。
③ userCloudStore.definePath 设置不同的存储路径，可以用于游戏的备份，也是一个全局变量。如果在运行时切换用于备份，在后续的正常逻辑的set和get操作要注意切换回去默认的存储路径；
④ setUserCloudStorage如果保存多个过程中有一个出错了，则全部保存失败；
⑤ setUserCloudStorage操作不会对已有的数据进行全量覆盖，保存的时候只会对提供的key的数据进行覆盖；
⑥ 开发者需要在游戏的合适时机保存。禁止在游戏退出回调的时候保存，存储接口可能已经释放掉了，导致保存失败；
⑦ 不建议高频率调用，如果调用频率过高会触发服务器的限流机制，导致接口调用失败。建议在合适的时间节点进行游戏数据的保存（多量少次）；已接入游戏的存档频率平均 30 秒一次；

⑧ 该能力适用于小游戏-新的开发项目。

⑨ 由于IDE模拟器暂不支持对云存档数据上传到云存储，调试的时候请使用真机调试。

三、游戏服务器保存
如果小游戏选择不接入云存档，自己实现存档能力，将存档数据保存在游戏自己的服务器，那么需要注意：游戏的保存需要走阿里巴巴的云网关，而云网关有对接口的大小做限制，如果出现游戏存档接口调用出错的情况，开发者需要有兜底方案和监控；

http协议接口建议使用POST方法，因为GET方法传输的内容受限于url的长度，其传输的内容会更多，从而减少接口调用出错的情况；

四、客户端本地缓存
如果游戏在接入云存档后，认为仍然有必要缓存到玩家的客户端本地缓存，可以接入平台的localstorage保存能力。

目前接口做用户隔离，角色A保存的数据，在角色B上是能读取到的，所以在保存的时候key值要添加角色的唯一标识。

localStorage.setItem(`data${roleId}`, `${data}`);

localstorage不建议高频率调用，会一定程度上造成游戏的卡顿，建议在合适的时间节点进行游戏数据的保存（多量少次）；

再次强调：开发者不能仅将存档数据保存于客户端本地缓存，必须接入前文的云存档或游戏方自己实现的存档能力，确保玩家更换手机后仍然有存档。

FAQ

关于此文档暂时还没有FAQ
有用(0) 我要提问
返回
顶部
阿里巴巴集团 | 淘宝网 | 天猫 | 聚划算 | 全球速卖通 | 阿里巴巴国际交易市场 | 1688 | 阿里妈妈 | 阿里旅行·去啊 | 阿里云计算 | YunOS | 阿里通信 | 万网 | 高德 | 优视 | 友盟 | 酷盘 | 虾米 | 天天动听 | 来往 | 钉钉 | 11Main | 支付宝
关于淘宝 合作伙伴 营销中心 联系客服 开放平台 诚征英才 联系我们 网站地图 法律声明 © 2016 Taobao.com 版权所有
网络文化经营许可证：文网文[2010]040号 | 增值电信业务经营许可证：浙B2-20080224-1 | 信息网络传播视听节目许可证：1109364号