玩家数据

您可以在 Yandex 服务器上保存游戏状态数据（包括完成的关卡、经验和游戏内购），也可以将这些数据传输到您的服务器。您还可以通过使用 Yandex 个人资料中的用户数据（例如姓名）对游戏进行个性化。

Player 对象可用于处理用户数据。

初始化

要初始化 Player 对象，请使用 ysdk.getPlayer() 方法：

var player;

ysdk.getPlayer().then(_player => {
        player = _player;
    }).catch(err => {
        // 初始化 Player 对象时出错。
    });

初始化 Player 对象时会传入以下数据：

用户ID — 所有玩家都会包含。
头像和名称 — 仅限已授权玩家。
平台内购数据（仅适用于支持应用内购买的游戏）— 仅限俄罗斯地区玩家。

访问用户数据取决于其个人资料中的隐私设置。如果玩家禁止访问个人数据，响应中将只包含用户ID。

您可以使用可选的 signed: true 参数和 fetch 方法来登录用户，并将游戏状态数据保存在您的服务器上。这样您就可以使用签名来验证玩家身份并避免可能存在的欺诈。

var player;

ysdk.getPlayer({ signed: true }).then(_player => {
        player = _player;

        // 使用 player.signature 在您的服务器上进行授权。
        fetch('https://your.game.server?auth', {
            method: 'POST',
            headers: { 'Content-Type': 'text/plain' },
            body: player.signature
        });
    }).catch(err => {
        // 初始化 Player 对象时出错。
    });

发送到服务器的请求中的 signature 参数包含 Yandex 个人资料中的用户数据和签名。该参数由两个 Base64 编码的字符串组成：

<signature>.<profile data>

详情请参见欺诈防范。

备注

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

用户登录

检查用户是否登录

要检查玩家是否已在 Yandex Games 上授权，请使用 Player 对象的 player.isAuthorized() 方法。该方法返回 true | false。

注意

方法 player.getMode(): 'lite' | '' 已弃用，未来将从接口中移除。

调用登录对话框

如果玩家未登录，您可以使用 ysdk.auth.openAuthDialog() 方法打开登录对话框。

提示

将登录的好处通知用户。不了解这些好处的用户很可能跳过登录并退出游戏。

var player;

function initPlayer() {
    return ysdk.getPlayer().then(_player => {
            player = _player;

            return player;
        });
}

initPlayer().then(_player => {
        if (_player.isAuthorized() === false) {
            // 玩家未登录。
            ysdk.auth.openAuthDialog().then(() => {
                    // 玩家已登录。
                    initPlayer().catch(err => {
                        // 初始化 Player 对象时出错。
                    });
                }).catch(() => {
                    // 玩家未登录。
                });
        }
    }).catch(err => {
        // 初始化 Player 对象时出错。
    });

游戏内数据

要处理用户的游戏内数据，请使用 Player 对象方法：

player.setData(data, flush)：保存用户数据。数据大小上限不应超过 200 KB。
- data：对象，包含键值对的对象。
- flush：布尔值，指定数据发送顺序。如果该值为“true”，数据将立即发送到服务器；如果该值为“false”（默认值），发送数据的请求将排入队列。
该方法会返回表示数据是否保存的 Promise。

当参数值为 flush: false 时，返回的结果将只显示数据有效性（数据已排入队列以便之后发送时）。但是，如果您现在使用 player.getData()，将返回由 player.setData() 设置的最新数据，即使当前数据尚未发送。
```
player.setData({
        achievements: ['trophy1', 'trophy2', 'trophy3'],
    }).then(() => {
        console.log('data is set');
    });
```

player.getData(keys)：异步返回存储在 Yandex 数据库中的游戏内用户数据。
- keys：array，要返回的关键字列表。如果 keys 参数缺失，该方法会返回所有游戏内用户数据。
该方法可返回 Promise<Object>，其中的对象包含键值对。
player.setStats(stats)：保存用户的数值数据。数据大小上限不得超过 10 KB。
- stats：对象，包含键值对的对象，其中每个值都是数字。
该方法会返回表示数据是否保存的 Promise。

提示

对于频繁变化的数值（例如得分、经验值和游戏货币），应使用该方法，而不是 player.setData()。
player.incrementStats(increments)：更改游戏内用户数据。数据大小上限不得超过 10 KB。
- increments：对象，包含键值对的对象，其中每个值都是数字。
该方法可返回 Promise<Object>，其中的对象包含更改和添加的键值对。
player.getStats(keys)：异步返回用户的数值数据。
- keys：array，要返回的关键字列表。如果 keys 参数缺失，该方法会返回所有游戏内用户数据。
该方法可返回 Promise<Object>，其中的对象包含键值对。

备注

请求频率是有限制的。如果超出限制，请求将会因错误而被拒绝。

用户个人资料数据

要从 Yandex 用户个人资料中获取数据，请使用 Player 对象方法：

player.getUniqueID()：返回用户的唯一永久 ID（类型：字符串）。

备注

之前使用的 player.getID() 方法现已弃用，但仍可以继续使用一段时间，这会在错误控制台中引发警告。

一般来说，对于某个 Player 对象，player.getID() 和 player.getUniqueID() 的值并不相同，但对于某些用户来说却可能是相同的。如果值不同且游戏本身已将某些数据关联到 player.getID() 值，则您需要迁移该数据并将其关联到 player.getUniqueID() 的值。要一次性迁移所有用户的数据，请联系支持部门。
player.getIDsPerGame()：返回 Promise<Array>，将在所有用户明确同意迁移其个人数据的开发者游戏中指定用户 ID。例如：
```
[
    { appID: 103915, userID: "tOpLpSh7i8QG8Voh/SuPbeS4NKTj1OxATCTKQF92H4c=" },
    { appID: 103993, userID: "bviQCIAAuVmNMP66bZzC4x+4oSFzRKpteZ/euP/Jwv4=" }
]
```
注意

该方法仅供登录用户使用。如果需要，请使用授权。

要检查该方法是否可供用户使用，您可以使用 ysdk.isAvailableMethod('player.getIDsPerGame') 方法。它会返回 Promise<Boolean>，其中布尔值表示该方法是否可用。
player.getName()：返回用户的名称（类型：字符串）。
player.getPhoto(size)：返回用户头像的 URL（类型：字符串）。
- size：字符串，要求的大小。可能的值：small、medium、large。

方法限制

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

iOS 进度丢失

如果通过 iframe 集成游戏，则 localStorage 在新版 iOS 中可能会经常重置，这会导致玩家进度丢失。为避免发生这种情况，请使用与 localStorage 具有相同界面的 safeStorage：

ysdk.getStorage().then(safeStorage => {
        safeStorage.setItem('key', 'safe storage is working');
        console.log(safeStorage.getItem('key'))
    })

为了避免手动更改代码，请全局覆盖 localStorage。

注意

覆盖前请确保 localStorage 不在使用中。

ysdk.getStorage().then(safeStorage => Object.defineProperty(window, 'localStorage', { get: () => safeStorage }))
    .then(() => {
        localStorage.setItem('key', 'safe storage is working');
        console.log(localStorage.getItem('key'))
    })

如果您将源代码下载为存档，则不需要执行任何操作：SDK 中的特殊包装器会自动使 localStorage 变得可靠。

备注

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

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

发送电子邮件

这篇文章是否有用？

事件

远程配置