好友

借助 Friends API，您可以对现有的游戏内好友系统以及游戏可以访问的其他社交系统进行补充和增强。您可以为玩家提供以下功能：

• 在游戏中查找好友。

• 在排行榜上与好友一较高下。

• 将 Play 游戏好友列表与现有的游戏内好友列表合并。

• 通过游戏内玩家资料弹出式窗口识别其他玩家。此弹出式窗口会显示当前玩家为其好友指定的昵称，以便知晓自己正在与哪些其他玩家一起玩游戏。

基础知识

借助这些 API，您可以执行以下操作：

• 加载好友：您可以查看玩家是否已允许游戏访问好友列表信息。授予访问权限后，您可以获取与已登录玩家的好友相对应的 Player 对象列表。
• 启动另一个玩家的 Play 游戏玩家资料的视图：您可以打开此视图，其中将显示已登录玩家为其他玩家指定的名称。此视图还提供好友管理控件，并且不会使玩家退出游戏。
• 提供用户控件：这些控件可允许用户管理其 Play 游戏玩家资料是否向好友显示以及其好友列表是否向游戏显示。对于好友列表访问权限，用户可以选择自动为所有游戏授予访问权限，也可以选择单独为每个游戏授予访问权限。因此，加载好友列表时可能会产生一个回调，该回调将显示获取访问权限的请求。

导入 Play 游戏好友列表

您可以使用 Friends API 来获取玩家的 Play 游戏好友列表，并将其添加到游戏内的好友列表中。

新用户将拥有一个起始好友列表，现有用户则可以将其 Play 游戏好友导入任何游戏内好友列表。 因此，您的用户将能够与尽可能多的玩家一起玩游戏，或者进行对战。

注意：如果您存储来自 Play 游戏的任何关系，则需要定期检查好友列表，以确保这些关系以及用户同意您使用这些关系的声明仍然有效。

将 Play 游戏好友添加到您的游戏中

如需将 Play 游戏好友添加到任何现有的游戏内好友列表中，请将 Play 游戏好友的 Play 游戏服务 ID 与您的内部数据库中的相应玩家信息相关联。请确保这些好友旁边会显示一个带有 Play 游戏图标的按钮。用户按下该按钮可以查看其他玩家的资料，以便确认好友的身份。

从后端服务器使用好友列表时，请使用 REST API 安全地进行加载，而不是传递 Android API 的结果。请确保使用 REST API 中的 players.get(me) 针对当前登录玩家返回的玩家 ID，因为这将与其他玩家看到的 ID 相一致。

如果未存储扩充的好友列表（但仅在查看时使用），则无需执行任何额外的操作。

授予 Play 游戏访问权限

如果您的游戏尚未获得 Play 游戏访问权限，一种有效的方式是在用户查看游戏内好友列表时通过弹出式窗口向用户征求同意。例如，您可以添加一个名为 Import Play Games friends 的按钮，当用户点按该按钮时，系统会向用户征求同意。（请务必在任何提及服务的按钮上使用 Play 游戏徽标。）

查看其他玩家的个人资料

您可以允许已登录玩家查看其他玩家的 Play 游戏玩家资料。这样一来，已登录玩家就可以查看为其他玩家指定的名称，以及他们是否已经是好友，从而为其他玩家添加其关系的相关背景信息。如果玩家还不是好友，则已登录玩家将在玩家资料视图中看到好友管理控件。在游戏内建立好友关系时，两位玩家的默认名称均为各自的游戏内名称（如果提供）。此外，还会显示发起了好友关系的游戏的名称。

社交排行榜

Friends API 也可用于排行榜。此功能可用于显示当前玩家在其 Play 游戏好友中的排名。请注意，这仅适用于已选择与您的应用共享此信息的用户，而且这些用户已经在 Play 游戏中建立了好友关系。为了支持此功能，游戏为用户提供了控件。此控件使用 collection 参数来选择排行榜的社交视图。如需了解详情，请参阅公开排行榜和社交排行榜部分。

如果您实现了社交排行榜收藏集，则在调用加载排行榜得分时可能会返回类似于 loadFriends() 中的“需要征求用户同意 (consent-required)”解析异常。如果您实现了 Play 游戏提供的默认界面（例如 getLeaderboardIntent()），则系统会自动为您执行相关处理。

后续步骤

在开始使用 Friends API 之前，请执行以下操作：

• 下载并查看代码示例：
  • Java
  • 使用 Unity 插件的 Unity 示例应用
• 熟悉质量核对清单中所述的建议。
• 在 Java 客户端中实现 Friends API。