Amigos en juegos de Android

En esta guía, se describe cómo usar las APIs de Friends en proyectos de Android Studio.

Carga amigos

Puedes recuperar y mostrar (en el juego) una lista de jugadores que son amigos del usuario actual. Como usuario, es posible controlar qué juegos tienen acceso a la lista de amigos. Cuando recuperas la lista de amigos, debes manejar el caso en el que se requiera permiso. Todo está encapsulado en la API para solicitar acceso y, posteriormente, usar la lista de amigos como una tarea sencilla. Para cargar la lista de amigos, sigue estos pasos:

  1. Llama al método PlayersClient.loadFriends(), que es una llamada asíncrona que muestra un objeto Task.
  2. Si la llamada se realiza de forma correcta, (el usuario ya otorgó acceso a la lista de amigos), los Servicios de juego de Google Play muestran un PlayerBuffer con anotaciones que representa a los amigos del usuario.

  3. Si el jugador necesita otorgar acceso a la lista de amigos, la llamada falla con FriendsResolutionRequiredException. Aún no se muestran diálogos.

    1. Esta excepción contiene un Intent que activa un diálogo para solicitar el consentimiento del jugador. Puedes iniciar este Intent de inmediato para abrir un cuadro de diálogo de consentimiento. Solo puedes usar este Intent una vez.

    2. Si el resultado de la actividad de Intent es Activity.RESULT_OK, se otorgó el consentimiento. Vuelve a llamar a loadFriends() para que se muestre la lista de amigos. Si el resultado es Activity.RESULT_CANCELLED, el usuario no dio su consentimiento, y loadFriends() seguirá mostrando FriendsResolutionRequiredException.

En el siguiente código, se muestra cómo cargar la lista de amigos:

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

En el siguiente código, se muestra cómo manejar el resultado de la solicitud de consentimiento:

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

Consulta el perfil de otro jugador

Puedes mostrar una vista del perfil de Play Juegos de otro jugador dentro de tu juego. Esta vista permite que los jugadores envíen y acepten invitaciones de amistad del jugador cuyo perfil se consulta. Esta vista no requiere acceso a la lista de amigos. Además, si tu juego tiene su propio concepto de nombres de los jugadores diferentes a los ID de jugador de Play Juegos, puedes pasarlos a la vista de perfil, de modo que se incluyan en cualquier invitación de amigo para proporcionar contexto adicional.

Para mostrar el perfil de otro jugador, sigue estos pasos:

  1. Llama al método PlayersClient.getCompareProfileIntent(), que es una llamada asíncrona que muestra un objeto Task.
  2. Si la llamada se realiza de forma correcta, los Servicios de juego de Google Play mostrarán un intent con una pantalla en la que el usuario puede compararse con el perfil de otro jugador.
  3. Usa Intent del paso anterior para iniciar una actividad.
// 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 el juego tiene su propio nombre para los jugadores, estos se pueden agregar a la llamada a la API. Esto permite que Play Juegos establezca el sobrenombre de los jugadores que envían invitaciones de amistad dentro de tu juego a "<game-specific-name> from <your-game-name>" (Play Juegos agrega automáticamente "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);
          // ...
        }});