Android ゲームの友だち

このガイドでは、Android Studio プロジェクトで Friends API を使用する方法について説明します。

友だちを読み込む

現在のユーザーと友だちになっているプレーヤーのリストを取得して（ゲーム内で）表示できます。ユーザーとして、どのゲームが友だちリストにアクセスできるようにするかを管理できます。友だちリストを取得するときは、権限が必要なケースに対処する必要があります。これはすべて API にカプセル化されているため、アクセスをリクエストし、その後に友だちリストを使用するというタスクを簡単に行えます。友だちリストを読み込む手順は次のとおりです。

  1. PlayersClient.loadFriends() メソッドを呼び出します。これは Task オブジェクトを返す非同期呼び出しです。
  2. 呼び出しが成功した場合（ユーザーがすでに友だちリストに対するアクセスを許可している場合）、Google Play Games サービスは、ユーザーの友だちを表すアノテーション付きの PlayerBuffer を返します。

  3. プレーヤーが友だちリストに対するアクセスを許可する必要がある場合、呼び出しは FriendsResolutionRequiredException で失敗します。ダイアログはまだ表示されません。

    1. この例外には、プレーヤーに同意を求めるダイアログをトリガーする Intent が含まれています。この Intent をすぐに起動すると、同意ダイアログを開くことができます。この Intent は 1 回だけ使用できます。

    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 Games サービスは、ユーザーが別のプレーヤーのプロフィールと自分を比較できる画面を表示するインテントを返します。
  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>」に設定できます。Play Games は自動的に「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);
          // ...
        }});