Questa pagina è stata tradotta dall'API Cloud Translation.

Accedere ai giochi Android

Per poter accedere ai servizi per i giochi di Google Play, il tuo gioco deve fornire l'account con il quale hai eseguito l'accesso. Se il player non è autenticato, il gioco potrebbe riscontrare errori durante le chiamate alle API dei servizi per i giochi di Google Play. Questa documentazione descrive come implementare un'esperienza di accesso senza interruzioni nel tuo gioco.

Implementare l'accesso del player

La classe GoogleSignInClient è il punto di accesso principale per recuperare l'account del player a cui è stato eseguito l'accesso e per accedere al player se non l'hanno ancora fatto nella tua app sul dispositivo.

Per creare un client di accesso, procedi nel seguente modo:

Crea un client di accesso tramite l'oggetto GoogleSignInOptions, come mostrato nel seguente snippet di codice. In GoogleSignInOptions.Builder per configurare l'accesso devi specificare GoogleSignInOptions.DEFAULT_GAMES_SIGN_IN.
```
GoogleSignInOptions signInOptions = GoogleSignInOptions.DEFAULT_GAMES_SIGN_IN;
```
Se vuoi utilizzare SnapshotsClient, aggiungi .requestScopes(Games.SCOPE_GAMES_SNAPSHOTS) alla tua GoogleSignInOptions.Builder come mostrato nel seguente snippet di codice:
```
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. Con qualsiasi altro ambito, il primo accesso silenzioso non avrà esito positivo, ad eccezione degli utenti che hanno già eseguito l'accesso su un altro dispositivo.
Chiama il metodo GoogleSignIn.getClient() e trasmetti le opzioni configurate nei passaggi precedenti. Se la chiamata ha esito positivo, l'API Accedi con Google restituisce un'istanza di GoogleSignInClient.

Controllare se il player è già connesso

Puoi controllare se un account è già connesso sul dispositivo corrente utilizzando GoogleSignIn.getLastSignedInAccount() e se questo account ha già le autorizzazioni richieste concesse utilizzando GoogleSignIn.hasPermissions(). Se entrambe le condizioni sono vere, ovvero getLastSignedInAccount() restituisce un valore non null e hasPermissions() restituisce true, puoi utilizzare in sicurezza l'account restituito da getLastSignedInAccount(), anche se il dispositivo è offline.

Esecuzione dell'accesso silenzioso

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

Il metodo silentSignIn() restituisce un Task<GoogleSignInAccount>. Quando l'attività è completata, imposti il campo GoogleSignInAccount che hai dichiarato in precedenza sull'account di accesso che l'attività restituisce come risultato o su null, a indicare che non è presente un utente che ha eseguito l'accesso.

Se il tentativo di accesso non riuscito non riesce, puoi inviare facoltativamente l'intent di accesso per visualizzare un'interfaccia utente di accesso, come descritto nella sezione Esecuzione dell'accesso interattivo.

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

Per eseguire l'accesso senza notifiche, procedi nel seguente modo:

Chiama il metodo silentSignIn() su GoogleSignInClient per avviare la procedura di accesso silenzioso. Questa chiamata restituisce un oggetto Task<GoogleSignInAccount> che contiene GoogleSignInAccount se l'accesso silenzio viene eseguito correttamente.
Gestisci l'esito positivo o negativo dell'accesso del player eseguendo l'override di OnCompleteListener.
- Se l'attività di accesso è riuscita, recupera l'oggetto GoogleSignInAccount chiamando getResult().
- Se l'accesso non è riuscito, puoi inviare l'intent di accesso per avviare un flusso di accesso interattivo. Per un elenco degli ascoltatori di callback aggiuntivi che puoi utilizzare, consulta la guida per gli sviluppatori dell'API Tasks e il riferimento API Task.

Il seguente snippet di codice mostra come la tua 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. Il codice di stato CommonStatusCodes.SIGN_IN_REQUIRED indica che il player deve eseguire un'azione esplicita per l'accesso. In questo caso, l'app deve avviare un flusso di accesso interattivo come descritto nella sezione successiva.

Esecuzione dell'accesso interattivo

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

Per eseguire l'accesso in modo interattivo, procedi nel seguente modo:

Chiama getSigninIntent() sulla GoogleSignInClient per ottenere un intento di accesso, quindi chiama startActivity() e passalo. 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 è riuscito, recupera l'oggetto GoogleSignInAccount da GoogleSignInResult.
Se il risultato dell'accesso non è riuscito, dovresti gestire l'errore di accesso (ad esempio, visualizzando un messaggio di errore in un avviso). Il seguente snippet di codice mostra in che modo la tua app può gestire i risultati dell'accesso al player:

@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();
    }
  }
}

Recupero informazioni sul giocatore in corso...

La GoogleSignInAccount restituita dall'API Accedi con Google non contiene informazioni sul player. Se il gioco utilizza informazioni sul giocatore, ad esempio il nome visualizzato e l'ID, puoi seguire questi passaggi per recuperare queste informazioni.

Ottieni un oggetto PlayersClient chiamando il metodo getPlayersClient() e trasmettendo GoogleSignInAccount come parametro.
Utilizza i metodi PlayersClient per caricare in modo asincrono l'oggetto Player che contiene informazioni su un player. Ad esempio, puoi chiamare getCurrentPlayer() per caricare il player a cui hai eseguito l'accesso. Se l'attività restituisce un valore ApiException con codice di stato SIGN_IN_REQUIRED, significa che il player deve essere nuovamente autenticato. Per farlo, chiama il numero GoogleSignInClient.getSignInIntent() per accedere in modo interattivo al player.
Se l'attività restituisce correttamente l'oggetto Player, puoi chiamare i metodi dell'oggetto Player per recuperare dettagli specifici sul player (ad esempio, getDisplayName() o getPlayerId()).

Specificare un pulsante di accesso

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

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

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

Questo snippet di codice mostra come aggiungere un pulsante di accesso nel metodo onCreate() per l'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);
}

Il seguente snippet di codice 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);
  }
}

Visualizzazione dei popup del gioco

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

Disconnessione del player in corso...

Per uscire, chiama 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.
        }
      });
}