Accedi nei giochi Android

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 con le precedenti integrazioni di giochi v1 continueranno a funzionare per un paio di anni, ti consigliamo di eseguire la migrazione alla v2 a partire da giugno 2025.
Questa guida riguarda l'utilizzo dell'SDK v1 dei servizi per i giochi di Play. Per informazioni sull'ultima versione dell'SDK, consulta la documentazione della versione 2.

Per accedere alla funzionalità di Google Play Services per i giochi, il tuo gioco deve fornire l'account del giocatore che ha eseguito l'accesso. Se il giocatore non è autenticato, il tuo gioco potrebbe riscontrare errori quando effettua chiamate alle API Google Play Games Services. Questa documentazione descrive come implementare un'esperienza di accesso senza interruzioni nel tuo gioco.

Implementare l'accesso del giocatore

La classe GoogleSignInClient è il punto di accesso principale per recuperare l'account del giocatore attualmente connesso e per accedere se non l'ha ancora fatto nella tua app sul dispositivo.

Per creare un client di accesso:

  1. Crea un client di accesso tramite l'oggetto GoogleSignInOptions, come mostrato nello snippet di codice seguente. Nella GoogleSignInOptions.Builder per configurare l'accesso, devi specificare GoogleSignInOptions.DEFAULT_GAMES_SIGN_IN.

    GoogleSignInOptions signInOptions = GoogleSignInOptions.DEFAULT_GAMES_SIGN_IN;

  2. Se vuoi utilizzare un SnapshotsClient, aggiungi .requestScopes(Games.SCOPE_GAMES_SNAPSHOTS) al tuo GoogleSignInOptions.Builder come mostrato nello snippet di codice seguente:

    GoogleSignInOptions  signInOptions =
    new GoogleSignInOptions.Builder(GoogleSignInOptions.DEFAULT_GAMES_SIGN_IN)
        .requestScopes(Games.SCOPE_GAMES_SNAPSHOTS)
        .build();

  3. Chiama il metodo GoogleSignIn.getClient() e trasmetti le opzioni che hai configurato nei passaggi precedenti. Se la chiamata va a buon fine, l'API Google Sign-In restituisce un'istanza di GoogleSignInClient.

Controllare se il giocatore ha già eseguito l'accesso

Puoi verificare se è già stato eseguito l'accesso a un account sul dispositivo attuale utilizzando GoogleSignIn.getLastSignedInAccount() e se questo account dispone già delle autorizzazioni richieste utilizzando GoogleSignIn.hasPermissions(). Se entrambe le condizioni sono vere, ovvero getLastSignedInAccount() restituisce un valore non nullo e hasPermissions() restituisce true, puoi utilizzare in sicurezza l'account restituito da getLastSignedInAccount(), anche se il dispositivo è offline.

Eseguire un accesso silenzioso

Puoi chiamare silentSignIn() per recuperare l'account del giocatore attualmente connesso e provare ad accedere senza visualizzare un'interfaccia utente se ha eseguito l'accesso alla tua app su un altro dispositivo.

Il metodo silentSignIn() restituisce un Task<GoogleSignInAccount>. Al termine dell'attività, imposta il campo GoogleSignInAccount dichiarato in precedenza sull'account di accesso che l'attività restituisce come risultato o su null, indicando che non è presente un utente che ha eseguito l'accesso.

Se il tentativo di accesso automatico non va a buon fine, puoi inviare facoltativamente l'intent di accesso per visualizzare un'interfaccia utente di accesso, come descritto in Eseguire un accesso interattivo.

Poiché lo stato del giocatore che ha eseguito l'accesso può cambiare quando l'attività non è in primo piano, ti consigliamo di chiamare silentSignIn() dal metodo onResume() dell'attività.

Per eseguire l'accesso in modalità silenziosa, segui questi passaggi:

  1. Chiama il metodo silentSignIn() su GoogleSignInClient per avviare il flusso di accesso silenzioso. Questa chiamata restituisce un oggetto Task<GoogleSignInAccount> che contiene un GoogleSignInAccount se l'accesso automatico è riuscito.
  2. Gestisci l'esito positivo o negativo dell'accesso del giocatore eseguendo l'override di OnCompleteListener.
    • Se l'attività di accesso è andata a buon fine, recupera l'oggetto GoogleSignInAccount chiamando getResult().
    • Se l'accesso non è andato a buon fine, puoi inviare un intent di accesso per avviare un flusso di accesso interattivo. Per un elenco di listener di callback aggiuntivi che puoi utilizzare, consulta la guida per sviluppatori dell'API Tasks e il Task riferimento API.

Il seguente snippet di codice mostra come la tua app può eseguire l'accesso automatico:

private void signInSilently() {
  GoogleSignInOptions signInOptions = GoogleSignInOptions.DEFAULT_GAMES_SIGN_IN;
  GoogleSignInAccount account = GoogleSignIn.getLastSignedInAccount(this);
  if (GoogleSignIn.hasPermissions(account, signInOptions.getScopeArray())) {
    // Already signed in.
    // The signed in account is stored in the 'account' variable.
    GoogleSignInAccount signedInAccount = account;
  } else {
    // Haven't been signed-in before. Try the silent sign-in first.
    GoogleSignInClient signInClient = GoogleSignIn.getClient(this, signInOptions);
    signInClient
        .silentSignIn()
        .addOnCompleteListener(
            this,
            new OnCompleteListener<GoogleSignInAccount>() {
              @Override
              public void onComplete(@NonNull Task<GoogleSignInAccount> task) {
                if (task.isSuccessful()) {
                  // The signed in account is stored in the task's result.
                  GoogleSignInAccount signedInAccount = task.getResult();
                } else {
                  // Player will need to sign-in explicitly using via UI.
                  // See [sign-in best practices](http://developers.google.com/games/services/checklist) for guidance on how and when to implement Interactive Sign-in,
                  // and [Performing Interactive Sign-in](http://developers.google.com/games/services/android/signin#performing_interactive_sign-in) for details on how to implement
                  // Interactive Sign-in.
                }
              }
            });
  }
}

@Override
protected void onResume() {
  super.onResume();
  signInSilently();
}

Se il tentativo di accesso automatico non va a buon fine, puoi chiamare getException() per ottenere un ApiException con il codice di stato dettagliato. Un codice di stato CommonStatusCodes.SIGN_IN_REQUIRED indica che il giocatore deve intraprendere un'azione esplicita per accedere. In questo caso, l'app deve avviare un flusso di accesso interattivo come descritto nella sezione successiva.

Eseguire un accesso interattivo

Per accedere con l'interazione del giocatore, la tua app deve avviare l'intent di accesso. In caso di esito positivo, l'API Google Sign-In mostra un'interfaccia utente che chiede al giocatore di inserire le proprie credenziali per accedere. Questo approccio semplifica lo sviluppo dell'app, poiché l'attività di accesso gestisce scenari come la necessità di aggiornare Google Play Services o mostrare richieste di consenso, per conto della tua app. Il risultato viene restituito tramite il callback onActivityResult.

Per eseguire l'accesso in modo interattivo:

  1. Chiama getSigninIntent() su GoogleSignInClient per ottenere un intent di accesso, quindi chiama startActivity() e trasmetti l'intent. Il seguente snippet di codice mostra come la tua app può avviare un flusso di accesso interattivo:

    private void startSignInIntent() {
  GoogleSignInClient signInClient = GoogleSignIn.getClient(this,
      GoogleSignInOptions.DEFAULT_GAMES_SIGN_IN);
  Intent intent = signInClient.getSignInIntent();
  startActivityForResult(intent, RC_SIGN_IN);
}

  2. Nel callback onActivityResult(), gestisci il risultato dell'intent restituito.

    • Se l'accesso è riuscito, recupera l'oggetto GoogleSignInAccount da GoogleSignInResult.
    • Se l'accesso non è andato a buon fine, devi gestire l'errore di accesso (ad esempio, visualizzando un messaggio di errore in un avviso). Il seguente snippet di codice mostra come la tua app può gestire i risultati dell'accesso del giocatore:
    @Override
protected void onActivityResult(int requestCode, int resultCode, Intent data) {
  super.onActivityResult(requestCode, resultCode, data);
  if (requestCode == RC_SIGN_IN) {
    GoogleSignInResult result = Auth.GoogleSignInApi.getSignInResultFromIntent(data);
    if (result.isSuccess()) {
      // The signed in account is stored in the result.
      GoogleSignInAccount signedInAccount = result.getSignInAccount();
    } else {
      String message = result.getStatus().getStatusMessage();
      if (message == null || message.isEmpty()) {
        message = getString(R.string.signin_other_error);
      }
      new AlertDialog.Builder(this).setMessage(message)
          .setNeutralButton(android.R.string.ok, null).show();
    }
  }
}

Recuperare le informazioni del giocatore

Il GoogleSignInAccount restituito dall'API Accedi con Google non contiene informazioni sul giocatore. Se il tuo gioco utilizza informazioni sui giocatori, come il nome visualizzato e l'ID giocatore, puoi seguire questi passaggi per recuperarle.

  1. Ottieni un oggetto PlayersClient chiamando il metodo getPlayersClient() e passando GoogleSignInAccount come parametro.
  2. Utilizza i metodi PlayersClient per caricare in modo asincrono l'oggetto Player che contiene le informazioni di un giocatore. Ad esempio, puoi chiamare getCurrentPlayer() per caricare il giocatore attualmente connesso. Se l'attività restituisce un ApiException con codice di stato SIGN_IN_REQUIRED, ciò indica che il giocatore deve essere riautenticato. Per farlo, chiama GoogleSignInClient.getSignInIntent() per accedere al player in modo interattivo.
  3. Se l'attività restituisce correttamente l'oggetto Player, puoi chiamare i metodi dell'oggetto Player per recuperare i dettagli specifici del giocatore (ad esempio, getDisplayName() o getPlayerId()).

Fornire un pulsante di accesso

Per fornire un pulsante di accesso Google standard nel tuo gioco, puoi utilizzare uno di questi approcci:

Quando gli utenti fanno clic sul pulsante di accesso, il gioco deve avviare il flusso di accesso inviando un intent di accesso, come descritto in Eseguire un accesso interattivo.

Questo snippet di codice mostra come aggiungere un pulsante di accesso nel metodo onCreate() per la tua attività.

@Override
protected void onCreate(Bundle savedInstanceState) {
  super.onCreate(savedInstanceState);
  setContentView(R.layout.activity_sign_in);
  findViewById(R.id.sign_in_button).setOnClickListener(this);
  findViewById(R.id.sign_out_button).setOnClickListener(this);
}

Lo snippet di codice riportato di seguito mostra come inviare l'intent di accesso quando l'utente fa clic sul pulsante di accesso.

@Override
public void onClick(View view) {
  if (view.getId() == R.id.sign_in_button) {
    // start the asynchronous sign in flow
    startSignInIntent();
  } else if (view.getId() == R.id.sign_out_button) {
    // sign out.
    signOut();
    // show sign-in button, hide the sign-out button
    findViewById(R.id.sign_in_button).setVisibility(View.VISIBLE);
    findViewById(R.id.sign_out_button).setVisibility(View.GONE);
  }
}

Visualizzare i popup di gioco

Puoi visualizzare le visualizzazioni popup nel tuo gioco utilizzando la classe GamesClient. Ad esempio, il gioco può mostrare un popup "Bentornato" o "Obiettivi sbloccati". Per consentire ai servizi per i giochi di Google Play di avviare popup nelle visualizzazioni del tuo gioco, chiama il metodo setViewForPopups(). Puoi personalizzare ulteriormente la posizione in cui viene visualizzato il popup sullo schermo chiamando setGravityForPopups().

Disconnetti il giocatore

La disconnessione viene eseguita chiamando il metodo signOut() su GoogleSignInClient.

private void signOut() {
  GoogleSignInClient signInClient = GoogleSignIn.getClient(this,
      GoogleSignInOptions.DEFAULT_GAMES_SIGN_IN);
  signInClient.signOut().addOnCompleteListener(this,
      new OnCompleteListener<Void>() {
        @Override
        public void onComplete(@NonNull Task<Void> task) {
          // at this point, the user is signed out.
        }
      });
}