# 玩家名称管理

> Manage player display names and handle naming updates throughout the player lifecycle.

SDK 最低版本：2.5.0-pre.3.确保您使用的是正确的版本。

玩家可以在其 Player ID 下关联一个玩家名称，使其能以更易于阅读的方式展现个性化身份。Player ID 精确对应一个玩家名称，反之亦然。

## 设置玩家名称##setting-player-name

玩家必须登录才能创建或更新玩家名称。使用 `AuthenticationService.Instance.UpdatePlayerNameAsync(playerName)`。玩家名称不应包含空格，最大长度应为 50 个字符。随机生成的后缀包含一个井号和四位数字（例如 #1234），会自动附在申请创建的名称后面。

如果玩家未登录或申请不成功，则 `UpdatePlayerNameAsync` 会抛出 RequestFailedException。如果因为身份验证错误而导致更新失败，则 `UpdatePlayerNameAsync` 会抛出 AuthenticationException。

## 获得玩家名称##getting-player-name

玩家必须登录才能获得玩家名称。使用 `AuthenticationService.Instance.GetPlayerNameAsync()`。如果没有找到该玩家的玩家名称，则会返回一个随机名称并分配给该玩家。

如果玩家未登录或申请不成功，则 `GetPlayerNameAsync` 会抛出 RequestFailedException。如果因为身份验证错误而导致获取失败，GetPlayerNameAsync 会抛出 AuthenticationException。

## 缓存##caching

每次调用 `UpdatePlayerNameAsync` 或 `GetPlayerNameAsync` 时，每个配置文件的玩家名称都会缓存在本地。要访问玩家名称的缓存值，请使用 `AuthenticationService.Instance.PlayerName`。在使用新玩家登录或注销后，或在玩家名称不存在时尝试调用 `GetPlayerNameAsync` 后，缓存值将清空。如果未设置缓存值，访问时会返回 null。