Android 游戏中的好友

本指南介绍了如何在 Android Studio 项目中使用 Friends API。

加载好友

您可以(在游戏中)检索并显示与当前用户是好友关系的玩家列表。用户可以控制哪些游戏具有对好友列表的访问权限。检索好友列表时,您需要处理需要权限的情况。这一切都封装在 API 中,使得请求访问权限以及随后使用好友列表变得很简单直观。如需加载好友列表,请按以下步骤操作:

  1. 调用 PlayersClient.loadFriends() 方法,这是返回 Task 对象的异步调用。
  2. 如果调用成功(用户已经授予访问好友列表的权限),Google Play 游戏服务会返回一个带有注解的 PlayerBuffer,用于表示用户的好友。
  3. 如果玩家需要授予对好友列表的访问权限,调用会失败并返回 FriendsResolutionRequiredException。这不会显示任何对话框。

    1. 此异常包含 Intent,它会触发一个向玩家征求同意的对话框。您可以立即启动此 Intent 以打开意见征求对话框。此 Intent 只能使用一次。
    2. 如果 Intent 的 activity 的结果为 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.
PlayGames.getPlayersClient(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 不同的玩家名称概念,您可以将这些名称传递给玩家资料视图,以支持将这些名称包含在任何好友邀请中以提供更多背景信息。

要显示其他玩家的资料,请按以下步骤操作:

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

如果游戏为玩家使用了自己的名称,则可以将这些名称添加到 API 调用中。这样一来,Play 游戏就可以将在您的游戏中发送好友邀请的玩家的别名设置为“<game-specific-name> from <your-game-name>”。Play 游戏会自动附加“from <your-game-name>”:

// 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.
PlayGames.PlayersClient(this)
    .getCompareProfileIntentWithAlternativeNameHints(otherPlayerId, otherPlayerInGameName, currentPlayerInGameName)
    .addOnSuccessListener(new OnSuccessListener<Intent>() {
        @Override
        public void onSuccess(Intent  intent) {
          startActivityForResult(intent, RC_SHOW_PROFILE);
          // ...
        }});