玩家数据
您可以：
- 使用 SDK 方法将游戏数据（完成的关卡、经验、应用内购买等）保存到 Yandex 服务器，或将其传输到您自己的服务器。云存档允许用户在不同设备上继续游戏。
- 使用 Yandex 用户个人资料中的数据（例如姓名）对游戏进行个性化。
Player 对象可用于处理用户数据。
初始化
要初始化 Player 对象，请使用 ysdk.getPlayer() 方法：
1const ysdk = await YaGames.init();
2
3try {
4 const player = await ysdk.getPlayer();
5} catch (e) {
6 // 初始化 Player 对象时出错。
7}
初始化 Player 对象时会以字符串形式传入以下数据：
- 用户ID —— 所有玩家都会包含。
- 头像和名称 —— 仅限已授权玩家。
- 平台内购数据（仅适用于支持应用内购买的游戏）—— 仅限俄罗斯地区玩家。
有关这些参数的更多信息，请参阅用户个人资料数据。
访问用户数据取决于其个人资料中的隐私设置。如果玩家禁止访问个人数据，响应中将只包含用户ID。
要授权用户并在您的服务器上保存游戏状态数据，请使用可选参数 { signed: true } 和 fetch() 方法。这将允许您使用密钥验证玩家的真实性并避免可能的作弊。密钥在连接应用内购买后可用。
1const ysdk = await YaGames.init();
2
3try {
4 const player = await ysdk.getPlayer({ signed: true });
5
6 // 使用 player.signature 在您的服务器上进行授权。
7 const authData = await fetch('https://your.game.server/auth', {
8 method: 'POST',
9 headers: { 'Content-Type': 'text/plain' },
10 body: player.signature
11 });
12} catch (e) {
13 // 初始化 Player 对象或授权时出错。
14}
发送到服务器的请求中的 signature 参数包含 Yandex 个人资料中的用户数据和签名。该参数由两个 base64 编码的字符串组成：
<签名>.<个人资料数据>
详情请参见防作弊保护。
备注
请求的发送频率不能超过每5分钟20次，否则将会因错误而被拒绝。
用户授权
检查授权
要检查玩家是否已在 Yandex 上授权，请使用 Player 对象的 player.isAuthorized() 方法。该方法返回 true | false。
注意
方法 player.getMode(): 'lite' | '' 已弃用，未来将从接口中移除。
调用授权对话框
要调用授权窗口，请使用 ysdk.auth.openAuthDialog() 方法。
重要
将授权的好处通知用户。如果用户不了解授权的必要性，很可能会拒绝授权并退出游戏。
详细信息请参阅授权提案。
1const ysdk = await YaGames.init();
2
3try {
4 let player = await ysdk.getPlayer();
5
6 // 玩家未授权。
7 if (!player.isAuthorized()) {
8 try {
9 // 打开授权窗口。
10 await ysdk.auth.openAuthDialog();
11
12 const authorizedPlayer = await ysdk.getPlayer();
13
14 player = authorizedPlayer;
15 } catch (e) {
16 // 玩家授权或重新初始化 Player 对象时出错。
17 }
18 }
19 // 玩家已成功授权。
20} catch (err) {
21 // 初始化 Player 对象时出错。
22}
游戏内数据
要处理用户的游戏内数据，请使用 Player 对象方法。
player.setData(data, flush)
保存用户数据。每个玩家的数据大小上限为 200 KB。
方法签名
function setData(data: object, flush: boolean) => Promise<void> {}
接受参数：
|
参数 |
类型 |
说明 |
|
|
|
包含键值对的对象。 |
|
|
|
确定数据发送的优先级:
|
该方法返回 Promise，表示数据是否保存成功。
当参数值为 flush: false 时，返回的结果仅显示数据有效性（数据发送已排入队列，将在稍后执行）。此时，player.getData() 方法将返回最后一次调用 player.setData() 设置的数据，即使这些数据尚未发送。
备注
请求的发送频率不能超过每5分钟100次，否则将会因错误而被拒绝。
示例
1const ysdk = await YaGames.init();
2
3const player = await ysdk.getPlayer();
4
5await player.setData({
6 achievements: ['trophy1', 'trophy2', 'trophy3']
7});
8
9console.log('data is set');
player.getData(keys)
异步返回存储在 Yandex 数据库中的游戏内用户数据。
方法签名
function getData(keys?: Array<string>) => Promise<object> {}
接受参数：
|
参数 |
类型 |
说明 |
|
|
|
需要返回的键列表。如果缺少 |
该方法返回 Promise<object>，其中的对象包含键值对。
备注
请求的发送频率不能超过每5分钟100次，否则将会因错误而被拒绝。
player.setStats(stats)
保存用户的数值数据。每个玩家的数值数据大小上限为 10 KB。
提示
对于频繁变化的数值（得分、经验值、游戏货币），应使用该方法，而不是 player.setData().
方法签名
function setStats(stats?: object) => Promise<void> {}
接受参数：
|
参数 |
类型 |
说明 |
|
|
|
包含键值对的对象，其中每个值必须是数字。 |
该方法返回 Promise，表示数据是否保存成功。
备注
请求的发送频率不能超过每1分钟60次，否则将会因错误而被拒绝。
player.incrementStats(increments)
更改用户的数值数据。每个玩家的数值数据大小上限为 10 KB。
方法签名
function incrementStats(increments: object) => Promise<object> {}
接受参数：
|
参数 |
类型 |
说明 |
|
|
|
包含键值对的对象，其中每个值必须是数字。 |
该方法返回 Promise<object>，其中的对象包含更改和添加的键值对。
备注
请求的发送频率不能超过每1分钟60次，否则将会因错误而被拒绝。
player.getStats(keys)
异步返回用户的数值数据。
方法签名
function getStats(keys?: Array<string>) => Promise<object> {}
接受参数：
|
参数 |
类型 |
说明 |
|
|
|
需要返回的键列表。如果缺少 |
该方法返回 Promise<object>，其中的对象包含键值对。
备注
请求的发送频率不能超过每1分钟60次，否则将会因错误而被拒绝。
用户个人资料数据
要从 Yandex 用户个人资料中获取数据，请使用 Player 对象方法。
player.getUniqueID()
返回用户的唯一永久 ID。
方法签名
function getUniqueID() => string {}
备注
方法 player.getID() 已弃用，但仍可以继续使用，这会在错误控制台中引发警告。
一般来说，对于某个 Player 对象，player.getID() 和 player.getUniqueID() 的值并不相同，但对于某些用户来说却可能是相同的。如果值不同且游戏本身已将某些数据关联到 player.getID() 值，则您需要迁移该数据并将其关联到 player.getUniqueID() 的值。要一次性迁移所有用户的数据，请联系支持服务.
player.getIDsPerGame()
注意
该请求仅供已授权用户使用。如何检查授权状态和调用登录对话框，请参见用户授权。
在发送请求之前，请使用 ysdk.isAvailableMethod('player.getIDsPerGame') 检查该方法的可用性。该方法返回 Promise<Boolean>。
该方法返回对象数组，其中包含用户在开发者所有游戏中的 ID，前提是用户明确同意传输个人数据。
方法签名
function getIDsPerGame() => Promise<Array<{ appID: number, userID: string }>> {}
player.getName()
返回用户的名称。
方法签名
function getName() => string {}
player.getPhoto()
根据请求的图像大小返回用户头像的 URL。
方法签名
function getPhoto(size: 'small' | 'medium' | 'large') => string {}
player.getPayingStatus()
返回取决于用户购买频率和金额的值。
方法签名
function getPayingStatus() => EPayingStatus {}
EPayingStatus 可取以下值之一：
|
值 |
说明 |
|
|
用户在过去一个月内购买了价值超过500卢布的平台货币。 |
|
|
用户在过去一年内至少有一次用真实货币购买平台货币的记录。 |
|
|
用户在过去一年内没有用真实货币购买平台货币。 |
|
|
用户不在俄罗斯联邦，或者用户未允许向开发者传输此类信息。 |
示例
1const ysdk = await YaGames.init(); // 初始化 SDK。
2const player = await ysdk.getPlayer(); // 获取玩家。
3const payingStatus = player.getPayingStatus(); // 获取用户在平台上的付费活跃度状态。
4
5if (payingStatus === 'paying' || payingStatus === 'partially_paying') {
6 // 在开始时或代替广告提供应用内商品。
7}
方法限制
|
方法 |
说明 |
限制 |
|
|
5分钟内20次请求 |
|
|
|
5分钟内100次请求 |
|
|
|
||
|
|
1分钟内60次请求 |
|
|
|
||
|
|
iOS 进度丢失
如果您使用自己的域名集成游戏，localStorage 在新版 iOS 中可能会经常重置，这会导致玩家进度丢失。为避免发生这种情况，请使用与 localStorage 具有相同接口的 safeStorage：
1const ysdk = await YaGames.init();
2
3const safeStorage = await ysdk.getStorage();
4
5safeStorage.setItem('key', 'safe storage is working');
6console.log(safeStorage.getItem('key'));
为了避免手动更改代码，请全局重新定义 localStorage。
注意
重新定义前请确保 localStorage 不在使用中。
1const ysdk = await YaGames.init();
2
3const safeStorage = await ysdk.getStorage();
4
5Object.defineProperty(window, 'localStorage', { get: () => safeStorage });
6
7localStorage.setItem('key', 'safe storage is working');
8console.log(localStorage.getItem('key'));
如果您将源代码作为存档上传，则不需要执行任何操作：SDK 中的特殊包装器会自动使 localStorage 变得可靠。
问题解决
如果保存大小超过SDK限制怎么办？
SDK方法对每个玩家的最大数据大小有限制：
|
方法 |
描述 |
限制 |
|
|
200 KB |
|
|
|
10 KB |
如果您的游戏需要保存更多数据（例如，在拥有大量单位或复杂世界状态的策略游戏中），请使用您自己的服务器来存储进度。有关数据存储方法的更多信息，请参阅保存进度的位置。
如何通过代码重置玩家进度？
要清除玩家数据，请使用player.setData()和player.setStats()方法写入空进度。
要测试进度重置，您还可以使用debug面板上的☁️ Clear cloud data按钮。
备注
技术支持团队将协助您将已完成的游戏发布到 Yandex 游戏平台。关于开发和测试方面的具体问题，其他开发人员将在Discord 频道中进行回答。
如果您遇到 Yandex Games SDK 方面的问题或有其他问题想要咨询，请联系支持部门：