Amis dans les jeux Android

Ce guide explique comment utiliser les API Friends dans les projets Android Studio.

Charger des amis

Vous pouvez récupérer et afficher (dans le jeu) une liste de joueurs qui sont amis avec l'utilisateur actuel. En tant qu'utilisateur, il est possible de contrôler quels jeux ont accès à la liste d'amis. Lorsque vous récupérez la liste d'amis, vous devez gérer le cas où une autorisation est nécessaire. Tout cela est encapsulé dans l'API pour faciliter la demande d'accès, puis l'utilisation de la liste d'amis. Pour charger la liste d'amis, procédez comme suit :

1. Appelez la méthode PlayersClient.loadFriends(), qui est un appel asynchrone renvoyant un objet Task.
2. Si l'appel aboutit (l'utilisateur a déjà accordé l'accès à la liste d'amis), les services de jeux Google Play renvoient un PlayerBuffer annoté qui représente les amis de l'utilisateur.

3. Si le joueur doit accorder l'accès à la liste d'amis, l'appel échoue avec l'exception FriendsResolutionRequiredException. Aucune boîte de dialogue n'a encore été affichée.

   1. Cette exception contient un Intent qui déclenche l'affichage d'une boîte de dialogue demandant le consentement du joueur. Vous pouvez lancer immédiatement cet Intent pour ouvrir une boîte de dialogue de collecte du consentement. Vous ne pouvez utiliser cet Intent qu'une seule fois.

   2. Si le résultat de l'activité de l'Intent est Activity.RESULT_OK, cela signifie que le consentement a été accordé. Rappelez loadFriends() pour renvoyer la liste d'amis. Si le résultat est Activity.RESULT_CANCELLED, cela signifie que l'utilisateur n'a pas donné son consentement. loadFriends() continue donc à renvoyer l'exception FriendsResolutionRequiredException.

Le code suivant montre comment charger la liste d'amis :

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

Le code suivant montre comment gérer le résultat de la demande de consentement :

/** 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.
    }
  }
}

Afficher le profil d'un autre joueur

Vous pouvez afficher le profil Play Jeux d'un autre joueur dans votre jeu. Cette vue permet aux joueurs d'envoyer et d'accepter des invitations à devenir amis. Elle ne nécessite pas d'accéder à la liste d'amis. De plus, si votre jeu possède son propre concept de noms de joueurs, distinct des ID de joueur Play Jeux, vous pouvez les transmettre à la vue du profil afin qu'ils puissent être inclus dans les invitations à devenir amis pour plus de contexte.

Pour afficher le profil d'un autre joueur, procédez comme suit :

1. Appelez la méthode PlayersClient.getCompareProfileIntent(), qui est un appel asynchrone renvoyant un objet Task.
2. Si l'appel aboutit, les services de jeux Google Play renvoient un Intent qui affiche un écran permettant à l'utilisateur de se comparer au profil d'un autre joueur.
3. Utilisez l'Intent de l'étape précédente pour démarrer une activité.

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

Si le jeu possède son propre concept de noms de joueurs, ceux-ci peuvent être ajoutés à l'appel d'API. Play Jeux peut ainsi définir le pseudo des joueurs qui envoient des invitations à devenir amis depuis votre jeu sur "<game-specific-name> de <your-game-name>". Play Jeux ajoute automatiquement "de <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);
          // ...
        }});