---
metadata:
  - name: generator
    content: Diplodoc Platform v5.66.0
alternate:
  - https://yandex.com/dev/games/doc/en/sdk/defold/player-data.md
  - https://yandex.com/dev/games/doc/hi/sdk/defold/player-data.md
  - https://yandex.com/dev/games/doc/ko/sdk/defold/player-data.md
  - https://yandex.com/dev/games/doc/ru/sdk/defold/player-data.md
  - https://yandex.com/dev/games/doc/tr/sdk/defold/player-data.md
  - https://yandex.com/dev/games/doc/vi/sdk/defold/player-data.md
  - https://yandex.com/dev/games/doc/zh/sdk/defold/player-data.md
  - href: https://yandex.com/dev/games/doc/zh/sdk/defold/player-data.md
    type: text/markdown
    title: Markdown version
  - href: https://yandex.com/dev/games/doc/zh/llms.txt?revision=r21993288
    rel: describedby
---
> **Documentation Index:** Fetch the complete configuration index at https://yandex.com/dev/games/doc/zh/llms.txt?revision=r21993288

# 玩家详情

<!-- source: zh/_includes/script-common.md -->
<!-- source: zh/_includes/script/index-js.md -->

<!-- endsource: zh/_includes/script/index-js.md -->

<!-- source: zh/_includes/script/requirements-js.md -->

<!-- endsource: zh/_includes/script/requirements-js.md -->

<!-- source: zh/_includes/script/image-modal-js.md -->

<!-- endsource: zh/_includes/script/image-modal-js.md -->
<!-- endsource: zh/_includes/script-common.md -->

<!-- source: zh/_includes/sdk/common-with-plugins.md -->
您可以：

- 使用 SDK 方法将游戏数据（已通过的关卡、经验、应用内购买等）保存在 Yandex 服务器上，或将其传输到您自己的服务器。 云存档允许用户在不同设备上继续游戏。
- 使用 Yandex 用户个人资料中的数据（例如姓名）来个性化游戏。
<!-- endsource: zh/_includes/sdk/common-with-plugins.md -->

## 玩家信息 {#player-info}

```lua showLineNumbers
ysdk.player.get_info(
    callback: function,
    options: {
        scopes: boolean|nil,
        signed: boolean|nil
    }
)
```

`callback: function` —— 被调用方法的回调。格式如下：

```lua
function(self, player: table|nil, signature: string|nil): nil
```

- `player: table` —— 玩家信息。包含以下属性：

```lua showLineNumbers
player = {
    logged_in: boolean,
    unique_id: string,
    name: string,
    photo: {
        small: string,
        medium: string,
        large: string
    }
}
```

**示例**

```lua showLineNumbers
function init_player()
    ysdk.player.get_info(function(self, player)
        if player then
            display_player(self, player)
        else
            ysdk.player.open_auth_dialog(function(self, authorized)
                ysdk.player.get_info(display_player, {})
            end)
        end
    end,
    {})
end

function display_player(player)
    if player then
        print(player.name, signature)
    end
end
```

## 用户登录 {#auth}

如果玩家未授权，您可以使用方法 `ysdk.player.open_auth_dialog()` 来弹出授权窗口。

```lua
ysdk.player.open_auth_dialog(callback: function)
```

`callback: function` —— 被调用方法的回调。其格式如下：

```lua
function(self, authorized: boolean): nil
```

- `authorized: boolean` —— 玩家是否已授权。

## 游戏内数据 {#ingame-data}

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

- `ysdk.player.set_data(data, flush)` —— 保存用户数据。数据最大大小不应超过 200&nbsp;KB。 {#setdata}
    - `data: table` —— 包含键-值对。
    - `flush: boolean` —— 确定数据发送的顺序。当值为 `true` 时，数据将立即发送到服务器；`false`（默认值）—— 数据发送请求将被加入队列。

该方法返回一个 `Promise`，用于指示数据是否保存成功。

当参数 `flush: false` 的值设置时，返回的结果仅显示数据的有效性（实际发送已加入队列，稍后执行）。此时，方法 `ysdk.player.get_data()` 将返回最后一次调用 `ysdk.player.set_data()` 所设置的数据，即使这些数据尚未发送。

- `ysdk.player.get_data(callback, keys)` —— 请求获取存储于 Yandex 数据库中的玩家游戏内数据。
    - `callback: fun(self, data: table<string, any>)` —— 用于处理获取到的玩家游戏内数据的回调函数。
    - `keys: table<number, string>` —— 需要返回的键列表。如果缺少 `keys` 参数，该方法将返回用户的所有游戏内数据。

- `ysdk.player.set_stats(stats)` —— 保存用户的数值数据。数据最大大小不应超过 10&nbsp;KB。
    - `stats: table<string, number>` —— 包含键-值对，其中每个值必须为数字。

{% note info %}

请使用此方法来处理经常变化的数值类型（如积分、经验值、游戏内货币），而不是使用 [ysdk.player.set_data()](#setdata)。

{% endnote %}

- `ysdk.player.increment_stats(increments)` —— 修改用户的游戏内数据。数据最大大小不应超过 10&nbsp;KB。
    - `increments: table<string, number>` —— 包含键值对的对象，每个值必须是数字。
- `ysdk.player.get_stats(callback, keys)` —— 获取存储在 Yandex 数据库中的用户数值数据。
    - `callback: fun(self, data: table<string, number>|nil)` —— 用于处理获取到的用户数值数据的回调函数。
    - `keys: string[]` —— 需要返回的键列表。如果缺少 `keys` 参数，该方法将返回用户的所有游戏内数据。

## 用户标识符 {#user-ids}

```lua
ysdk.player.get_ids_per_game(callback: function)
```

`callback: function` —— 被调用方法的回调。格式如下：

```lua
function(self, ids: {appID: number, userID: string}[]): nil
```

- `ids` —— 用户在开发者所有游戏中的标识符，前提是用户已明确同意传输个人数据。包含以下属性：
    - `app_id: string` —— 应用程序的标识符。
    - `user_id: string` —— 用户的标识符。

**示例**

```lua showLineNumbers
function log_ids()
    ysdk.player.get_ids_per_game(function(self, ids)
        for _, value in ipairs(ids) do
            print(value.app_id, value.user_id)
        end
    end)
end
```

---


<!-- source: zh/_includes/sdk/button-git.md -->
<a href="https://github.com/yandex-games-plugins/defold">
  <span class="button">存储库</span>
</a>
<!-- endsource: zh/_includes/sdk/button-git.md -->