Android 遊戲中的好友

本指南說明如何在 Android Studio 專案使用 Friends API。

載入好友

您可以取得目前使用者的好友名單，並在遊戲中顯示這些玩家。使用者可以管理哪些遊戲可以存取好友名單。擷取好友名單時，如果需要取得權限，您必須處理這類情況。由於 API 已封裝所有相關動作，處理存取權要求和使用好友清單，一點也不複雜。您可以按照下列步驟載入好友名單：

  1. 呼叫 PlayersClient.loadFriends() 方法，這是非同步呼叫，會回傳 Task 物件。
  2. 如果呼叫成功，代表使用者已授權可存取好友清單，Google Play 遊戲服務就會傳回已加上註解的 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.
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 啟動活動。
// 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 Games 將玩家從你的遊戲中發送好友邀請時的暱稱，設為「<game-specific-name> from <your-game-name>」，其中「from <your-game-name>」會由 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.
PlayGames.PlayersClient(this)
    .getCompareProfileIntentWithAlternativeNameHints(otherPlayerId, otherPlayerInGameName, currentPlayerInGameName)
    .addOnSuccessListener(new OnSuccessListener<Intent>() {
        @Override
        public void onSuccess(Intent  intent) {
          startActivityForResult(intent, RC_SHOW_PROFILE);
          // ...
        }});