集成好友 API（Java）

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

加载好友

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

调用 PlayersClient.loadFriends() 方法，这是一个异步调用，返回一个 Task 对象。
如果调用成功（用户已授予对好友列表的访问权限），Google Play 游戏服务将返回一个带注释的 PlayerBuffer，表示用户的好友。
如果玩家需要授予对好友列表的访问权限，则调用将失败并出现 FriendsResolutionRequiredException。尚未显示任何对话框。
1. 此异常包含一个 Intent，该 Intent 将触发一个对话框以征求玩家的同意。您可以立即启动此 Intent 以打开同意对话框。您只能使用此 Intent 一次。
2. 如果 Intent 的活动结果为 Activity.RESULT_OK，则表示已授予同意。再次调用 loadFriends() 以返回好友列表。如果结果为 Activity.RESULT_CANCELLED，则用户未同意，loadFriends() 将继续返回 FriendsResolutionRequiredException。
  
  注意： 如果您从服务器调用 loadFriends() 并确定需要请求同意，则需要从游戏客户端再次调用 loadFriends()。第二次调用不会成功，但它将提供显示同意对话框所需的 Intent。

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

// 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 游戏个人资料视图。此视图允许玩家发送和接受正在查看的玩家的好友邀请。此视图不需要访问好友列表。此外，如果您的游戏具有与 Play 游戏游戏玩家 ID 分开的玩家名称概念，则可以将这些名称传递给个人资料视图，以便将其包含在任何好友邀请中以提供更多上下文。

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

调用 PlayersClient.getCompareProfileIntent() 方法，这是一个异步调用，返回一个 Task 对象。
如果调用成功，Google Play 游戏服务将返回一个 Intent，该 Intent 将显示一个屏幕，用户可以在其中将自己与其他玩家的个人资料进行比较。
使用上一步中的 Intent 启动活动。

// 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 游戏能够将从您的游戏中发送好友邀请的玩家的昵称设置为“<游戏特定名称> 来自 <您的游戏名称>”（Play 游戏会自动附加“来自 <您的游戏名称>”）

// 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);
          // ...
        }});