Questa pagina è stata tradotta dall'API Cloud Translation.

Accedi nei giochi Android

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 prilikom poziva na API Google Play Services. Questa documentazione descrive come implementare un'esperienza di accesso senza problemi nel tuo gioco.

Implementare l'accesso dei giocatori

La classe GoogleSignInClient è il punto di contatto principale per recuperare l'account del visualizzatore che ha eseguito l'accesso al momento e per farlo accedere se non l'ha ancora fatto sulla tua app sul dispositivo.

Per creare un client di accesso:

Crea un client di accesso tramite l'oggetto GoogleSignInOptions, come mostrato nello snippet di codice seguente. In GoogleSignInOptions.Builder per configurare l'accesso, devi specificare GoogleSignInOptions.DEFAULT_GAMES_SIGN_IN.
```
GoogleSignInOptions signInOptions = GoogleSignInOptions.DEFAULT_GAMES_SIGN_IN;
```
Se vuoi utilizzare un SnapshotsClient, aggiungi .requestScopes(Games.SCOPE_GAMES_SNAPSHOTS) al 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();
```
Attenzione: non richiedere altri ambiti o dati del profilo Google, a meno che non siano essenziali per il tuo caso d'uso. Qualsiasi altro ambito causa il fallimento del primo accesso silenzioso, ad eccezione degli utenti che hanno già eseguito l'accesso su un altro dispositivo.
Chiama il metodo GoogleSignIn.getClient() e passa le opzioni configurate nei passaggi precedenti. Se la chiamata è riuscita, l'API Accedi con Google restituisce un'istanza di GoogleSignInClient.

Controlla se l'utente ha già eseguito l'accesso

Puoi verificare se è già stato eseguito l'accesso con un account sul dispositivo corrente 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 diverso da null e hasPermissions() restituisce true, puoi utilizzare tranquillamente l'account restituito da getLastSignedInAccount(), anche se il dispositivo è offline.

Puoi chiamare silentSignIn() per recuperare l'account del giocatore che ha eseguito l'accesso al momento e provare ad accedere senza visualizzare un'interfaccia utente se ha eseguito correttamente 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 restituito dall'attività o su null per indicare che non è presente un utente che ha eseguito l'accesso.

Se il tentativo di accesso silenzioso 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, consigliamo di chiamare silentSignIn() dal metodo onResume() dell'attività.

Per eseguire l'accesso in silenzio:

Chiama il metodo silentSignIn() su GoogleSignInClient per avviare il flusso di accesso silenzioso. Questa chiamata restituisce un oggetto Task<GoogleSignInAccount> contenente un GoogleSignInAccount se l'accesso silenzioso è andato a buon fine.
Gestisci l'esito positivo o negativo dell'accesso del giocatore sostituendo 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'intenzione di accesso per avviare un flusso di accesso interattivo. Per un elenco di altri ascoltatori di callback che puoi utilizzare, consulta la guida per gli sviluppatori dell'API Tasks e il riferimento all'API Task.

Il seguente snippet di codice mostra come l'app può eseguire l'accesso silenzioso:

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 silenzioso non va a buon fine, puoi chiamare getException() per ottenere un ApiException con il codice di stato dettagliato. Un codice stato CommonStatusCodes.SIGN_IN_REQUIRED indica che il giocatore deve eseguire un'azione esplicita per accedere. In questo caso, l'app deve avviare un flusso di accesso interattivo come descritto nella sezione successiva.

Per accedere con l'interazione del giocatore, la tua app deve avviare l'intent di accesso. In caso di esito positivo, l'API di accesso con Google 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 dell'app. Il risultato viene restituito tramite il callback onActivityResult.

Per eseguire l'accesso in modo interattivo:

Chiama getSigninIntent() su GoogleSignInClient per ottenere un intent di accesso, quindi chiama startActivity() e passa 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);
}

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

Se il risultato dell'accesso è stato positivo, recupera l'oggetto GoogleSignInAccount da GoogleSignInResult.
Se il risultato dell'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 sul giocatore

Il valore GoogleSignInAccount restituito dall'API Accedi con Google non contiene informazioni sul visualizzatore. Se il tuo gioco utilizza le informazioni del giocatore, ad esempio il nome visualizzato e l'ID giocatore, puoi seguire questi passaggi per recuperarle.

Ottieni un oggetto PlayersClient chiamando il metodo getPlayersClient() e passando GoogleSignInAccount come parametro.
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 player con cui hai eseguito l'accesso. Se l'attività restituisce un ApiException con codice di stato SIGN_IN_REQUIRED, significa che è necessario autenticare nuovamente il player. Per farlo, chiama GoogleSignInClient.getSignInIntent() per accedere al player in modo interattivo.
Se l'attività restituisce correttamente l'oggetto Player, puoi chiamare i metodi dell'oggetto Player per recuperare dettagli specifici del giocatore (ad esempio, getDisplayName() o getPlayerId().

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

Includi un com.google.android.gms.common.SignInButton nel layout dell'attività principale;
Progetta un pulsante di accesso personalizzato in base alle linee guida per il branding di Accedi con Google.

Quando gli utenti fanno clic sul pulsante di accesso, il gioco deve avviare il flusso di accesso inviando un intento 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'intenzione 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);
  }
}

Mostrare popup di partite

Puoi visualizzare le visualizzazioni popup nel tuo gioco utilizzando la classe GamesClient. Ad esempio, il tuo gioco può mostrare un popup "Ti diamo il benvenuto di nuovo" 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 del popup sullo schermo chiamando setGravityForPopups().

Uscire dal player

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