---
metadata:
  - name: generator
    content: Diplodoc Platform v5.54.4
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: zh/sdk/defold/player-data.md
    type: text/markdown
    title: Markdown version
  - href: ../../llms.txt
    type: text/markdown
    title: llms.txt
---
> **Documentation Index:** Fetch the complete configuration index at https://yandex.com/dev/games/doc/zh/llms.txt

# 玩家详情

<!-- 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 -->

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

## 玩家信息 {#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 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)` —— 保存玩家的数值型数据。数据最大不能超过 10KB。

    - `stats: table<string, number>` —— 包含键-值对，其中每个值必须为数字。

{% note info %}

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

{% endnote %}

- `ysdk.player.increment_stats(increments)` —— 修改用户的游戏内数据。数据的最大大小不能超过10KB。
    - `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/button-git.md -->
<a href="https://github.com/yandex-games-plugins/defold">
  <span class="button">存储库</span>
</a>
<!-- endsource: zh/_includes/button-git.md -->