Obsługa zapisanych gier w grach na Androida

Ten przewodnik pokazuje, jak zaimplementować zapisane gry za pomocą interfejsu API zrzutów udostępnianego przez usługi gier Google Play. Interfejsy API znajdziesz w pakietach com.google.android.gms.games.snapshot i com.google.android.gms.games.

Zanim zaczniesz

Jeśli jeszcze tego nie zrobisz, warto zapoznać się z koncepcjami dotyczącymi zapisanych gier.

Pobieranie klienta zrzutów

Aby zacząć korzystać z interfejsu Snapshots API, gra musi najpierw uzyskać obiekt SnapshotsClient. Aby to zrobić, wywołaj metodę Games.getSnapshotsClient(), przekazując w niej aktywność i GoogleSignInAccount dla bieżącego odtwarzacza. Aby dowiedzieć się, jak pobrać informacje o koncie gracza, przeczytaj artykuł Logowanie się w Grach na Androida.

Określ zakres Dysku.

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

Oto przykład metody onResume(), która służy do rejestrowania aktywności logowania:

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

wyświetlanie zapisanych gier,

Interfejs Snapshots API możesz zintegrować wszędzie tam, gdzie gracze mogą zapisywać postępy w grze lub je przywracać. Gra może wyświetlać taką opcję w określonych punktach zapisu lub przywracania albo pozwalać graczom zapisywać i przywracać postępy w dowolnym momencie.

Gdy gracze wybiorą opcję zapisu/przywrócenia w grze, możesz wyświetlić opcjonalny ekran z prośbą o wpisanie informacji o nowym zapisie gry lub o wybranie istniejącego zapisu do przywrócenia.

Aby ułatwić Ci tworzenie gier, interfejs Snapshots API udostępnia domyślny interfejs użytkownika do wyboru zapisanych gier, którego możesz używać od razu po zainstalowaniu. Interfejs wyboru zapisanych gier umożliwia graczom tworzenie nowych zapisanych gier, wyświetlanie szczegółów dotyczących istniejących zapisanych gier oraz wczytywanie wcześniejszych zapisanych gier.

Aby uruchomić domyślne UI zapisanych gier:

  1. Zadzwoń pod numer SnapshotsClient.getSelectSnapshotIntent(), aby uzyskać Intent kod do uruchomienia domyślnego interfejsu wyboru zapisanych gier.
  2. Zadzwoń pod numer startActivityForResult() i przekaż ten parametr Intent. Jeśli wywołanie się powiedzie, gra wyświetli interfejs wyboru zapisanej gry wraz z określonymi opcjami.

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

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

Jeśli gracz zdecyduje się utworzyć nowe zapisanie gry lub wczytać istniejące, interfejs wyśle żądanie do Usług gier Google Play. Jeśli prośba zostanie zrealizowana, usługi Gier Play w Google Play zwrócą informacje potrzebne do utworzenia lub przywrócenia zapisanej gry za pomocą wywołania zwrotnego onActivityResult(). Gra może zastąpić tę funkcję wywołania zwrotnego, aby sprawdzić, czy podczas wysyłania żądania nie wystąpiły żadne 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 gier,

Aby zapisać treści w zapisanej grze:

  1. Asynchroniczne otwieranie zrzutu za pomocą SnapshotsClient.open(). Następnie pobierz obiekt Snapshot z wyniku zadania, wywołując funkcję SnapshotsClient.DataOrConflict.getData().
  2. Pobierz instancję SnapshotContents za pomocą SnapshotsClient.SnapshotConflict.
  3. Aby zapisać dane odtwarzacza w formacie bajtowym, wywołaj funkcję SnapshotContents.writeBytes().
  4. Gdy wszystkie zmiany zostaną zapisane, zadzwoń pod numer SnapshotsClient.commitAndClose(), aby wysłać je na serwery Google. W wywołaniu metody gra może opcjonalnie podać dodatkowe informacje, aby poinformować Usługi gier Google Play, jak przedstawić zapisaną grę graczom. Te informacje są reprezentowane przez obiekt SnapshotMetaDataChange, który gra tworzy za pomocą funkcji SnapshotMetadataChange.Builder.

Ten fragment kodu pokazuje, jak gra może zatwierdzić 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 =
      Games.getSnapshotsClient(this, GoogleSignIn.getLastSignedInAccount(this));

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

Jeśli podczas wywołania przez aplikacjęSnapshotsClient.commitAndClose() urządzenie gracza nie jest połączone z siecią, Usługi gier Google Play zapisują zapisane dane gry lokalnie na urządzeniu. Po ponownym połączeniu urządzenia Usługi gier Google Play synchronizują zapisane zmiany w grze z lokalnie zapisanymi danymi na serwerach Google.

wczytywanie zapisanych gier,

Aby pobrać zapisane gry dla aktualnie zalogowanego gracza:

  1. Asynchroniczne otwieranie zrzutu za pomocą SnapshotsClient.open(). Następnie pobierz obiekt Snapshot z wyniku zadania, wywołując funkcję SnapshotsClient.DataOrConflict.getData(). Gra może też pobrać konkretny podsumowanie za pomocą interfejsu do wyboru zapisanych gier, zgodnie z opisem w artykule Wyświetlanie zapisanych gier.
  2. Pobierz instancję SnapshotContents za pomocą SnapshotsClient.SnapshotConflict.
  3. Zadzwoń pod numer SnapshotContents.readFully(), aby odczytać zawartość zrzutu ekranu.

Ten fragment kodu pokazuje, jak załadować konkretny zapis gry:

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

Rozwiązywanie konfliktów zapisanych gier

Gdy w grze używasz interfejsu Snapshots API, możliwe jest, że wiele urządzeń będzie odczytywać i zapisywać te same zapisane dane gry. Jeśli urządzenie tymczasowo utraci połączenie z siecią, a później nawiąże je ponownie, może to spowodować konflikt danych, w którym zapisana gra na urządzeniu gracza jest niezsynchronizowana z wersją zapisaną na serwerach Google.

Interfejs Snapshots API udostępnia mechanizm rozwiązywania konfliktów, który w czasie odczytu przedstawia obie grupy konfliktujących zapisanych gier i umożliwia wdrożenie strategii rozwiązywania konfliktów odpowiedniej dla Twojej gry.

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

  • Wersja na serwerze: najnowsza wersja Usług Gier Google Play, która jest prawidłowa dla urządzenia gracza;
  • Wersja lokalna: zmodyfikowana wersja wykryta na jednym z urządzeń odtwarzacza, która zawiera sprzeczne treści lub metadane. Może się ona różnić od wersji, którą próbujesz zapisać.

Gra musi zdecydować, jak rozwiązać konflikt, wybierając jedną z podanych wersji lub scalając dane z 2 zapisanych wersji.

Aby wykryć i rozwiązać konflikty dotyczące zapisanych 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 rozwiązać konflikt.
  3. Zadzwoń pod numer SnapshotsClient.DataOrConflict.getConflict(), aby pobrać instancję SnaphotsClient.snapshotConflict.
  4. Aby pobrać identyfikator konfliktu, który jednoznacznie identyfikuje wykryty konflikt, wywołaj funkcję SnapshotsClient.SnapshotConflict.getConflictId(). Gra potrzebuje tej wartości, aby później wysłać prośbę o rozwiązanie konfliktu.
  5. Aby uzyskać lokalną wersję, zadzwoń pod numer SnapshotsClient.SnapshotConflict.getConflictingSnapshot().
  6. Aby uzyskać wersję serwera, zadzwoń pod numer SnapshotsClient.SnapshotConflict.getSnapshot().
  7. Aby rozwiązać konflikt zapisanych gier, wybierz wersję, którą chcesz zapisać na serwerze jako wersję końcową, i przekaż ją do metody SnapshotsClient.resolveConflict().

Poniższy fragment kodu pokazuje, jak gra może obsługiwać konflikt zapisanych gier, wybierając ostatnio zmodyfikowaną zapisaną 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 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");
              }
            }
          });
}

Modyfikowanie zapisanych gier w celu rozwiązania konfliktu

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

  1. Zadzwoń pod numer SnapshotsClient.open() .
  2. Aby uzyskać nowy obiekt SnapshotContents, wywołaj funkcję SnapshotsClient.SnapshotConflict.getResolutionSnapshotsContent().
  3. Scal dane z tabeli SnapshotsClient.SnapshotConflict.getConflictingSnapshot() i SnapshotsClient.SnapshotConflict.getSnapshot() z obiektem SnapshotContents z poprzedniego kroku.
  4. Opcjonalnie utwórz instancję SnapshotMetadataChange, jeśli w polach metadanych zaszły jakieś zmiany.
  5. Zadzwoń pod numer SnapshotsClient.resolveConflict(). W wywołaniu metody jako pierwszy argument podaj obiekt SnapshotsClient.SnapshotConflict.getConflictId(), a jako drugi i trzeci odpowiednio obiekty SnapshotMetadataChange i SnapshotContents, które zmodyfikowano wcześniej.
  6. Jeśli wywołanie SnapshotsClient.resolveConflict() się powiedzie, interfejs API przechowuje obiekt Snapshot na serwerze i próbuje otworzyć obiekt Snapshot na urządzeniu lokalnym.