Integra le API Friends (Java)

A seguito del ritiro dell'API Google Sign-In, rimuoveremo l'SDK v1 per i giochi nel 2026. Dopo febbraio 2025, non potrai pubblicare su Google Play titoli che sono stati integrati di recente con l'SDK v1 per i giochi. Ti consigliamo di utilizzare l'SDK v2 per i giochi.
Anche se i titoli esistenti integrati in precedenza con l'SDK v1 per i giochi continueranno a funzionare per un paio di anni, ti consigliamo di eseguire la migrazione all'SDK v2 a partire da giugno 2025.
Questa guida riguarda l'utilizzo dell'SDK Play Games Services v1. Per informazioni sull'ultima versione dell'SDK, consulta la documentazione della versione 2.

Segui i passaggi descritti in questa guida per implementare le API Friends nel codice Java del tuo gioco.

Caricare amici

Puoi recuperare e visualizzare (nel gioco) un elenco di giocatori amici dell'utente corrente. In qualità di utente, è possibile controllare quali giochi hanno accesso all'elenco di amici. Quando recuperi l'elenco di amici, devi gestire il caso in cui è richiesta l'autorizzazione. Tutto questo è incapsulato nell'API per semplificare la richiesta di accesso e il successivo utilizzo dell'elenco di amici. Per caricare l'elenco di amici:

  1. Chiama il metodo PlayersClient.loadFriends(), che è una chiamata asincrona che restituisce un oggetto Task.
  2. Se la chiamata ha esito positivo (l'utente ha già concesso l'accesso all'elenco di amici), l'SDK Google Play Games Services restituisce un PlayerBuffer annotato che rappresenta gli amici dell'utente.

  3. Se il giocatore deve concedere l'accesso all'elenco di amici, la chiamata non va a buon fine e viene visualizzata la classe FriendsResolutionRequiredException. Ancora non vengono mostrate finestre di dialogo.

    1. Questa eccezione contiene un Intent che attiva una finestra di dialogo per chiedere il consenso al giocatore. Puoi avviare questo Intent immediatamente per aprire una finestra di dialogo per il consenso. Puoi utilizzare questo Intent una sola volta.

    2. Se il risultato dell'attività di Intent è Activity.RESULT_OK, il consenso è stato concesso. Chiama di nuovo loadFriends() per restituire l'elenco degli amici. Se il risultato è Activity.RESULT_CANCELLED, l'utente non ha dato il consenso e loadFriends() continuerà a restituire FriendsResolutionRequiredException.

Il seguente codice mostra come implementare il caricamento dell'elenco di amici:

// 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.
Games.getPlayersClient(this, GoogleSignIn.getLastSignedInAccount(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;
}

Il seguente codice mostra come gestire il risultato della richiesta di consenso:

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

Visualizzare il profilo di un altro giocatore

Puoi mostrare il profilo Play Giochi di un altro giocatore all'interno del gioco. Questa visualizzazione consente ai giocatori di inviare e accettare inviti di amicizia per il giocatore visualizzato. Questa visualizzazione non richiede l'accesso all'elenco di amici. Inoltre, se il tuo gioco ha un proprio concetto di nomi dei giocatori separato dagli ID giocatore di Play Giochi, puoi trasmetterli alla visualizzazione del profilo in modo che possano essere inclusi in eventuali inviti di amicizia per un contesto aggiuntivo.

Per mostrare il profilo di un altro giocatore:

  1. Chiama il metodo PlayersClient.getCompareProfileIntent(), che è una chiamata asincrona che restituisce un oggetto Task.
  2. Se la chiamata ha esito positivo, l'SDK Google Play Games Services restituisce una classe Intent che mostrerà una schermata in cui l'utente può confrontare il proprio profilo con quello di un altro giocatore.
  3. Utilizza la classe Intent del passaggio precedente per avviare un'attività.
// Retrieve and launch an Intent to show a player profile within the game.
Games.getPlayersClient(this, GoogleSignIn.getLastSignedInAccount(this))
    .getCompareProfileIntent(otherPlayerId)
    .addOnSuccessListener(new OnSuccessListener<Intent>() {
        @Override
        public void onSuccess(Intent  intent) {
          startActivityForResult(intent, RC_SHOW_PROFILE);
          // ...
        }});

Se il gioco ha un proprio nome per i giocatori, questi possono essere aggiunti alla chiamata API. In questo modo, Play Giochi può impostare il nickname dei giocatori che inviano inviti di amicizia dal tuo gioco a "<nome-specifico-del-gioco> da <nome-del-tuo-gioco>" (Play Giochi aggiunge automaticamente "da <nome-del-tuo-gioco>"):

// 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.
Games.PlayersClient(this, GoogleSignIn.getLastSignedInAccount(this))
    .getCompareProfileIntentWithAlternativeNameHints(otherPlayerId, otherPlayerInGameName, currentPlayerInGameName)
    .addOnSuccessListener(new OnSuccessListener<Intent>() {
        @Override
        public void onSuccess(Intent  intent) {
          startActivityForResult(intent, RC_SHOW_PROFILE);
          // ...
        }});