Partite salvate per i giochi Android

Questa guida mostra come implementare le 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

Per informazioni sulla funzionalità, consulta la panoramica su Giochi salvati.

Ottieni il client snapshot

Per iniziare a usare l'API Snapshot, il gioco deve prima ottenere un oggetto SnapshotsClient. Per farlo, chiama il metodo Games.getSnapshotsClient() e trasmetti l'attività.

Specifica l'ambito di Drive

L'API Snapshot si basa sull'API Google Drive per l'archiviazione dei giochi salvati. Per accedere all'API Drive, la tua app deve specificare l'ambito Drive.SCOPE_APPFOLDER durante la creazione del client Accedi con Google.

Ecco un esempio di come eseguire questa operazione con il metodo onResume() per l'attività di accesso:


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

Mostra le partite salvate

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

Una volta che i giocatori hanno selezionato l'opzione di salvataggio/ripristino nel gioco, il gioco può visualizzare in via facoltativa una schermata che chiede ai giocatori di inserire le informazioni per una nuova partita salvata o di selezionare un gioco salvato esistente da ripristinare.

Per semplificare lo sviluppo, l'API Snapshot fornisce un'interfaccia utente (UI) predefinita per la selezione dei giochi salvati che puoi utilizzare subito. L'interfaccia utente per la selezione dei giochi salvati consente ai giocatori di creare una nuova partita salvata, visualizzare i dettagli delle partite salvate esistenti e caricare i giochi salvati in precedenza.

Per avviare l'UI predefinita di Partite salvate:

  1. Chiama SnapshotsClient.getSelectSnapshotIntent() per ottenere un Intent per lanciare l'interfaccia utente predefinita per la selezione dei giochi salvati.
  2. Chiama startActivityForResult() e passalo Intent. Se la chiamata ha esito positivo, il gioco mostra l'interfaccia utente per la selezione del gioco salvato, insieme alle opzioni specificate.

Ecco un esempio di come avviare l'interfaccia utente predefinita per la selezione dei giochi salvati:

private static final int RC_SAVED_GAMES = 9009;

private void showSavedGamesUI() {
  SnapshotsClient snapshotsClient =
      PlayGames.getSnapshotsClient(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, l'interfaccia utente invia una richiesta ai servizi per i giochi di Play. Se la richiesta ha esito positivo, i servizi per i giochi di Play restituiscono informazioni per creare o ripristinare il gioco salvato tramite il callback onActivityResult(). Il gioco può sostituire questo callback per controllare 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
      // ...
    }
  }
}

Scrivi le partite salvate

Per memorizzare contenuti in una partita salvata:

  1. Apri in modo asincrono uno snapshot tramite SnapshotsClient.open().

  2. Recupera l'oggetto Snapshot dal risultato dell'attività chiamando SnapshotsClient.DataOrConflict.getData().

  3. Recupera un'istanza SnapshotContents con SnapshotsClient.SnapshotConflict.

  4. Chiama SnapshotContents.writeBytes() per archiviare i dati del player in formato byte.

  5. Dopo aver scritto tutte le modifiche, chiama SnapshotsClient.commitAndClose() per inviarle ai server di Google. Nella chiamata al metodo, il gioco può facoltativamente fornire informazioni aggiuntive per indicare ai servizi per i giochi di Play come presentare il gioco salvato ai giocatori. Queste informazioni sono rappresentate in un oggetto SnapshotMetaDataChange creato dal gioco utilizzando SnapshotMetadataChange.Builder.

Lo snippet seguente mostra in che modo il tuo gioco può eseguire il commit di 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 =
      PlayGames.getSnapshotsClient(this);

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

Se il dispositivo del giocatore non è connesso a una rete quando la tua app chiama il numero SnapshotsClient.commitAndClose(), i servizi per i giochi di Play archivia localmente i dati dei giochi salvati sul dispositivo. Alla riconnessione del dispositivo, i servizi per i giochi di Play sincronizzano le modifiche ai giochi salvate nella cache locale con i server di Google.

Carica partite salvate

Per recuperare le partite salvate per il giocatore attualmente connesso:

  1. Apri in modo asincrono uno snapshot con SnapshotsClient.open().

  2. Elimina l'oggetto Snapshot dal risultato dell'attività chiamando SnapshotsClient.DataOrConflict.getData(). In alternativa, il gioco può anche recuperare uno snapshot specifico tramite l'interfaccia utente di selezione delle partite salvate, come descritto nella sezione Visualizzazione delle partite salvate.

  3. Recupera l'istanza SnapshotContents con SnapshotsClient.SnapshotConflict.

  4. Chiama SnapshotContents.readFully() per leggere i contenuti dello snapshot.

Il seguente snippet mostra come caricare una specifica partita salvata:

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

  // Get the SnapshotsClient from the signed in account.
  SnapshotsClient snapshotsClient =
      PlayGames.getSnapshotsClient(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 di giochi salvati

Quando usi l'API Snapshot nel gioco, più dispositivi possono eseguire letture e scritture sullo stesso gioco salvato. Nel caso in cui un dispositivo perda temporaneamente la connessione di rete e successivamente si riconnetta, potrebbero verificarsi conflitti di dati in base ai quali il gioco salvato, memorizzato sul dispositivo locale di un giocatore, non è sincronizzato con la versione remota memorizzata sui server di Google.

L'API snapshot fornisce un meccanismo di risoluzione dei conflitti che presenta entrambi gli insiemi di giochi salvati in conflitto in fase di lettura e ti consente di implementare una strategia di risoluzione appropriata per il tuo gioco.

Quando i servizi per i giochi di Play rilevano un conflitto di dati, il metodo SnapshotsClient.DataOrConflict.isConflict() restituisce il valore true. In questo evento, la classe SnapshotsClient.SnapshotConflict fornisce due versioni del gioco salvato:

  • Versione server: la versione più aggiornata nota ai servizi per i giochi di Play per essere adatta al dispositivo del giocatore.

  • Versione locale: una versione modificata rilevata su uno dei dispositivi del player con contenuti o metadati in conflitto. Potrebbe non essere la stessa che hai provato a salvare.

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

Per rilevare e risolvere i conflitti di giochi salvati:

  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 SnaphotsClient.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 scaricare la versione locale.

  6. Chiama SnapshotsClient.SnapshotConflict.getSnapshot() per ottenere la versione del server.

  7. Per risolvere il conflitto di giochi salvato, seleziona una versione che vuoi salvare sul server come versione finale e passala al metodo SnapshotsClient.resolveConflict().

Lo snippet seguente mostra un esempio di come il tuo gioco potrebbe gestire un conflitto di giochi salvati selezionando il gioco salvato 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 PlayGames.getSnapshotsClient(theActivity)
      .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");
              }
            }
          });
}

Modifica le partite salvate

Se vuoi unire i dati di più giochi salvati o modificare un elemento 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. Facoltativamente, crea un'istanza SnapshotMetadataChange in caso di 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 a SnapshotsClient.resolveConflict() ha esito positivo, l'API archivia l'oggetto Snapshot nel server e tenta di aprire l'oggetto Snapshot sul dispositivo locale.