Attivare l'accesso lato server ai servizi per i giochi di Google Play

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.

Se il tuo gioco utilizza un server di backend, ti consigliamo di utilizzare Accedi con Google per autenticare i giocatori e trasferire in modo sicuro l'identità del giocatore al server di backend. In questo modo, il gioco può recuperare in modo sicuro l'identità del giocatore e altri dati senza essere esposto a potenziali manomissioni durante il passaggio attraverso il dispositivo.

In questo scenario, il gioco chiede al giocatore di accedere a Google Play Games Services come di consueto. Quando il giocatore esegue l'accesso correttamente, l'oggetto GoogleSignInAccount contiene un codice speciale monouso (chiamato codice di autenticazione del server) che il client passa al server. Dopodiché, sul server, scambia il codice di autorizzazione del server con un token OAuth 2.0 che il server può utilizzare per effettuare chiamate all'API Google Play Games Services.

Per ulteriori indicazioni sull'aggiunta dell'accesso nei tuoi giochi, consulta Accesso nei giochi per Android.

Per visualizzare un esempio di codice dettagliato che mostra come utilizzare Google Sign-In per autenticare i giocatori, consulta l'esempio clientserverskeleton su GitHub.

Per l'accesso offline sono necessari i seguenti passaggi:

  1. In Google Play Console: crea una credenziale per il tuo server di gioco. Il tipo di client OAuth delle credenziali sarà "web".
  2. Nell'app per Android: durante l'accesso, richiedi un codice di autenticazione server per le credenziali del server e passalo al server.
  3. Sul server di gioco: scambia il codice di autenticazione del server con un token di accesso OAuth utilizzando i servizi di autenticazione Google, quindi utilizzalo per chiamare le API REST dei servizi per i giochi di Play.

Prima di iniziare

Prima di poter integrare Google Sign-In nel tuo gioco, devi prima aggiungerlo in Google Play Console, come descritto in Configurazione di Google Play Games Services.

Creare un'applicazione web lato server associata per il tuo gioco

Google Play Games Services non fornisce supporto di backend per i giochi web. Tuttavia, fornisce il supporto del server di backend per il server del tuo gioco per Android.

Se vuoi utilizzare le API REST per i servizi per i giochi di Google Play nella tua app lato server, segui questi passaggi:

  1. Crea un'app web associata per il tuo gioco nella sezione App collegate di Google Play Console. Tieni presente che l'launch_url non viene utilizzato per questo flusso e può essere lasciato vuoto.
  2. Per ottenere le informazioni sulle credenziali per la tua app, segui questi passaggi:
    1. Nel tuo gioco in Google Play Console, fai clic su Dettagli gioco.
    2. Scorri verso il basso fino alla sezione Progetto della console API e fai clic sul link al progetto della console API.
    3. Nella schermata API e servizi > Credenziali della console Google API, scarica il file client_secret.json per la tua app web e salvalo in una posizione accessibile al server. Registra l'ID client della credenziale per riferimento futuro.
  3. Riavvia l'app lato server in modo che sia pronta ad accettare richieste dall'app client del tuo gioco.

Esegui l'accesso sul client

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. In GoogleSignInOptions.Builder per configurare l'accesso, devi specificare GoogleSignInOptions.DEFAULT_GAMES_SIGN_IN.
  2. Devi anche specificare che il tuo gioco richiede un codice di autenticazione per il server di backend chiamando il metodo GoogleSignInOptions.Builder.requestServerAuthCode() con l'ID client del server come parametro. Recupererai il codice di autorizzazione in un secondo momento per i token di accesso sul server di backend, come descritto in Recuperare il codice di autorizzazione del server.
  3. Chiama il metodo GoogleSignIn.getClient() e passa le opzioni che hai configurato in precedenza. Se la chiamata va a buon fine, l'API Google Sign-In restituisce un'istanza di GoogleSignInClient.
  4. Una volta ottenuta l'istanza GoogleSignInClient, devi procedere all'accesso silenzioso del giocatore dall'onResume() dell'attività, come descritto in Esecuzione dell'accesso silenzioso.

Ecco un esempio:

private static final int RC_SIGN_IN = 9001;
private GoogleSignInClient mGoogleSignInClient;

private void startSignInForAuthCode() {

  // Client ID for your backend server.
  String webClientId = getString(R.string.webclient_id);

  GoogleSignInOptions signInOption = new
      GoogleSignInOptions.Builder(GoogleSignInOptions.DEFAULT_GAMES_SIGN_IN)
      .requestServerAuthCode(webClientId)
      .build();

  GoogleSignInClient signInClient = GoogleSignIn.getClient(this, signInOption);
  Intent intent = signInClient.getSignInIntent();
  startActivityForResult(intent, RC_SIGN_IN);
}

Recuperare il codice di autorizzazione del server

Per recuperare un codice di autenticazione del server che il tuo gioco può utilizzare per i token di accesso sul server di backend, chiama il metodo getServerAuthCode() sull'oggetto GoogleSignInAccount restituito da Google Sign-In in caso di accesso riuscito del giocatore.

Ecco un esempio:

// Auth code to send to backend server.
private String mServerAuthCode;

@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()) {
      mServerAuthCode = result.getSignInAccount().getServerAuthCode();
    } 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();
    }
  }
}

Scambia il codice di autenticazione del server con un token di accesso sul server

Invia il codice di autorizzazione del server al server di backend per scambiarlo con token di accesso e aggiornamento. Utilizza il token di accesso per chiamare l'API Google Play Games Services per conto del giocatore e, facoltativamente, memorizza il token di aggiornamento per acquisire un nuovo token di accesso quando quello attuale scade.

Il seguente snippet di codice mostra come implementare il codice lato server nel linguaggio di programmazione Java per scambiare il codice di autorizzazione del server con token di accesso. Utilizza l'app di esempio clientserverskeleton:

/**
 * Exchanges the authcode for an access token credential.  The credential
 * is the associated with the given player.
 *
 * @param authCode - the non-null authcode passed from the client.
 * @param player   - the player object which the given authcode is
 *                 associated with.
 * @return the HTTP response code indicating the outcome of the exchange.
 */
private int exchangeAuthCode(String authCode, Player player) {
try {

    // The client_secret.json file is downloaded from the Google API
    // console.  This is used to identify your web application.  The
    // contents of this file should not be shared.
    //
    File secretFile = new File("client_secret.json");

    // If we don't have the file, we can't access any APIs, so return
    // an error.
    if (!secretFile.exists()) {
        log("Secret file : " + secretFile
                .getAbsolutePath() + "  does not exist!");
        return HttpServletResponse.SC_FORBIDDEN;
    }

    GoogleClientSecrets clientSecrets = GoogleClientSecrets.load(
            JacksonFactory.getDefaultInstance(), new
            FileReader(secretFile));

    // Extract the application id of the game from the client id.
    String applicationId = extractApplicationId(clientSecrets
            .getDetails().getClientId());

    GoogleTokenResponse tokenResponse =
            new GoogleAuthorizationCodeTokenRequest(
            HTTPTransport,
            JacksonFactory.getDefaultInstance(),
            "https://oauth2.googleapis.com/token",
            clientSecrets.getDetails().getClientId(),
            clientSecrets.getDetails().getClientSecret(),
            authCode,
            "")
            .execute();

    log("hasRefresh == " + (tokenResponse.getRefreshToken() != null));
    log("Exchanging authCode: " + authCode + " for token");
    Credential credential = new Credential
            .Builder(BearerToken.authorizationHeaderAccessMethod())
            .setJsonFactory(JacksonFactory.getDefaultInstance())
            .setTransport(HTTPTransport)
            .setTokenServerEncodedUrl("https://www.googleapis.com/oauth2/v4/token")
            .setClientAuthentication(new HttpExecuteInterceptor() {
                @Override
                public void intercept(HttpRequest request)
                        throws IOException {
                        }
            })
            .build()
            .setFromTokenResponse(tokenResponse);

    player.setCredential(credential);

    // Now that we have a credential, we can access the Games API.
    PlayGamesAPI api = new PlayGamesAPI(player, applicationId,
            HTTPTransport, JacksonFactory.getDefaultInstance());

    // Call the verify method, which checks that the access token has
    // access to the Games API, and that the player id used by the
    // client matches the playerId associated with the accessToken.
    boolean ok = api.verifyPlayer();

    // Call a Games API on the server.
    if (ok) {
        ok = api.updatePlayerInfo();
        if (ok) {
            // persist the player.
            savePlayer(api.getPlayer());
        }
    }

    return ok ? HttpServletResponse.SC_OK :
            HttpServletResponse.SC_INTERNAL_SERVER_ERROR;

  } catch (IOException e) {
    e.printStackTrace();
  }
  return HttpServletResponse.SC_INTERNAL_SERVER_ERROR;
}

Per scoprire di più sull'accesso alle API di Google da un server di backend per conto di un giocatore che ha eseguito l'accesso, consulta Abilitazione dell'accesso lato server.

Gestire la disconnessione del giocatore

Per disconnettere i giocatori dal tuo gioco, chiama il metodo signOut() su GoogleSignInClient. Per un esempio di snippet di codice, vedi Disconnessione del giocatore.

Chiamare le API REST dal server

Consulta le API REST per i servizi per i giochi di Google Play per una descrizione completa delle chiamate API disponibili.

Di seguito sono riportati alcuni esempi di chiamate API REST che potresti trovare utili:

Giocatore

  • Vuoi ottenere l'ID e i dati del profilo del giocatore che ha eseguito l'accesso? Chiama Players.get con 'me' come ID.

Amici

Assicurati di consultare la guida Amici, che spiega in modo più dettagliato la funzionalità Amici.

Obiettivi

Assicurati di consultare la guida agli obiettivi, che li spiega in modo più dettagliato.

  • Vuoi visualizzare un elenco degli obiettivi attuali? Puoi effettuare una chiamata a AchievementDefinitions.list.
  • Combina questa chiamata con una chiamata a Achievements.list per scoprire quali ha sbloccato il giocatore.
  • Il giocatore ha ottenuto un obiettivo? Usa Achievements.unlock per sbloccarlo.
  • Il giocatore ha fatto progressi verso un obiettivo parziale? Utilizza Achievements.increment per segnalare i progressi (e scoprire se il giocatore l'ha sbloccato).
  • Stai eseguendo il debug di un gioco non ancora in produzione? Prova a chiamare Achievements.reset o Achievements.resetAll dalle API di gestione per reimpostare gli obiettivi al loro stato originale.

Classifiche

Assicurati di consultare la guida alle classifiche, che le spiega in modo più dettagliato.

  • Vuoi ottenere un elenco di tutte le classifiche del gioco? Esegui una chiamata a Leaderboards.list.
  • Il giocatore ha finito una partita? Puoi inviare il suo punteggio a Scores.submit e scoprire se si tratta di un nuovo punteggio più alto.
  • Vuoi visualizzare una classifica? Recupera i dati da Scores.list e mostrali all'utente.
  • Utilizza Scores.listWindow per trovare un assortimento di punteggi vicini al punteggio più alto dell'utente.
  • Per ottenere maggiori informazioni sul punteggio del giocatore in una determinata classifica (ad esempio, se il giocatore si trova nel 12% dei migliori giocatori), chiama Scores.get.
  • Stai eseguendo il debug di un gioco? Prova a chiamare Scores.reset dalle API di gestione per reimpostare tutti i punteggi del giocatore in una determinata classifica.