玩家数据

您可以在 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> {}

接受参数：

参数

类型

说明

data

object

包含键值对的对象。

flush

boolean

确定数据发送的优先级:

true —— 数据将立即发送到服务器。
false（默认值）—— 数据发送请求将排队等待。

该方法返回 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> {}

接受参数：

参数	类型	说明
`keys`	`Array<string>`	需要返回的键列表。如果缺少 `keys` 参数，该方法将返回用户的所有游戏内数据。

该方法返回 Promise<object>，其中的对象包含键值对。

备注

请求的发送频率不能超过每5分钟100次，否则将会因错误而被拒绝。

player.setStats(stats)

保存用户的数值数据。每个玩家的数值数据大小上限为 10 KB。

提示

对于频繁变化的数值（得分、经验值、游戏货币），应使用该方法，而不是 player.setData().

方法签名：

function setStats(stats?: object) => Promise<void> {}

接受参数：

参数	类型	说明
`stats`	`object`	包含键值对的对象，其中每个值必须是数字。

该方法返回 Promise，表示数据是否保存成功。

备注

请求的发送频率不能超过每1分钟60次，否则将会因错误而被拒绝。

player.incrementStats(increments)

更改用户的数值数据。每个玩家的数值数据大小上限为 10 KB。

方法签名：

function incrementStats(increments: object) => Promise<object> {}

接受参数：

参数	类型	说明
`increments`	`object`	包含键值对的对象，其中每个值必须是数字。

该方法返回 Promise<object>，其中的对象包含更改和添加的键值对。

备注

请求的发送频率不能超过每1分钟60次，否则将会因错误而被拒绝。

player.getStats(keys)

异步返回用户的数值数据。

方法签名：

function getStats(keys?: Array<string>) => Promise<object> {}

接受参数：

参数	类型	说明
`keys`	`Array<string>`	需要返回的键列表。如果缺少 `keys` 参数，该方法将返回用户的所有数值数据。

该方法返回 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 可取以下值之一：

值	说明
`paying`	用户在过去一个月内购买了价值超过500卢布的平台货币。
`partially_paying`	用户在过去一年内至少有一次用真实货币购买平台货币的记录。
`not_paying`	用户在过去一年内没有用真实货币购买平台货币。
`unknown`	用户不在俄罗斯联邦，或者用户未允许向开发者传输此类信息。

示例

1const ysdk = await YaGames.init(); // 初始化 SDK。
2const player = await ysdk.getPlayer(); // 获取玩家。
3const payingStatus = player.getPayingStatus(); // 获取用户在平台上的付费活跃度状态。
4
5if (payingStatus === 'paying' || payingStatus === 'partially_paying') {
6    // 在开始时或代替广告提供应用内商品。
7}

方法限制

方法	说明	限制
`ysdk.getPlayer()`	初始化 `Player` 对象	5分钟内20次请求
`player.setData()`	保存用户数据	5分钟内100次请求
`player.getData()`	异步返回用户的游戏内数据	5分钟内100次请求
`player.setStats()`	保存用户的数值数据	1分钟内60次请求
`player.getStats()`	异步返回用户的数值数据
`player.incrementStats()`	修改用户的数值数据

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 变得可靠。

备注

技术支持团队将协助您将已完成的游戏发布到 Yandex 游戏平台。关于开发和测试方面的具体问题，其他开发人员将在Discord 频道中进行回答。

如果您遇到 Yandex Games SDK 方面的问题或有其他问题想要咨询，请联系支持部门：

写入聊天信息

这篇文章是否有用？

事件

远程配置