Amigos em jogos para Android

Este guia descreve como usar as APIs Friends em projetos do Android Studio.

Carregar amigos

Você pode recuperar e mostrar (no jogo) uma lista de jogadores que são amigos do usuário atual. Como usuário, é possível controlar quais jogos têm acesso à lista de amigos. Ao recuperar a lista de amigos, é necessário processar o caso em que a permissão é necessária. Tudo isso é encapsulado na API para facilitar a solicitação de acesso e, posteriormente, usar a lista de amigos como uma tarefa simples. Para carregar a lista de amigos, siga estas etapas:

  1. Chame o método PlayersClient.loadFriends(), que é uma chamada assíncrona que retorna um objeto Task.
  2. Se a chamada for bem-sucedida (o usuário já concedeu acesso à lista de amigos), os serviços relacionados a jogos do Google vão retornar um PlayerBuffer anotado que representa os amigos do usuário.

  3. Se o jogador precisar conceder acesso à lista de amigos, a chamada vai falhar com um FriendsResolutionRequiredException. Nenhuma caixa de diálogo foi mostrada ainda.

    1. Essa exceção contém um Intent que aciona uma caixa de diálogo para solicitar o consentimento do jogador. Você pode iniciar esse Intent imediatamente para abrir uma caixa de diálogo de consentimento. Esse Intent só pode ser usado uma vez.

    2. Se o resultado da atividade da Intent for Activity.RESULT_OK, o consentimento foi dado. Chamar loadFriends() novamente para retornar a lista de amigos. Se o resultado for Activity.RESULT_CANCELLED, isso significa que o usuário não deu seu consentimento, e loadFriends() continuará retornando FriendsResolutionRequiredException.

O código a seguir mostra como carregar a 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;
}

O código a seguir mostra como processar o resultado da solicitação de consentimento:

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

Visitar o perfil de outro jogador

Você pode mostrar uma visualização do perfil do Play Games de outro jogador no seu jogo. Essa visualização permite que os jogadores enviem e aceitem convites de amigos que estejam sendo visualizados. Essa visualização não requer acesso à lista de amigos. Além disso, se o jogo tiver o próprio conceito de nomes de jogadores separados dos IDs de jogador do Play Games, você vai poder transmiti-los para a visualização de perfil para que eles possam ser incluídos em convites de amigos para mais contexto.

Para mostrar o perfil de outro jogador, siga estas etapas:

  1. Chame o método PlayersClient.getCompareProfileIntent(), que é uma chamada assíncrona que retorna um objeto Task.
  2. Se a chamada for bem-sucedida, os serviços relacionados a jogos do Google Play vão retornar uma intent que mostra uma tela em que o usuário pode se comparar com o perfil de outro jogador.
  3. Use o Intent da etapa anterior para iniciar uma atividade.
// 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);
          // ...
        }});

Se o jogo tiver seu próprio nome, os jogadores poderão adicioná-lo à chamada de API. Isso permite que o Play Games defina o apelido de jogadores que enviam convites de amigos no seu jogo como "<game-specific-name> from <your-game-name>". O Play Games anexa automaticamente "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);
          // ...
        }});