Supporto dei giochi salvati 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.

Questa guida mostra come implementare la funzionalità Partite salvate utilizzando l'API snapshot fornita dai servizi per i giochi di Google Play. Le API sono disponibili nei pacchetti com.google.android.gms.games.snapshot e com.google.android.gms.games.

Prima di iniziare

Se non l'hai ancora fatto, potrebbe esserti utile esaminare i concetti di gioco di Saved Games.

Scaricare il client di snapshot

Per iniziare a utilizzare l'API snapshot, il tuo gioco deve prima ottenere un oggetto SnapshotsClient. Per farlo, chiama il metodo Games.getSnapshotsClient() e passa l'attività e l'GoogleSignInAccount per il giocatore attuale. Per scoprire come recuperare le informazioni dell'account giocatore, consulta la sezione Accesso nei giochi per Android.

Specifica l'ambito di Drive

L'API Snapshot si basa sull'API Google Drive per l'archiviazione delle partite salvate. Per accedere all'API Drive, la tua app deve specificare l'ambito Drive.SCOPE_APPFOLDER quando crei il client di accesso con Google.

Ecco un esempio di come farlo nel metodo onResume() per la tua attività di accesso:

private GoogleSignInClient mGoogleSignInClient;

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

private void signInSilently() {
  GoogleSignInOptions signInOption =
      new GoogleSignInOptions.Builder(GoogleSignInOptions.DEFAULT_GAMES_SIGN_IN)
          // Add the APPFOLDER scope for Snapshot support.
          .requestScopes(Drive.SCOPE_APPFOLDER)
          .build();

  GoogleSignInClient signInClient = GoogleSignIn.getClient(this, signInOption);
  signInClient.silentSignIn().addOnCompleteListener(this,
      new OnCompleteListener<GoogleSignInAccount>() {
        @Override
        public void onComplete(@NonNull Task<GoogleSignInAccount> task) {
          if (task.isSuccessful()) {
            onConnected(task.getResult());
          } else {
            // Player will need to sign-in explicitly using via UI
          }
        }
      });
}

Visualizzare le partite salvate

Puoi integrare l'API Snapshot ovunque il tuo gioco offra ai giocatori la possibilità di salvare o ripristinare i progressi. Il tuo gioco potrebbe mostrare un'opzione di questo tipo in punti di salvataggio/ripristino designati o consentire ai giocatori di salvare o ripristinare i progressi in qualsiasi momento.

Una volta che i giocatori selezionano l'opzione di salvataggio/ripristino nel tuo gioco, quest'ultimo può facoltativamente visualizzare una schermata che chiede ai giocatori di inserire le informazioni per una nuova partita salvata o di selezionare una partita salvata esistente da ripristinare.

Per semplificare lo sviluppo, l'API Snapshots fornisce un'interfaccia utente (UI) di selezione predefinita delle partite salvate che puoi utilizzare immediatamente. L'interfaccia utente di selezione delle partite salvate consente ai giocatori di creare una nuova partita salvata, visualizzare i dettagli delle partite salvate esistenti e caricare le partite salvate precedenti.

Per avviare l'interfaccia utente predefinita delle Partite salvate:

  1. Chiama SnapshotsClient.getSelectSnapshotIntent() per ottenere un Intent per avviare l'interfaccia utente di selezione dei giochi salvati predefinita.
  2. Chiama startActivityForResult() e inserisci Intent. Se la chiamata ha esito positivo, il gioco mostra l'interfaccia utente di selezione delle partite salvate, insieme alle opzioni specificate.

Ecco un esempio di come avviare l'UI di selezione delle partite salvate predefinite:

private static final int RC_SAVED_GAMES = 9009;

private void showSavedGamesUI() {
  SnapshotsClient snapshotsClient =
      Games.getSnapshotsClient(this, GoogleSignIn.getLastSignedInAccount(this));
  int maxNumberOfSavedGamesToShow = 5;

  Task<Intent> intentTask = snapshotsClient.getSelectSnapshotIntent(
      "See My Saves", true, true, maxNumberOfSavedGamesToShow);

  intentTask.addOnSuccessListener(new OnSuccessListener<Intent>() {
    @Override
    public void onSuccess(Intent intent) {
      startActivityForResult(intent, RC_SAVED_GAMES);
    }
  });
}

Se il giocatore sceglie di creare una nuova partita salvata o di caricarne una esistente, la UI invia una richiesta a Google Play Games Services. Se la richiesta ha esito positivo, Google Play Games Services restituisce le informazioni per creare o ripristinare la partita salvata tramite il callback onActivityResult(). Il gioco può eseguire l'override di questo callback per verificare se si sono verificati errori durante la richiesta.

Il seguente snippet di codice mostra un'implementazione di esempio di onActivityResult():

private String mCurrentSaveName = "snapshotTemp";

/**
 * This callback will be triggered after you call startActivityForResult from the
 * showSavedGamesUI method.
 */
@Override
protected void onActivityResult(int requestCode, int resultCode,
                                Intent intent) {
  if (intent != null) {
    if (intent.hasExtra(SnapshotsClient.EXTRA_SNAPSHOT_METADATA)) {
      // Load a snapshot.
      SnapshotMetadata snapshotMetadata =
          intent.getParcelableExtra(SnapshotsClient.EXTRA_SNAPSHOT_METADATA);
      mCurrentSaveName = snapshotMetadata.getUniqueName();

      // Load the game data from the Snapshot
      // ...
    } else if (intent.hasExtra(SnapshotsClient.EXTRA_SNAPSHOT_NEW)) {
      // Create a new snapshot named with a unique string
      String unique = new BigInteger(281, new Random()).toString(13);
      mCurrentSaveName = "snapshotTemp-" + unique;

      // Create the new snapshot
      // ...
    }
  }
}

Scrivere le partite salvate

Per memorizzare i contenuti in una partita salvata:

  1. Apri in modo asincrono uno snapshot tramite SnapshotsClient.open(). Quindi, recupera l'oggetto Snapshot dal risultato dell'attività chiamando SnapshotsClient.DataOrConflict.getData().
  2. Recupera un'istanza SnapshotContents tramite SnapshotsClient.SnapshotConflict.
  3. Chiama SnapshotContents.writeBytes() per archiviare i dati del giocatore in formato byte.
  4. Una volta scritte tutte le modifiche, chiama SnapshotsClient.commitAndClose() per inviarle ai server di Google. Nella chiamata al metodo, il tuo gioco può fornire facoltativamente informazioni aggiuntive per indicare a Google Play Games Services come presentare questa partita salvata ai giocatori. Queste informazioni sono rappresentate in un oggetto SnapshotMetaDataChange, che il tuo gioco crea utilizzando SnapshotMetadataChange.Builder.

Il seguente snippet mostra come il tuo gioco potrebbe eseguire il commit delle modifiche a una partita salvata:

private Task<SnapshotMetadata> writeSnapshot(Snapshot snapshot,
                                             byte[] data, Bitmap coverImage, String desc) {

  // Set the data payload for the snapshot
  snapshot.getSnapshotContents().writeBytes(data);

  // Create the change operation
  SnapshotMetadataChange metadataChange = new SnapshotMetadataChange.Builder()
      .setCoverImage(coverImage)
      .setDescription(desc)
      .build();

  SnapshotsClient snapshotsClient =
      Games.getSnapshotsClient(this, GoogleSignIn.getLastSignedInAccount(this));

  // Commit the operation
  return snapshotsClient.commitAndClose(snapshot, metadataChange);
}

Se il dispositivo del giocatore non è connesso a una rete quando la tua app chiama SnapshotsClient.commitAndClose(), Google Play Games Services memorizza i dati di gioco salvati localmente sul dispositivo. Una volta riconnesso il dispositivo, i servizi per i giochi di Google Play sincronizzano le modifiche alla partita salvata memorizzata nella cache locale con i server di Google.

Caricare le partite salvate

Per recuperare le partite salvate per il giocatore attualmente connesso:

  1. Apri in modo asincrono uno snapshot tramite SnapshotsClient.open(). Quindi, recupera l'oggetto Snapshot dal risultato dell'attività chiamando SnapshotsClient.DataOrConflict.getData(). In alternativa, il tuo gioco può recuperare uno snapshot specifico anche tramite l'interfaccia utente di selezione delle partite salvate, come descritto in Visualizzare le partite salvate.
  2. Recupera l'istanza SnapshotContents tramite SnapshotsClient.SnapshotConflict.
  3. Chiama SnapshotContents.readFully() per leggere i contenuti dello snapshot.

Il seguente snippet mostra come caricare una partita salvata specifica:

Task<byte[]> loadSnapshot() {
  // Display a progress dialog
  // ...

  // Get the SnapshotsClient from the signed in account.
  SnapshotsClient snapshotsClient =
      Games.getSnapshotsClient(this, GoogleSignIn.getLastSignedInAccount(this));

  // In the case of a conflict, the most recently modified version of this snapshot will be used.
  int conflictResolutionPolicy = SnapshotsClient.RESOLUTION_POLICY_MOST_RECENTLY_MODIFIED;

  // Open the saved game using its name.
  return snapshotsClient.open(mCurrentSaveName, true, conflictResolutionPolicy)
      .addOnFailureListener(new OnFailureListener() {
        @Override
        public void onFailure(@NonNull Exception e) {
          Log.e(TAG, "Error while opening Snapshot.", e);
        }
      }).continueWith(new Continuation<SnapshotsClient.DataOrConflict<Snapshot>, byte[]>() {
        @Override
        public byte[] then(@NonNull Task<SnapshotsClient.DataOrConflict<Snapshot>> task) throws Exception {
          Snapshot snapshot = task.getResult().getData();

          // Opening the snapshot was a success and any conflicts have been resolved.
          try {
            // Extract the raw data from the snapshot.
            return snapshot.getSnapshotContents().readFully();
          } catch (IOException e) {
            Log.e(TAG, "Error while reading Snapshot.", e);
          }

          return null;
        }
      }).addOnCompleteListener(new OnCompleteListener<byte[]>() {
        @Override
        public void onComplete(@NonNull Task<byte[]> task) {
          // Dismiss progress dialog and reflect the changes in the UI when complete.
          // ...
        }
      });
}

Gestire i conflitti dei giochi salvati

Quando utilizzi l'API Snapshot nel tuo gioco, è possibile che più dispositivi eseguano letture e scritture sulla stessa partita salvata. Nel caso in cui un dispositivo perda temporaneamente la connessione di rete e si ricolleghi in un secondo momento, ciò potrebbe causare conflitti di dati per cui la partita salvata memorizzata sul dispositivo locale di un giocatore non è sincronizzata con la versione remota memorizzata sui server di Google.

L'API Snapshot fornisce un meccanismo di risoluzione dei conflitti che presenta entrambi i set di partite salvate in conflitto al momento della lettura e ti consente di implementare una strategia di risoluzione adatta al tuo gioco.

Quando Google Play Giochi rileva un conflitto di dati, il metodo SnapshotsClient.DataOrConflict.isConflict() restituisce il valore true. In questo caso, la classe SnapshotsClient.SnapshotConflict fornisce due versioni del gioco salvato:

  • Versione server: la versione più aggiornata nota a Google Play Games Services per essere accurata per il dispositivo del giocatore.
  • Versione locale: una versione modificata rilevata su uno dei dispositivi del giocatore che contiene contenuti o metadati in conflitto. Potrebbe non coincidere con la versione che hai tentato di salvare.

Il gioco deve decidere come risolvere il conflitto scegliendo una delle versioni fornite o unendo i dati delle due versioni del gioco salvato.

Per rilevare e risolvere i conflitti delle partite salvate:

  1. Chiama il numero SnapshotsClient.open(). Il risultato dell'attività contiene una classe SnapshotsClient.DataOrConflict.
  2. Chiama il metodo SnapshotsClient.DataOrConflict.isConflict(). Se il risultato è vero, devi risolvere un conflitto.
  3. Chiama SnapshotsClient.DataOrConflict.getConflict() per recuperare un'istanza SnapshotsClient.snapshotConflict.
  4. Chiama SnapshotsClient.SnapshotConflict.getConflictId() per recuperare l'ID conflitto che identifica in modo univoco il conflitto rilevato. Il gioco ha bisogno di questo valore per inviare una richiesta di risoluzione dei conflitti in un secondo momento.
  5. Chiama il numero SnapshotsClient.SnapshotConflict.getConflictingSnapshot() per ottenere la versione locale.
  6. Chiama il numero SnapshotsClient.SnapshotConflict.getSnapshot() per ottenere la versione del server.
  7. Per risolvere il conflitto relativo al salvataggio, seleziona una versione da salvare sul server come versione finale e passala al metodo SnapshotsClient.resolveConflict().

Il seguente snippet mostra un esempio di come il gioco potrebbe gestire un conflitto di salvataggio selezionando il salvataggio modificato più di recente come versione finale da salvare:

private static final int MAX_SNAPSHOT_RESOLVE_RETRIES = 10;

Task<Snapshot> processSnapshotOpenResult(SnapshotsClient.DataOrConflict<Snapshot> result,
                                         final int retryCount) {

  if (!result.isConflict()) {
    // There was no conflict, so return the result of the source.
    TaskCompletionSource<Snapshot> source = new TaskCompletionSource<>();
    source.setResult(result.getData());
    return source.getTask();
  }

  // There was a conflict.  Try resolving it by selecting the newest of the conflicting snapshots.
  // This is the same as using RESOLUTION_POLICY_MOST_RECENTLY_MODIFIED as a conflict resolution
  // policy, but we are implementing it as an example of a manual resolution.
  // One option is to present a UI to the user to choose which snapshot to resolve.
  SnapshotsClient.SnapshotConflict conflict = result.getConflict();

  Snapshot snapshot = conflict.getSnapshot();
  Snapshot conflictSnapshot = conflict.getConflictingSnapshot();

  // Resolve between conflicts by selecting the newest of the conflicting snapshots.
  Snapshot resolvedSnapshot = snapshot;

  if (snapshot.getMetadata().getLastModifiedTimestamp() <
      conflictSnapshot.getMetadata().getLastModifiedTimestamp()) {
    resolvedSnapshot = conflictSnapshot;
  }

  return Games.getSnapshotsClient(theActivity, GoogleSignIn.getLastSignedInAccount(this))
      .resolveConflict(conflict.getConflictId(), resolvedSnapshot)
      .continueWithTask(
          new Continuation<
              SnapshotsClient.DataOrConflict<Snapshot>,
              Task<Snapshot>>() {
            @Override
            public Task<Snapshot> then(
                @NonNull Task<SnapshotsClient.DataOrConflict<Snapshot>> task)
                throws Exception {
              // Resolving the conflict may cause another conflict,
              // so recurse and try another resolution.
              if (retryCount < MAX_SNAPSHOT_RESOLVE_RETRIES) {
                return processSnapshotOpenResult(task.getResult(), retryCount + 1);
              } else {
                throw new Exception("Could not resolve snapshot conflicts");
              }
            }
          });
}

Modificare i giochi salvati per la risoluzione dei conflitti

Se vuoi unire i dati di più partite salvate o modificare un Snapshot esistente per salvarlo sul server come versione finale risolta, segui questi passaggi:

  1. Chiama il numero SnapshotsClient.open() .
  2. Chiama SnapshotsClient.SnapshotConflict.getResolutionSnapshotsContent() per ottenere un nuovo oggetto SnapshotContents.
  3. Unisci i dati di SnapshotsClient.SnapshotConflict.getConflictingSnapshot() e SnapshotsClient.SnapshotConflict.getSnapshot() nell'oggetto SnapshotContents del passaggio precedente.
  4. Se vuoi, crea un'istanza SnapshotMetadataChange se sono state apportate modifiche ai campi dei metadati.
  5. Chiama il numero SnapshotsClient.resolveConflict(). Nella chiamata al metodo, passa SnapshotsClient.SnapshotConflict.getConflictId() come primo argomento e gli oggetti SnapshotMetadataChange e SnapshotContents che hai modificato in precedenza come secondo e terzo argomento rispettivamente.
  6. Se la chiamata SnapshotsClient.resolveConflict() ha esito positivo, l'API memorizza l'oggetto Snapshot sul server e tenta di aprire l'oggetto Snapshot sul tuo dispositivo locale.