Assistenza per le Partite salvate nei giochi Android

Questa guida mostra come implementare il gioco delle partite salvate utilizzando lo l'API snapshot fornita dai servizi per i giochi di Google Play. Le API sono disponibili nella com.google.android.gms.games.snapshot e com.google.android.gms.games pacchetti.

Prima di iniziare

Se non l'hai ancora fatto, potrebbe essere utile consultare il Concetti sui giochi salvati dei giochi.

recupera il client snapshot

Per iniziare a utilizzare l'API Snapshot, il gioco deve prima ottenere un SnapshotsClient. A questo scopo, puoi richiamare Games.getSnapshotsClient() e trasferire il valore e l'attività GoogleSignInAccount del player corrente. Per scoprire come recuperare i dati dell'account giocatore, controlla Accedi in Giochi Android.

Specifica l'ambito di Drive

L'API Snapshot si basa sull'API Google Drive per lo spazio di archiviazione dei giochi salvati. A accedere all'API Drive, l'app deve specificare Drive.SCOPE_APPFOLDER durante la creazione del client di accesso con Google.

Ecco un esempio di come farlo nella onResume() metodo 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
          }
        }
      });
}

Visualizzazione delle partite salvate

Puoi integrare l'API Snapshot ovunque il tuo gioco fornisca ai giocatori l'opzione per salvare o ripristinare l'avanzamento. Sul tuo gioco potrebbe essere visualizzata la l'opzione corrispondente ai punti di salvataggio/ripristino designati o consenti ai giocatori di salvare o ripristinare progressi in qualsiasi momento.

Quando i giocatori selezionano l'opzione di salvataggio/ripristino all'interno del gioco, il gioco può facoltativamente, viene visualizzata una schermata che chiede ai giocatori di inserire informazioni per un nuovo partita o per selezionarne una esistente da ripristinare.

Per semplificare lo sviluppo, l'API Snapshot fornisce un utente che può selezionare le partite salvate che puoi usare subito. L'interfaccia utente per la selezione delle partite salvate consente creare una nuova partita salvata, visualizzare i dettagli delle partite salvate esistenti e caricare quelle salvate precedenti.

Per avviare l'interfaccia utente predefinita Partite salvate:

  1. Chiama il numero SnapshotsClient.getSelectSnapshotIntent() per ricevere un Intent per lanciare l'app predefinita UI per la selezione delle partite salvate.
  2. Chiama il numero startActivityForResult() e passiamo Intent. Se la chiamata ha esito positivo, il gioco mostra l'UI di selezione delle partite salvate, insieme con le opzioni che hai specificato.

Ecco un esempio di come avviare l'interfaccia utente di selezione delle partite salvate predefinita:

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 caricarne una esistente, l'interfaccia utente invia una richiesta ai servizi per i giochi di Google Play. Se la richiesta ha esito positivo, I servizi per i giochi di Google Play restituiscono informazioni per creare o ripristinare la partita salvata tramite onActivityResult() di Google. Il tuo gioco può ignorare questo callback per verificare se si sono verificati errori durante la richiesta.

Il seguente snippet di codice mostra un'implementazione di esempio 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
      // ...
    }
  }
}

Scrittura di partite salvate

Per memorizzare contenuti in una partita salvata:

  1. Apri uno snapshot in modo asincrono 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 player in formato byte.
  4. Una volta scritte tutte le modifiche, richiama SnapshotsClient.commitAndClose() per inviare le modifiche ai server di Google. Nella chiamata al metodo, il gioco può facoltativamente fornire informazioni aggiuntive per indicare ai servizi per i giochi di Google Play come per presentare questa partita salvata ai giocatori. Queste informazioni sono rappresentate in un SnapshotMetaDataChange creato dal tuo gioco usando SnapshotMetadataChange.Builder.

Il seguente snippet mostra in che modo il tuo gioco potrebbe applicare 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 player non è connesso a una rete quando l'app chiama SnapshotsClient.commitAndClose(), i servizi per i giochi di Google Play archiviano i dati dei giochi salvati localmente su del dispositivo. Al momento della riconnessione del dispositivo, i servizi per i giochi di Google Play sincronizzano la partita salvata memorizzata nella cache locale modifiche ai server di Google.

Caricamento delle partite salvate in corso...

Per recuperare le partite salvate per il giocatore che ha eseguito l'accesso al momento:

  1. Apri uno snapshot in modo asincrono tramite SnapshotsClient.open(). Quindi, recupera l'oggetto Snapshot. dal risultato dell'attività chiamando SnapshotsClient.DataOrConflict.getData(). In alternativa, gioco può anche recuperare un'istantanea specifica tramite l'interfaccia utente di selezione delle partite salvate, come descritto in Visualizzazione delle 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 specifica partita salvata:

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 delle partite salvate

Quando utilizzi l'API Snapshot nel tuo gioco, è possibile che dispositivi per eseguire operazioni di lettura e scrittura sulla stessa partita salvata. Nel caso in cui il dispositivo perde temporaneamente la connessione di rete e successivamente si riconnette, Causa conflitti di dati per cui la partita salvata memorizzata sul dispositivo locale di un giocatore non è sincronizzato con la versione remota memorizzata nei server di Google.

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

Quando i servizi per i giochi di Google Play rileva un conflitto di dati, Il metodo SnapshotsClient.DataOrConflict.isConflict() restituisce il valore true. In questo evento, il metodo Il corso SnapshotsClient.SnapshotConflict fornisce due versioni della partita salvata:

  • Versione server: la versione più aggiornata nota ai servizi per i giochi di Google Play per garantire la massima accuratezza per il dispositivo del giocatore; e
  • Versione locale: una versione modificata rilevata su uno dei dispositivi del player che contiene contenuti o metadati in conflitto. Potrebbe non essere la versione che hai provato a salvare.

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

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, hai un conflitto da risolvere.
  3. Chiama il numero SnapshotsClient.DataOrConflict.getConflict() per recuperare un SnaphotsClient.snapshotConflict.
  4. Chiama SnapshotsClient.SnapshotConflict.getConflictId() per recuperare l'ID conflitto che ha in modo univoco identifica il conflitto rilevato. Il gioco richiede questo valore per inviare una richiesta di risoluzione dei conflitti in un secondo momento.
  5. Chiama SnapshotsClient.SnapshotConflict.getConflictingSnapshot() per ricevere la versione locale.
  6. Chiama SnapshotsClient.SnapshotConflict.getSnapshot() per ottenere la versione del server.
  7. Per risolvere il conflitto di partite salvate, seleziona una versione che vuoi salvare sul server come alla versione finale e passarla al metodo SnapshotsClient.resolveConflict().

Il seguente snippet mostra un esempio di come il tuo gioco potrebbe gestire un conflitto di partite salvate selezionando la partita salvata modificata 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");
              }
            }
          });
}

Modifica delle partite salvate per la risoluzione dei conflitti

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

  1. Chiama il numero SnapshotsClient.open() .
  2. Chiama il numero SnapshotsClient.SnapshotConflict.getResolutionSnapshotsContent() per riceverne uno nuovo SnapshotContents.
  3. Unisci i dati di SnapshotsClient.SnapshotConflict.getConflictingSnapshot() e SnapshotsClient.SnapshotConflict.getSnapshot() nell'oggetto SnapshotContents dalla passaggio precedente.
  4. Facoltativamente, crea un'istanza SnapshotMetadataChange in caso di modifiche ai metadati. campi.
  5. Chiama il numero SnapshotsClient.resolveConflict(). Nella chiamata al metodo, SnapshotsClient.SnapshotConflict.getConflictId() come primo argomento e la Gli oggetti SnapshotMetadataChange e SnapshotContents che hai modificato in precedenza come secondo e il terzo argomento.
  6. Se la chiamata a SnapshotsClient.resolveConflict() ha esito positivo, l'API archivia il Snapshot al server e tenta di aprire l'oggetto Snapshot sul tuo dispositivo locale.