集成 Friends API (Java)

随着 Google 登录 API 的弃用，我们将在 2026 年移除 games v1 SDK。2025 年 2 月后，您将无法在 Google Play 上发布新集成了 games v1 SDK 的游戏。我们建议您改用 games v2 SDK。
虽然现有集成了旧版 games v1 的游戏在未来几年内仍可运行，但建议您从 2025 年 6 月开始迁移到 v2。
本指南介绍了如何使用 Play Games Services v1 SDK。有关最新 SDK 版本的信息，请参阅v2 文档。

使用本指南中的步骤在您的 Java 游戏代码中实现 Friends API。

加载好友

您可以检索并显示（在游戏中）当前用户的好友列表。作为用户，可以控制哪些游戏可以访问好友列表。当您检索好友列表时，必须处理需要权限的情况。这一切都封装在 API 中，以便请求访问权限并随后使用好友列表成为一个直接的任务。要加载好友列表，请按照以下步骤操作：

  1. 调用 PlayersClient.loadFriends() 方法，这是一个异步调用，返回一个 Task 对象。
  2. 如果调用成功（用户已授予访问好友列表的权限），Google Play Games Services 会返回一个带注解的 PlayerBuffer，该对象代表用户的好友。

  3. 如果玩家需要授予访问好友列表的权限，则调用会因 FriendsResolutionRequiredException 而失败。此时尚未显示任何对话框。

    1. 此异常包含一个 Intent，可触发对话框以请求玩家同意。您可以立即启动此 Intent 以打开同意对话框。此 Intent 只能使用一次。

    2. 如果 Intent 的活动结果为 Activity.RESULT_OK，则表示已授予同意。再次调用 loadFriends() 可返回好友列表。如果结果为 Activity.RESULT_CANCELLED，则表示用户未同意，并且 loadFriends() 将继续返回 FriendsResolutionRequiredException。

以下代码展示了如何实现好友列表的加载：

// Attempt loading friends.
// Register a success listener to handle the successfully loaded friends list.
// Register a failure listener to handle asking for permission to access the list.
Games.getPlayersClient(this, GoogleSignIn.getLastSignedInAccount(this))
    .loadFriends(PAGE_SIZE, /* forceReload= */ false)
    .addOnSuccessListener(
        new OnSuccessListener<AnnotatedData<PlayerBuffer>>() {
            @Override
            public void onSuccess(AnnotatedData<PlayerBuffer>  data) {
          PlayerBuffer playerBuffer = data.get();
          // ...
        })

    .addOnFailureListener(
        exception -> {
      if (exception instanceof FriendsResolutionRequiredException) {
        PendingIntent pendingIntent =
            ((FriendsResolutionRequiredException) task.getException())
            .getResolution();
        parentActivity.startIntentSenderForResult(
            pendingIntent.getIntentSender(),
            /* requestCode */ SHOW_SHARING_FRIENDS_CONSENT,
            /* fillInIntent */ null,
            /* flagsMask */ 0,
            /* flagsValues */ 0,
            /* extraFlags */ 0,
            /* options */ null);
     }
   });
 return;
}

以下代码展示了如何处理请求同意的结果：

/** Handle the activity result from the request for consent. */
@Override
public void onActivityResult(int requestCode, int result, Intent data) {
  if (requestCode == SHOW_SHARING_FRIENDS_CONSENT) {
    if (result == Activity.RESULT_OK) {
      // We got consent from the user to access their friends. Retry loading the friends
      callLoadFriends();
    } else {
      // User did not grant consent.
    }
  }
}

查看其他玩家的个人资料

您可以在游戏中显示其他玩家的 Play Games 个人资料视图。此视图允许玩家发送和接受被查看玩家的好友邀请。此视图不需要访问好友列表。此外，如果您的游戏有自己的独立于 Play Games 玩家 ID 的玩家名称概念，您可以将其传递给个人资料视图，以便将其包含在任何好友邀请中以提供更多上下文。

要显示其他玩家的个人资料，请按照以下步骤操作：

  1. 调用 PlayersClient.getCompareProfileIntent() 方法，这是一个异步调用，返回一个 Task 对象。
  2. 如果调用成功，Google Play Games Services 会返回一个 Intent，该 Intent 将显示一个屏幕，用户可以在其中比较自己与另一位玩家的个人资料。
  3. 使用上一步的 Intent 启动 activity。
// Retrieve and launch an Intent to show a player profile within the game.
Games.getPlayersClient(this, GoogleSignIn.getLastSignedInAccount(this))
    .getCompareProfileIntent(otherPlayerId)
    .addOnSuccessListener(new OnSuccessListener<Intent>() {
        @Override
        public void onSuccess(Intent  intent) {
          startActivityForResult(intent, RC_SHOW_PROFILE);
          // ...
        }});

如果游戏有自己的玩家名称，可以将其添加到 API 调用中。这样一来，Play Games 就可以将在您的游戏中发送好友邀请的玩家的昵称设置为“<特定于游戏的名称>，来自 <您的游戏名称>”（Play Games 会自动附加“来自 <您的游戏名称>”）

// Show a player profile within the game, with additional hints containing the
// game-specific names for both players.
// - otherPlayerId is the Play Games playerId of the player to view.
// - otherPlayerInGameName is the game-specific name of the player being viewed.
// - currentPlayerInGameName is the game-specific name of the player who is signed
//   in. Hence if the player sends an invitation to the profile they are viewing,
//   their game-specific name can be included.
Games.PlayersClient(this, GoogleSignIn.getLastSignedInAccount(this))
    .getCompareProfileIntentWithAlternativeNameHints(otherPlayerId, otherPlayerInGameName, currentPlayerInGameName)
    .addOnSuccessListener(new OnSuccessListener<Intent>() {
        @Override
        public void onSuccess(Intent  intent) {
          startActivityForResult(intent, RC_SHOW_PROFILE);
          // ...
        }});