Obsługa gier zapisana w Grach na Androida

Ten przewodnik pokazuje, jak wdrożyć zapisane gry za pomocą interfejsu API zrzutów ekranu dostępnego w usługach Google Play. Interfejsy API znajdziesz w pakietach com.google.android.gms.games.snapshot i com.google.android.gms.games.

Zanim zaczniesz

Warto zapoznać się z koncepcjami dotyczącymi zapisanych gier.

Uzyskiwanie klienta zrzutów

Aby zacząć korzystać z interfejsu API zrzutów, gra musi najpierw uzyskać obiekt SnapshotsClient. Aby to zrobić, wywołaj metodę Games.getSnapshotsClient() i przekaż działanie.

Określanie zakresu Dysku

Zrzuty interfejsu API wykorzystują interfejs API Dysku Google do przechowywania przechowywanych gier. Aby uzyskać dostęp do interfejsu Drive API, Twoja aplikacja musi określić zakres Drive.SCOPE_APPFOLDER podczas tworzenia klienta logowania Google.

Oto przykładowa metoda stosowana podczas metody logowania onResume():


@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świetlam zapisane gry

Podczas korzystania z interfejsu API do zrzutów ekranu możesz zintegrować gracze z możliwością zapisywania lub przywracania postępów w grze. Gra może wyświetlać tę opcję w wyznaczonych punktach zapisu lub przywracania albo umożliwiać graczom zapisywanie lub przywracanie postępów w dowolnym momencie.

Gdy gracz wybierze w grze opcję zapisywania/przywracania, może opcjonalnie wyświetlić się ekran z prośbą o wprowadzenie danych dotyczących nowej zapisanej gry lub istniejącej już gry.

Aby uprościć programowanie, interfejs API migawek udostępnia domyślny interfejs użytkownika do zapisywania wybranych gier, którego możesz użyć od razu. Interfejs wyboru zapisanych gier pozwala użytkownikom tworzyć nowe zapisane gry, wyświetlać informacje o zapisanych wcześniej grach i wczytywać zapisane gry.

Aby uruchomić domyślny interfejs Zapisanych gier:

  1. Wywołaj SnapshotsClient.getSelectSnapshotIntent(), aby uzyskać Intent służącego do uruchomienia domyślnego interfejsu wyboru gier.
  2. Zadzwoń pod numer startActivityForResult() i przekaż mu plik Intent. Jeśli wywołanie się powiedzie, gra wyświetli zapisany interfejs wyboru gry wraz z określonymi przez Ciebie opcjami.

Oto przykład, 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ć zapisaną grę, interfejs wyśle żądanie do usług gier Google Play. Jeśli żądanie zostanie zrealizowane, Usługi gier Google Play zwróciją informacje, aby utworzyć lub przywrócić zapisaną grę 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 pokazuje 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
      // ...
    }
  }
}

Zapisywanie zapisanych gier

Aby zapisać treść w zapisanej grze:

  1. Asynchroniczne otwieranie zrzutów przy użyciu SnapshotsClient.open(). Następnie pobierz obiekt Snapshot z wyników zadania, wywołując obiekt SnapshotsClient.DataOrConflict.getData().
  2. Pobierz instancję SnapshotContents przez SnapshotsClient.SnapshotConflict.
  3. Wywołaj SnapshotContents.writeBytes(), aby przechowywać dane gracza w bajtach.
  4. Po zapisaniu wszystkich zmian zadzwoń pod numer SnapshotsClient.commitAndClose(), aby wysłać je na serwery Google. W wywołaniu metody gra może opcjonalnie podać dodatkowe informacje, dzięki którym usługi gier Google Play będą mogły przedstawić tę grę graczom. Te informacje są zawarte w obiekcie SnapshotMetaDataChange, który gra tworzy za pomocą SnapshotMetadataChange.Builder.

Ten fragment kodu zawiera informacje o tym, jak Twoja 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 Google Play przechowują zapisane na nim dane gier lokalnie. Po ponownym połączeniu urządzenia Usługi gier Google Play zsynchronizują zmiany wprowadzone w lokalnej pamięci gry z serwerami Google.

Wczytuję zapisane gry

Aby pobrać zapisane gry dla gracza, który jest obecnie zalogowany:

  1. Asynchroniczne otwieranie zrzutów przy użyciu SnapshotsClient.open(). Następnie pobierz obiekt Snapshot z wyników zadania, wywołując obiekt SnapshotsClient.DataOrConflict.getData(). Możesz też pobrać konkretny zrzut przez interfejs wyboru zapisanych gier, tak jak to opisano w sekcji Wyświetlanie zapisanych gier.
  2. Pobierz instancję SnapshotContents przez SnapshotsClient.SnapshotConflict.
  3. Aby odczytać zawartość zrzutu, wywołaj SnapshotContents.readFully().

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ązywanie konfliktów zapisanych gier

Gdy korzystasz w swojej grze z interfejsu API migawek, wiele urządzeń może odczytywać i zapisywać tę samą zapisaną grę. Jeśli urządzenie tymczasowo utraci połączenie z siecią, a później połączy się z powrotem, może to spowodować konflikty związane z danymi, w ramach których zapisana gra znajdująca się na urządzeniu lokalnym użytkownika nie jest zsynchronizowana z wersjami zdalnymi przechowywanymi na serwerach Google.

Zrzuty interfejsu API udostępniają mechanizm rozwiązywania konfliktów, który w czasie odczytu prezentuje oba zestawy zapisanych gier i pozwala wdrożyć strategię rozwiązywania problemów odpowiednią dla danej gry.

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

  • Wersja serwera: najnowsza wersja znana przez Usługi gier Google Play na urządzeniu użytkownika.
  • Wersja lokalna: zmodyfikowana wersja jednego z urządzeń odtwarzacza, która zawiera treści bądź metadane będące w konflikcie. Może on różnić się od wersji, którą próbujesz zapisać.

Gra musi zdecydować, jak rozwiązać konflikt, wybierając jedną z udostępnionych wersji lub scalając dane dwóch zapisanych wersji.

Aby wykryć i rozwiązać 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, musisz najpierw rozwiązać spór.
  3. Wywołaj SnapshotsClient.DataOrConflict.getConflict(), aby pobrać instancję SnaphotsClient.snapshotConflict.
  4. Wywołaj SnapshotsClient.SnapshotConflict.getConflictId(), aby pobrać identyfikator konfliktu, który jednoznacznie identyfikuje wykryty konflikt. Ta wartość wymaga Twojej gry, aby móc później wysłać prośbę o rozwiązanie konfliktu.
  5. Zadzwoń pod numer SnapshotsClient.SnapshotConflict.getConflictingSnapshot(), aby pobrać wersję lokalną.
  6. Zadzwoń pod numer SnapshotsClient.SnapshotConflict.getSnapshot(), aby pobrać wersję serwera.
  7. Aby rozwiązać konflikt zapisanych gier, wybierz wersję, którą chcesz zapisać na serwerze, w wersji ostatecznej i przekaż ją metodzie SnapshotsClient.resolveConflict().

Fragment kodu poniżej pokazuje, jak Twoja gra może obsługiwać konflikt zapisanych gier, wybierając ostatnio zmodyfikowaną grę 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");
              }
            }
          });
}

Modyfikowanie zapisanych gier w celu rozwiązania konfliktu

Jeśli chcesz scalić dane z wielu zapisanych gier lub zmodyfikować istniejące polecenie Snapshot, aby zapisać je na serwerze jako ostateczną wersję:

  1. Zadzwoń pod numer SnapshotsClient.open() .
  2. Wywołaj SnapshotsClient.SnapshotConflict.getResolutionSnapshotsContent(), aby uzyskać nowy obiekt SnapshotContents.
  3. Scal dane z SnapshotsClient.SnapshotConflict.getConflictingSnapshot() i SnapshotsClient.SnapshotConflict.getSnapshot() z obiektem SnapshotContents z poprzedniego kroku.
  4. Opcjonalnie: w razie jakichkolwiek zmian w polach metadanych utwórz instancję SnapshotMetadataChange.
  5. Zadzwoń pod numer SnapshotsClient.resolveConflict(). W wywołaniu metody jako pierwszy argument wskaż SnapshotsClient.SnapshotConflict.getConflictId(), 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 na serwerze obiekt Snapshot i spróbuje otworzyć obiekt Snaps na urządzeniu lokalnym.