Obsługa zapisanych gier w grach na Androida

Z tego przewodnika dowiesz się, jak zaimplementować zapisane gry za pomocą interfejs API migawki dostępny w usługach gier Google Play. Interfejsy API można znaleźć w com.google.android.gms.games.snapshot i com.google.android.gms.games pakietów.

Zanim zaczniesz

W razie potrzeby zapoznaj się z Zapisane gry.

Uzyskiwanie klienta zrzutów

Aby zacząć korzystać z interfejsu API zrzutów, Twoja gra musi najpierw uzyskać SnapshotsClient. Aby to zrobić, wywołaj metodę Games.getSnapshotsClient() i przekazywanie funkcji działania.

Określanie zakresu Dysku

W przypadku miejsca na zapisane gry interfejs API zrzutów korzysta z interfejsu Google Drive API. Do uzyskuje dostęp do interfejsu Drive API, aplikacja musi określić Drive.SCOPE_APPFOLDER podczas tworzenia klienta logowania Google.

Oto przykład, jak to zrobić w onResume() metody logowania:

@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 OnCompleteListenerG<oogleSignInAccount(>) {
        @Override
        public void onComplete(@NonNull TaskG<oogleSignInAccount >task) {
          if (task.isSuccessful()) {
            onConnected(task.getResult());
          } else {
            // Player will need to sign-in explicitly using via UI
          }
        }
      });
}

Wyświetlam zapisane gry

Interfejs API zrzutów można zintegrować wszędzie tam, gdzie Twoja gra zapewnia graczom zapisać lub przywrócić postępy. Twoja gra może wyświetlać takie w wyznaczonych punktach zapisu/przywracania lub umożliwiać graczom w dowolnym momencie.

Gdy gracze wybiorą w grze opcję zapisywania/przywracania gry, gra może opcjonalnie wyświetlić ekran z prośbą o podanie informacji dla nowego zapisanego grę lub wybierz zapisaną grę, którą chcesz przywrócić.

Aby uprościć programowanie, interfejs Snaps API umożliwia domyślne wybieranie zapisanych gier interfejsu (UI), z którego można korzystać od razu. Interfejs wyboru zapisanych gier pozwala graczom: tworzyć nowe zapisane gry, wyświetlać szczegółowe informacje o istniejących grach i wczytywać wcześniej zapisane gry.

Aby uruchomić domyślny interfejs Zapisane gry:

  1. Zadzwoń pod numer SnapshotsClient.getSelectSnapshotIntent(), aby otrzymać Intent za uruchomienie domyślnego Interfejs wyboru zapisanych gier.
  2. Zadzwoń pod numer startActivityForResult() i przekazać ten Intent. Jeśli wywołanie się powiedzie, gra wyświetli interfejs wyboru zapisanej gry, wybierając określone opcje.

Ten przykład pokazuje, jak uruchomić domyślny interfejs 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 Google Play. Jeśli żądanie zostanie zrealizowane, Usługi gier Google Play zwracają informacje, aby utworzyć lub przywrócić zapisaną grę onActivityResult() oddzwanianie. Gra może zastąpić to wywołanie zwrotne, by sprawdzić, czy podczas żądania nie wystąpiły jakieś błędy.

Fragment kodu poniżej zawiera przykładową implementację 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
      // ...
    }
  }
}

Tworzenie zapisanych gier

Aby zapisać treści w zapisanej grze:

  1. Asynchronicznie otwórz zrzut w narzędziu SnapshotsClient.open(). Następnie pobierz obiekt Snapshot. na podstawie wyniku zadania, wywołując funkcję SnapshotsClient.DataOrConflict.getData().
  2. Pobierz instancję SnapshotContents przez SnapshotsClient.SnapshotConflict.
  3. Wywołaj SnapshotContents.writeBytes(), by zapisać dane odtwarzacza w formacie bajtowym.
  4. Po zapisaniu wszystkich zmian wywołaj polecenie SnapshotsClient.commitAndClose(), aby wysłać zmiany na serwery Google. W wywołaniu metody gra może opcjonalnie udostępniać dodatkowe informacje, by poinformować usługi gier Google Play, jak pokazać graczom tę zapisaną grę. Te informacje znajdują się w: SnapshotMetaDataChange który jest tworzony przez grę za pomocą SnapshotMetadataChange.Builder.

Ten fragment kodu pokazuje, w jaki sposób Twoja gra może wprowadzać 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 odtwarzacza nie jest połączone z siecią, gdy aplikacja wywołuje SnapshotsClient.commitAndClose(), Usługi gier Google Play przechowują zapisane dane gier lokalnie urządzenia. Po ponownym połączeniu z urządzeniem Usługi gier Google Play synchronizują grę zapisaną lokalnie w pamięci podręcznej zmiany na serwerach Google.

Wczytuję zapisane gry

Aby pobrać zapisane gry dla aktualnie zalogowanego gracza:

  1. Asynchronicznie otwórz zrzut w narzędziu SnapshotsClient.open(). Następnie pobierz obiekt Snapshot. na podstawie wyniku zadania, wywołując funkcję SnapshotsClient.DataOrConflict.getData(). Ewentualnie gra może też pobrać określony zrzut za pomocą interfejsu wyboru zapisanych gier, jak opisano w Wyświetlanie zapisanych gier
  2. Pobierz instancję SnapshotContents przez SnapshotsClient.SnapshotConflict.
  3. 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.
          // ...
        }
      });
}

Radzenie sobie z zapisanymi konfliktami gier

Podczas korzystania z interfejsu zrzutów ekranu w grze może się zdarzyć, urządzeń do wykonywania i odczytywania i zapisów w tej samej zapisanej grze. W przypadku, gdy urządzenie tymczasowo utraci połączenie z siecią, a następnie ponownie się połączy, powodują konflikty danych, gdy zapisana gra jest przechowywana na lokalnym urządzeniu gracza nie jest zsynchronizowany ze zdalną wersją zapisaną na serwerach Google.

Interfejs API zrzutów oferuje mechanizm rozwiązywania konfliktów, który przedstawia zestawy zapisanych gier będących w konflikcie w czasie odczytu i pozwala na wdrożenie rozwiązania; która najlepiej pasuje do Twojej gry.

Gdy Usługi gier Google Play wykryją konflikt danych, Metoda SnapshotsClient.DataOrConflict.isConflict() zwraca wartość true. W tym zdarzeniu funkcja Zajęcia SnapshotsClient.SnapshotConflict udostępniają 2 wersje zapisanej gry:

  • Wersja serwera: najnowsza wersja, według której Usługi gier Google Play są poprawne. na urządzeniu gracza; oraz
  • Wersja lokalna: zmodyfikowana wersja wykryta na jednym z urządzeń gracza, która zawiera sprzecznych treści lub metadanych. Może się ona różnić od wersji, którą próbujesz zapisać.

Gra musi zdecydować, jak rozwiązać konflikt, wybierając jedną z przesłane wersje lub scalanie danych dwóch zapisanych wersji gry.

Aby wykrywać i rozwiązywać zapisane konflikty gier:

  1. Zadzwoń pod numer SnapshotsClient.open(). Wynik zadania zawiera klasę SnapshotsClient.DataOrConflict.
  2. Wywołaj metodę SnapshotsClient.DataOrConflict.isConflict(). Jeśli wynik jest prawdziwy, do rozwiązania.
  3. Wywołaj SnapshotsClient.DataOrConflict.getConflict(), aby pobrać SnaphotsClient.snapshotConflict instancję.
  4. Wywołaj SnapshotsClient.SnapshotConflict.getConflictId(), aby pobrać niepowtarzalny identyfikator konfliktu identyfikuje wykryty konflikt. Twoja gra potrzebuje tej wartości, aby wysłać żądanie rozwiązania konfliktu później.
  5. Zadzwoń pod numer SnapshotsClient.SnapshotConflict.getConflictingSnapshot(), aby pobrać wersję lokalną.
  6. Wywołaj SnapshotsClient.SnapshotConflict.getSnapshot(), aby pobrać wersję serwera.
  7. Aby rozwiązać konflikt zapisanych gier, wybierz wersję, którą chcesz zapisać na serwerze jako plik w wersji ostatecznej i przekazać ją do metody SnapshotsClient.resolveConflict().

Ten fragment kodu i przykład pokazuje, jak Twoja gra może poradzić sobie z zapisanym konfliktem gry przez wybierając ostatnio zmodyfikowaną zapisaną grę jako ostateczną wersję do zapisania:

private static final int MAX_SNAPSHOT_RESOLVE_RETRIES = 10;

TaskS<napshot >processSnapshotOpenResult(SnapshotsClient.DataOrConflictS<napshot >result,
                                         final int retryCount) {

  if (!result.isConflict()) {
    // There was no conflict, so return the result of the source.
    TaskCompletionSourceS<napshot >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.DataOrConflictS<napshot,>
              TaskS<napshot(>>) {
            @Override
            public TaskS<napshot >then(
                @NonNull TaskS<napshotsClient.DataOrConflictS<napshot >>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(C"ould not resolve snapshot conflicts)";
              }
            }
          });
}

Modyfikowanie zapisanych gier pod kątem rozwiązywania konfliktów

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

  1. Zadzwoń pod numer SnapshotsClient.open() .
  2. Zadzwoń pod numer SnapshotsClient.SnapshotConflict.getResolutionSnapshotsContent(), aby otrzymać nowy SnapshotContents.
  3. Scal dane z SnapshotsClient.SnapshotConflict.getConflictingSnapshot() oraz SnapshotsClient.SnapshotConflict.getSnapshot() do obiektu SnapshotContents z poprzedniego kroku.
  4. Opcjonalnie utwórz instancję SnapshotMetadataChange, jeśli nastąpią zmiany w metadanych. .
  5. Zadzwoń pod numer SnapshotsClient.resolveConflict(). W wywołaniu metody przekaż SnapshotsClient.SnapshotConflict.getConflictId() jako pierwszy argument, a obiekty SnapshotMetadataChange i SnapshotContents, które zostały przez Ciebie zmodyfikowane wcześniej jako drugi i odpowiednio trzeciego argumentu.
  6. Jeśli wywołanie SnapshotsClient.resolveConflict() się powiedzie, API zapisze Snapshot i próbuje otworzyć obiekt Snapshot na urządzeniu lokalnym.