Obsługa zapisanych gier w grach na Androida

Po wycofaniu interfejsu Google Sign-In API w 2026 roku usuniemy pakiet SDK do gier w wersji 1. Z końcem lutego 2025 r. nie będzie już można publikować w Google Play nowych tytułów, w których zastosowano integrację z wersją 1 pakietu SDK gier. Zamiast tego zalecamy używanie pakietu SDK do gier w wersji 2.
Dotychczasowe tytuły z integracjami gier w wersji 1 będą działać jeszcze przez kilka lat, ale zachęcamy do przejścia na wersję 2 od czerwca 2025 r.
Ten przewodnik dotyczy korzystania z pakietu SDK usług gier Play w wersji 1. Informacje o najnowszej wersji pakietu SDK znajdziesz w dokumentacji wersji 2.

Z tego przewodnika dowiesz się, jak zaimplementować funkcję zapisanych gier za pomocą interfejsu Snapshots API udostępnianego przez usługi gier 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 zrobiono, warto zapoznać się z koncepcjami gier zapisanych.

Pobieranie klienta zrzutów

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

Określanie zakresu Dysku

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

Oto przykład, jak to zrobić w przypadku metody onResume() dla działania związanego z logowaniem:

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ć w każdym miejscu w grze, w którym gracze mają możliwość zapisywania lub przywracania postępów. Gra może wyświetlać taką opcję w wyznaczonych punktach zapisu lub przywracania albo umożliwiać graczom zapisywanie lub przywracanie postępów w dowolnym momencie.

Gdy gracze wybiorą w Twojej grze opcję zapisu lub przywracania, gra może opcjonalnie wyświetlić ekran z prośbą o wpisanie informacji o nowej zapisanej grze lub wybranie istniejącej zapisanej gry do przywrócenia.

Aby ułatwić Ci pracę, interfejs API migawek udostępnia domyślny interfejs użytkownika do wyboru zapisanych gier, z którego możesz korzystać od razu po wyjęciu z pudełka. Interfejs wyboru zapisanych gier umożliwia graczom tworzenie nowych zapisanych gier, wyświetlanie szczegółów istniejących zapisanych gier i wczytywanie poprzednich zapisanych gier.

Aby uruchomić domyślny interfejs zapisanych gier:

  1. Zadzwoń pod numer SnapshotsClient.getSelectSnapshotIntent(), aby uzyskać Intent do uruchomienia domyślnego interfejsu wyboru zapisanych gier.
  2. Zadzwoń pod numer startActivityForResult() i przekaż ten numer Intent. Jeśli wywołanie się powiedzie, gra wyświetli interfejs wyboru zapisanej 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 =
      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 wybierze utworzenie nowego zapisu gry lub wczytanie istniejącego zapisu, interfejs wyśle żądanie do Usług gier Play. Jeśli żądanie się powiedzie, usługi gier Google Play zwrócą informacje umożliwiające utworzenie lub przywrócenie 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 jakieś błędy.

Poniższy fragment kodu pokazuje przykładową implementację funkcji 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 SnapshotsClient.DataOrConflict.getData().
  2. Pobierz instancję SnapshotContents za pomocą SnapshotsClient.SnapshotConflict.
  3. Wywołaj funkcję SnapshotContents.writeBytes(), aby zapisać dane gracza w formacie bajtowym.
  4. Gdy wszystkie zmiany zostaną zapisane, wywołaj SnapshotsClient.commitAndClose(), aby wysłać je na serwery Google. W wywołaniu metody gra może opcjonalnie podać dodatkowe informacje, aby określić, w jaki sposób Usługi gier Google Play mają prezentować zapisaną grę graczom. Informacje te są reprezentowane w SnapshotMetaDataChangeobiekcie, który gra tworzy za pomocą funkcji SnapshotMetadataChange.Builder.

Poniższy fragment kodu pokazuje, jak gra może zatwierdzać 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 w momencie, gdy aplikacja wywołuje funkcję SnapshotsClient.commitAndClose(), urządzenie gracza nie jest połączone z siecią, usługi gier Google Play zapisują dane zapisanej gry lokalnie na urządzeniu. Po ponownym połączeniu urządzenia Usługi gier Google Play synchronizują lokalnie zapisane zmiany w grze z serwerami 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 SnapshotsClient.DataOrConflict.getData(). Możesz też pobrać konkretny zrzut za pomocą interfejsu wyboru zapisanych gier, jak opisano w sekcji Wyświetlanie zapisanych gier.
  2. Pobierz instancję SnapshotContents za pomocą SnapshotsClient.SnapshotConflict.
  3. Zadzwoń na numer SnapshotContents.readFully(), aby odczytać zawartość migawki.

Poniższy fragment kodu pokazuje, jak wczytać konkretną zapisaną grę:

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 API do tworzenia migawek, wiele urządzeń może odczytywać i zapisywać tę samą zapisaną grę. Jeśli urządzenie tymczasowo utraci połączenie z siecią, a potem je odzyska, może to spowodować konflikty danych, w wyniku których zapisana gra przechowywana na urządzeniu lokalnym gracza będzie niezsynchronizowana z wersją zdalną przechowywaną na serwerach Google.

Interfejs Snapshots API udostępnia mechanizm rozwiązywania konfliktów, który w momencie odczytu przedstawia oba zestawy sprzecznych zapisanych gier i umożliwia wdrożenie strategii rozwiązywania problemó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 serwera: najnowsza wersja, która według Usług gier Google Play jest prawidłowa na urządzeniu gracza;
  • Wersja lokalna: zmodyfikowana wersja wykryta na jednym z urządzeń odtwarzacza, która zawiera sprzeczne treści lub metadane. Może się różnić od wersji, którą próbowano zapisać.

Gra musi zdecydować, jak rozwiązać konflikt, wybierając jedną z podanych wersji lub łącząc dane z dwóch zapisanych wersji gry.

Aby wykryć i rozwiązać konflikty 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, występuje konflikt, który należy rozwiązać.
  3. Zadzwoń pod numer SnapshotsClient.DataOrConflict.getConflict(), aby odzyskać instancję SnapshotsClient.snapshotConflict.
  4. Wywołaj funkcję SnapshotsClient.SnapshotConflict.getConflictId(), aby pobrać identyfikator konfliktu, który jednoznacznie identyfikuje wykryty konflikt. Ta wartość jest potrzebna w grze, aby później wysłać prośbę o rozwiązanie konfliktu.
  5. Zadzwoń pod numer SnapshotsClient.SnapshotConflict.getConflictingSnapshot(), aby uzyskać lokalną wersję.
  6. Aby uzyskać wersję serwera, zadzwoń pod numer SnapshotsClient.SnapshotConflict.getSnapshot().
  7. Aby rozwiązać konflikt zapisanej gry, 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 rozwiązać 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 konfliktów

Jeśli chcesz scalić dane z kilku zapisanych gier lub zmodyfikować istniejący Snapshot, aby zapisać go 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 obiekt SnapshotContents.
  3. Połącz dane z SnapshotsClient.SnapshotConflict.getConflictingSnapshot() i SnapshotsClient.SnapshotConflict.getSnapshot() w obiekcie SnapshotContents z poprzedniego kroku.
  4. Opcjonalnie utwórz instancję SnapshotMetadataChange, jeśli w polach metadanych wprowadzono 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 drugi i trzeci argument.
  6. Jeśli wywołanie SnapshotsClient.resolveConflict() zakończy się powodzeniem, interfejs API zapisze obiekt Snapshot na serwerze i spróbuje otworzyć obiekt Snapshot na urządzeniu lokalnym.