Zapisane gry na Androida

Z tego przewodnika dowiesz się, jak wdrożyć zapisane gry za pomocą interfejsu snapshots API dostępnego w usługach gier Google Play. Interfejsy API można znaleźć w pakietach com.google.android.gms.games.snapshot i com.google.android.gms.games.

Zanim zaczniesz

Więcej informacji o tej funkcji znajdziesz w artykule Omówienie zapisanych gier.

Pobranie klienta zrzutów

Aby można było zacząć korzystać z interfejsu Snaps API, gra musi najpierw uzyskać obiekt SnapshotsClient. Możesz to zrobić, wywołując metodę Games.getSnapshotsClient() i przekazując aktywność.

Określanie zakresu Dysku

Interfejs Snaps API korzysta z Google Drive API do przechowywania zapisanych gier. Aby uzyskać dostęp do interfejsu Drive API, podczas tworzenia klienta logowania przez Google aplikacja musi określić zakres Drive.SCOPE_APPFOLDER.

Oto przykład, jak można to zrobić w ramach metody onResume() w przypadku aktywności związanej z logowaniem:


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

Wyświetl zapisane gry

Możesz zintegrować interfejs Snaps API wszędzie tam, gdzie Twoja gra umożliwia graczom zapisywanie i przywracanie postępów. Twoja gra może wyświetlać taką opcję w wyznaczonych punktach zapisu/przywracania lub umożliwiać graczom zapisywanie i przywracanie postępu w dowolnym momencie.

Gdy gracze wybierzą opcję zapisania lub przywrócenia w grze, może wyświetlić się ekran z prośbą o podanie informacji o nowej zapisanej grze lub o wybranie wcześniej zapisanej gry do przywrócenia.

Aby uprościć programowanie, interfejs API zrzutów udostępnia domyślny interfejs użytkownika (UI) zapisanych gier. Interfejs wyboru zapisanych gier pozwala graczom tworzyć nowe zapisane gry, wyświetlać szczegółowe informacje o tych grach i wczytywać wcześniej zapisane gry.

Aby uruchomić domyślny interfejs zapisanych gier:

  1. Wywołaj SnapshotsClient.getSelectSnapshotIntent(), aby otrzymać Intent za uruchomienie domyślnego interfejsu wyboru zapisanych gier.
  2. Zadzwoń pod numer startActivityForResult() i przekaż go w polu Intent. Jeśli wywołanie się powiedzie, gra wyświetli interfejs zapisanego wyboru gry wraz z określonymi przez Ciebie opcjami.

Oto przykład uruchamiania domyślnego interfejsu wyboru zapisanych gier:

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

Jeśli gracz zdecyduje się utworzyć nową zapisaną grę lub wczytać istniejącą, interfejs wysyła żądanie do usług gier Play. Jeśli żądanie zostanie zrealizowane, usługi gier Play zwracają informacje potrzebne do utworzenia lub przywrócenia zapisanej gry za pomocą wywołania zwrotnego onActivityResult(). Gra może zastąpić to wywołanie zwrotne, aby sprawdzić, czy podczas żądania wystąpiły błędy.

Ten fragment kodu zawiera przykładową implementację interfejsu 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
      // ...
    }
  }
}

Zapisywanie zapisanych gier

Aby zapisać treści w zapisanej grze:

  1. Otwórz zrzut asynchronicznie za pomocą narzędzia SnapshotsClient.open().

  2. Pobierz obiekt Snapshot z wyniku zadania, wywołując SnapshotsClient.DataOrConflict.getData().

  3. Pobierz instancję SnapshotContents za pomocą SnapshotsClient.SnapshotConflict.

  4. Wywołaj SnapshotContents.writeBytes(), aby zapisać dane odtwarzacza w formacie bajtowym.

  5. Po zapisaniu wszystkich zmian wywołaj SnapshotsClient.commitAndClose(), aby wysłać zmiany na serwery Google. W wywołaniu metody gra może opcjonalnie dostarczać dodatkowe informacje, które informują usługi gier Play, jak mają zaprezentować tę zapisaną grę graczom. Informacje te są zawarte w obiekcie SnapshotMetaDataChange, który Twoja gra tworzy za pomocą SnapshotMetadataChange.Builder.

Ten fragment kodu pokazuje, jak gra może wprowadzić zmiany w zapisanej grze:

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

Jeśli urządzenie gracza nie jest połączone z siecią, gdy aplikacja wywołuje metodę SnapshotsClient.commitAndClose(), Usługi gier Play przechowują dane zapisane lokalnie na urządzeniu. Po ponownym połączeniu urządzenia usługi gier Play synchronizują zapisane lokalnie zmiany w grach z serwerami Google.

Wczytaj zapisane gry

Aby pobrać zapisane gry dla obecnie zalogowanego gracza:

  1. Otwórz zrzut asynchronicznie za pomocą narzędzia SnapshotsClient.open().

  2. Pobierz obiekt Snapshot z wyniku zadania, wywołując metodę SnapshotsClient.DataOrConflict.getData(). Może też pobierać określony zrzut przez interfejs zapisanych gier, zgodnie z opisem w sekcji Wyświetlanie zapisanych gier.

  3. Pobierz instancję SnapshotContents za pomocą SnapshotsClient.SnapshotConflict.

  4. Wywołaj SnapshotContents.readFully(), aby odczytać zawartość zrzutu.

Ten fragment kodu pokazuje, jak możesz wczytać konkretną zapisaną grę:

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.
          // ...
        }
      });
}

Rozwiąż konflikty zapisanych gier

Gdy korzystasz w grze z interfejsu Snaps API, wiele urządzeń może wykonywać odczyty i zapisy w tej samej zapisanej grze. Jeśli urządzenie tymczasowo utraci połączenie z siecią, a później ponownie się połączy, może to spowodować konflikty danych, w wyniku którego zapisana rozgrywka zapisana na urządzeniu lokalnym użytkownika nie jest zsynchronizowana ze zdalną wersją zapisaną na serwerach Google.

Interfejs API zrzutów udostępnia mechanizm rozwiązywania konfliktów, który prezentuje w czasie odczytu oba zestawy zapisanych gier będących w konflikcie i umożliwia wdrożenie strategii rozwiązywania problemów odpowiedniej dla Twojej gry.

Gdy usługi gier Play wykryje konflikt danych, metoda SnapshotsClient.DataOrConflict.isConflict() zwraca wartość true. W takim przypadku klasa SnapshotsClient.SnapshotConflict udostępnia 2 wersje zapisanej gry:

  • Wersja serwera: najnowsza wersja znana przez usługi gier Play, która odpowiada urządzeniu gracza.

  • Wersja lokalna: zmodyfikowana wersja wykryta na jednym z urządzeń odtwarzacza, która zawiera treści lub metadane powodujące konflikt. Może się ona różnić od wersji, którą chcesz zapisać.

Gra musi podjąć decyzję o tym, jak rozwiązać konflikt, wybierając jedną z udostępnionych wersji lub scalając dane z 2 zapisanych wersji.

Aby wykryć i rozwiązać problemy z zapisanymi konfliktami gier:

  1. Zadzwoń pod numer SnapshotsClient.open(). Wynik zadania zawiera klasę SnapshotsClient.DataOrConflict.

  2. Wywołaj metodę SnapshotsClient.DataOrConflict.isConflict(). Jeśli wynik jest spełniony, masz konflikt do rozwiązania.

  3. Wywołaj SnapshotsClient.DataOrConflict.getConflict(), aby pobrać instancję SnaphotsClient.snapshotConflict.

  4. Wywołaj metodę SnapshotsClient.SnapshotConflict.getConflictId(), aby pobrać identyfikator konfliktu, który jednoznacznie identyfikuje wykryty konflikt. Gra potrzebuje tej wartości, aby później wysłać prośbę o rozwiązanie konfliktu.

  5. Zadzwoń pod numer SnapshotsClient.SnapshotConflict.getConflictingSnapshot(), aby pobrać wersję lokalną.

  6. Wywołaj SnapshotsClient.SnapshotConflict.getSnapshot(), aby uzyskać wersję serwera.

  7. Aby rozwiązać ten problem, wybierz wersję, którą chcesz zapisać na serwerze jako wersję ostateczną, i przekaż ją do metody SnapshotsClient.resolveConflict().

Ten fragment kodu pokazuje, jak gra może poradzić sobie z zapisanym konfliktem, wybierając ostatnio zmodyfikowaną wersję jako ostateczną wersję do zapisania:


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

Zmienianie zapisanych gier

Jeśli chcesz scalić dane z kilku zapisanych gier lub zmodyfikować istniejącą grę Snapshot, by zapisać ją na serwerze jako ostateczną wersję, wykonaj te czynności:

  1. Zadzwoń pod numer SnapshotsClient.open().

  2. Wywołaj SnapshotsClient.SnapshotConflict.getResolutionSnapshotsContent(), aby uzyskać nowy obiekt SnapshotContents.

  3. Połącz dane z SnapshotsClient.SnapshotConflict.getConflictingSnapshot() i SnapshotsClient.SnapshotConflict.getSnapshot() z obiektem SnapshotContents z poprzedniego kroku.

  4. Opcjonalnie utwórz wystąpienie SnapshotMetadataChange, jeśli w polach metadanych zaszły jakieś zmiany.

  5. Zadzwoń pod numer SnapshotsClient.resolveConflict(). W wywołaniu metody przekaż SnapshotsClient.SnapshotConflict.getConflictId() jako pierwszy argument, a zmodyfikowane wcześniej obiekty SnapshotMetadataChange i SnapshotContents jako odpowiednio drugi i trzeci argument.

  6. Jeśli wywołanie SnapshotsClient.resolveConflict() się powiedzie, interfejs API zapisze obiekt Snapshot na serwerze i próbuje otworzyć obiekt zrzutu na urządzeniu lokalnym.