Z tego przewodnika dowiesz się, jak wdrożyć zapisane gry 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
Więcej informacji o tej funkcji znajdziesz w omówieniu Zapisanych gier.
- Włącz obsługę zapisanych gier w Konsoli Google Play.
- Pobierz i przejrzyj przykładowy kod zapisanych gier na stronie z przykładowymi aplikacjami na Androida.
- Zapoznaj się z rekomendacjami opisanymi na liście kontrolnej jakości.
Pobieranie klienta zrzutów
Aby zacząć korzystać z interfejsu API migawek, gra musi najpierw uzyskać obiekt SnapshotsClient
. Możesz to zrobić, wywołując metodę
Games.getSnapshotsContents()
i przekazując aktywność.
Wyświetlanie zapisanych gier
Interfejs Snapshots API możesz zintegrować w dowolnym 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 grze opcję zapisania lub przywrócenia, gra może opcjonalnie wyświetlić ekran z prośbą o wpisanie informacji o nowej zapisanej grze lub o wybranie istniejącej zapisanej gry do przywrócenia.
Aby uprościć proces tworzenia, interfejs API migawek udostępnia domyślny interfejs 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:
- Wywołaj funkcję
SnapshotsClient.getSelectSnapshotIntent()
aby uzyskaćIntent
do uruchomienia domyślnego interfejsu wyboru zapisanych gier. - Zadzwoń pod numer
startActivityForResult()
i przekaż dalejIntent
. 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 = 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 wybierze utworzenie nowej lub wczytanie istniejącej zapisanej gry, interfejs wyśle żądanie do Usług gier Play. Jeśli żądanie zostanie zrealizowane, usługi gier Play zwrócą informacje umożliwiające utworzenie lub przywrócenie zapisanej gry za pomocą wywołania zwrotnego onActivityResult()
. Twoja 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:
Asynchroniczne otwieranie zrzutu za pomocą funkcji
SnapshotsClient.open()
.Pobierz obiekt
Snapshot
z wyniku zadania, wywołującSnapshotsClient.DataOrConflict.getData()
.Pobierz instancję
SnapshotContents
za pomocąSnapshotsClient.SnapshotConflict
.Wywołaj
SnapshotContents.writeBytes()
aby zapisać dane gracza w formacie bajtowym.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ć, jak Usługi gier Play mają prezentować zapisaną grę graczom. Te informacje są reprezentowane w obiekcieSnapshotMetaDataChange
utworzonym przez grę za pomocą funkcjiSnapshotMetadataChange.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 = 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 SnapshotsClient.commitAndClose()
, Usługi gier Play zapisują dane zapisanej gry lokalnie na urządzeniu. Po ponownym połączeniu urządzenia usługi gier Play synchronizują lokalnie zapisane zmiany w grze z serwerami Google.
Wczytywanie zapisanych gier
Aby pobrać zapisane gry dla uwierzytelnionego gracza:
Asynchroniczne otwieranie zrzutu za pomocą
SnapshotsClient.open()
.Pobierz obiekt
Snapshot
z wyniku zadania, wywołującSnapshotsClient.DataOrConflict.getData()
. Możesz też pobrać konkretny zapisany stan gry za pomocą interfejsu wyboru zapisanych gier, zgodnie z opisem w sekcji Wyświetlanie zapisanych gier.Pobierz instancję
SnapshotContents
za pomocąSnapshotsClient.SnapshotConflict
.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 = 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
Jeśli w grze używasz interfejsu Snapshots API, wiele urządzeń może odczytywać i zapisywać te same zapisane gry. 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 gier Play 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 znana Usługom gier Play, która jest dokładna w przypadku 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ę 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:
Zadzwoń pod numer
SnapshotsClient.open()
. Wynik zadania zawiera klasęSnapshotsClient.DataOrConflict
.Wywołaj metodę
SnapshotsClient.DataOrConflict.isConflict()
. Jeśli wynik to „prawda”, masz konflikt do rozwiązania.Zadzwoń pod numer
SnapshotsClient.DataOrConflict.getConflict()
, aby odzyskać instancjęSnapshotsClient.snapshotConflict
.Wywołaj
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.Aby uzyskać wersję lokalną, wywołaj metodę Call
SnapshotsClient.SnapshotConflict.getConflictingSnapshot()
.Aby uzyskać wersję serwera, wywołaj metodę
SnapshotsClient.SnapshotConflict.getSnapshot()
.Aby rozwiązać konflikt zapisanej gry, wybierz wersję, którą chcesz zapisać na serwerze jako wersję ostateczną, i przekaż ją do metody
SnapshotsClient.resolveConflict()
.
Poniższy fragment kodu pokazuje, jak gra może rozwiązać konflikt zapisanych stanów gry, wybierając ostatnio zmodyfikowany zapisany stan gry 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
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:
Zadzwoń pod numer
SnapshotsClient.open()
.Zadzwoń pod numer
SnapshotsClient.SnapshotConflict.getResolutionSnapshotsContent()
i uzyskaj nowy obiektSnapshotContents
.Połącz dane z obiektów
SnapshotsClient.SnapshotConflict.getConflictingSnapshot()
iSnapshotsClient.SnapshotConflict.getSnapshot()
w obiektSnapshotContents
z poprzedniego kroku.W razie potrzeby utwórz instancję
SnapshotMetadataChange
, jeśli w polach metadanych wprowadzono jakiekolwiek zmiany.Zadzwoń pod numer
SnapshotsClient.resolveConflict()
. W wywołaniu metody przekażSnapshotsClient.SnapshotConflict.getConflictId()
jako pierwszy argument, a zmodyfikowane wcześniej obiektySnapshotMetadataChange
iSnapshotContents
jako drugi i trzeci argument.Jeśli wywołanie
SnapshotsClient.resolveConflict()
się powiedzie, interfejs API zapisze obiektSnapshot
na serwerze i spróbuje otworzyć obiekt Snapshot na urządzeniu lokalnym.- Jeśli wystąpi konflikt,
SnapshotsClient.DataOrConflict.isConflict()
zwracatrue
. W takim przypadku gra powinna wrócić do kroku 2 i powtórzyć czynności związane z modyfikowaniem zrzutu, dopóki konflikty nie zostaną rozwiązane. - Jeśli nie ma konfliktu, funkcja
SnapshotsClient.DataOrConflict.isConflict()
zwraca wartośćfalse
, a obiektSnapshot
jest otwarty, dzięki czemu gra może go modyfikować.
- Jeśli wystąpi konflikt,