Поддержка сохраненных игр в играх для Android

В связи с прекращением поддержки API входа Google мы удалим SDK для игр v1 в 2026 году. После февраля 2025 года вы не сможете публиковать в Google Play игры, недавно интегрированные с SDK для игр v1. Вместо этого мы рекомендуем использовать SDK для игр v2.
Хотя существующие игры с интеграцией предыдущих игр v1 продолжат функционировать еще пару лет, вам рекомендуется перейти на v2, начиная с июня 2025 года.
Это руководство посвящено использованию SDK Play Games Services v1. Информацию о последней версии SDK см. в документации v2 .

В этом руководстве показано, как реализовать сохранение игр с помощью API снимков, предоставляемого игровыми сервисами Google Play. API находятся в пакетах com.google.android.gms.games.snapshot и com.google.android.gms.games .

Прежде чем начать

Если вы еще этого не сделали, возможно, вам будет полезно ознакомиться с концепциями игры «Сохраненные игры» .

Получить клиент моментальных снимков

Чтобы начать использовать API снимков, ваша игра должна сначала получить объект SnapshotsClient . Это можно сделать, вызвав метод Games.getSnapshotsClient() и передав ему Activity и GoogleSignInAccount текущего игрока. Чтобы узнать, как получить информацию об учётной записи игрока, см. раздел Вход в игры для Android .

Укажите область действия диска

API снимков использует API Google Диска для хранения сохранённых игр. Для доступа к API Диска ваше приложение должно указать область действия Drive.SCOPE_APPFOLDER при создании клиента входа через Google.

Вот пример того, как это сделать в методе onResume() для вашего входа в систему:

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

Показать сохраненные игры

Вы можете интегрировать API снимков везде, где ваша игра предоставляет игрокам возможность сохранять или восстанавливать свой прогресс. Такая возможность может отображаться в назначенных точках сохранения/восстановления или позволять игрокам сохранять или восстанавливать свой прогресс в любое время.

После того, как игроки выберут опцию сохранения/восстановления в вашей игре, ваша игра может опционально вывести экран, предлагающий игрокам ввести информацию для новой сохраненной игры или выбрать существующую сохраненную игру для восстановления.

Для упрощения разработки API снимков предоставляет стандартный пользовательский интерфейс для выбора сохранённых игр, который можно использовать сразу после установки. Интерфейс выбора сохранённых игр позволяет игрокам создавать новые сохранённые игры, просматривать информацию о существующих сохранённых играх и загружать предыдущие сохранённые игры.

Чтобы запустить интерфейс сохраненных игр по умолчанию:

  1. Вызовите SnapshotsClient.getSelectSnapshotIntent() чтобы получить Intent для запуска пользовательского интерфейса выбора сохраненных игр по умолчанию.
  2. Вызовите startActivityForResult() и передайте это Intent . Если вызов успешен, игра отобразит интерфейс выбора сохранённой игры вместе с указанными вами параметрами.

Вот пример того, как запустить пользовательский интерфейс выбора сохраненных игр по умолчанию:

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

Если игрок выбирает создание новой сохранённой игры или загрузку существующей, пользовательский интерфейс отправляет запрос в игровые сервисы Google Play. В случае успешного запроса игровые сервисы Google Play возвращают информацию для создания или восстановления сохранённой игры через обратный вызов onActivityResult() . Ваша игра может переопределить этот обратный вызов, чтобы проверить наличие ошибок во время запроса.

В следующем фрагменте кода показан пример реализации 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
      // ...
    }
  }
}

Записать сохраненные игры

Чтобы сохранить контент в сохраненной игре:

  1. Асинхронно откройте снимок с помощью SnapshotsClient.open() . Затем извлеките объект Snapshot из результата задачи, вызвав метод SnapshotsClient.DataOrConflict.getData() .
  2. Получите экземпляр SnapshotContents через SnapshotsClient.SnapshotConflict .
  3. Вызовите SnapshotContents.writeBytes() для сохранения данных проигрывателя в байтовом формате.
  4. После того, как все изменения будут записаны, вызовите SnapshotsClient.commitAndClose() для отправки изменений на серверы Google. При вызове метода ваша игра может предоставить дополнительную информацию, указывающую сервисам Google Play Games, как отображать сохранённую игру для игроков. Эта информация представлена ​​в объекте SnapshotMetaDataChange , который ваша игра создаёт с помощью SnapshotMetadataChange.Builder .

В следующем фрагменте показано, как ваша игра может вносить изменения в сохраненную игру:

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

Если устройство игрока не подключено к сети, когда ваше приложение вызывает SnapshotsClient.commitAndClose() , игровые сервисы Google Play сохраняют сохранённые игровые данные локально на устройстве. После повторного подключения устройства игровые сервисы Google Play синхронизируют локально кэшированные изменения сохранённой игры с серверами Google.

Загрузить сохраненные игры

Чтобы получить сохраненные игры для текущего вошедшего в систему игрока:

  1. Асинхронно откройте снимок состояния с помощью SnapshotsClient.open() . Затем извлеките объект Snapshot из результата задачи, вызвав метод SnapshotsClient.DataOrConflict.getData() . Кроме того, ваша игра может получить конкретный снимок состояния через интерфейс выбора сохранённых игр, как описано в разделе Отображение сохранённых игр .
  2. Получите экземпляр SnapshotContents через SnapshotsClient.SnapshotConflict .
  3. Вызовите SnapshotContents.readFully() , чтобы прочитать содержимое снимка.

В следующем фрагменте показано, как можно загрузить определенную сохраненную игру:

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

Разрешение конфликтов сохраненных игр

При использовании API снимков в вашей игре несколько устройств могут выполнять чтение и запись одной и той же сохранённой игры. Если устройство временно потеряет сетевое подключение и затем снова подключится, это может привести к конфликтам данных, из-за которых сохранённая игра, хранящаяся на локальном устройстве игрока, не будет синхронизирована с удалённой версией, хранящейся на серверах Google.

API снимков предоставляет механизм разрешения конфликтов, который представляет оба набора конфликтующих сохраненных игр во время чтения и позволяет реализовать стратегию разрешения, подходящую для вашей игры.

Когда сервисы Google Play Games обнаруживают конфликт данных, метод SnapshotsClient.DataOrConflict.isConflict() возвращает значение true В этом случае класс SnapshotsClient.SnapshotConflict предоставляет две версии сохраненной игры:

  • Версия сервера : самая актуальная версия, известная сервисам Google Play Games и соответствующая устройству игрока; и
  • Локальная версия : на одном из устройств проигрывателя обнаружена изменённая версия, содержащая конфликтующий контент или метаданные. Возможно, она отличается от версии, которую вы пытались сохранить.

Ваша игра должна решить, как разрешить конфликт, выбрав одну из предоставленных версий или объединив данные двух сохраненных версий игры.

Чтобы обнаружить и разрешить конфликты сохраненных игр:

  1. Вызовите SnapshotsClient.open() . Результат задачи содержит класс SnapshotsClient.DataOrConflict .
  2. Вызовите метод SnapshotsClient.DataOrConflict.isConflict() . Если результат — true, вам необходимо разрешить конфликт.
  3. Вызовите SnapshotsClient.DataOrConflict.getConflict() , чтобы получить экземпляр SnapshotsClient.snapshotConflict .
  4. Вызовите метод SnapshotsClient.SnapshotConflict.getConflictId() чтобы получить уникальный идентификатор обнаруженного конфликта. Это значение необходимо вашей игре для отправки запроса на разрешение конфликта в будущем.
  5. Вызовите SnapshotsClient.SnapshotConflict.getConflictingSnapshot() , чтобы получить локальную версию.
  6. Вызовите SnapshotsClient.SnapshotConflict.getSnapshot() , чтобы получить версию сервера.
  7. Чтобы разрешить конфликт сохраненной игры, выберите версию, которую вы хотите сохранить на сервере в качестве финальной версии, и передайте ее методу SnapshotsClient.resolveConflict() .

В следующем фрагменте показан пример того, как ваша игра может справиться с конфликтом сохраненных игр, выбрав последнюю измененную сохраненную игру в качестве окончательной версии для сохранения:

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

Изменяйте сохраненные игры для разрешения конфликтов

Если вы хотите объединить данные из нескольких сохраненных игр или изменить существующий Snapshot для сохранения на сервере в качестве окончательной версии, выполните следующие действия:

  1. Вызовите SnapshotsClient.open() .
  2. Вызовите SnapshotsClient.SnapshotConflict.getResolutionSnapshotsContent() , чтобы получить новый объект SnapshotContents .
  3. Объедините данные из SnapshotsClient.SnapshotConflict.getConflictingSnapshot() и SnapshotsClient.SnapshotConflict.getSnapshot() в объект SnapshotContents из предыдущего шага.
  4. При желании можно создать экземпляр SnapshotMetadataChange , если в полях метаданных произошли какие-либо изменения.
  5. Вызовите метод SnapshotsClient.resolveConflict() . При вызове метода передайте метод SnapshotsClient.SnapshotConflict.getConflictId() в качестве первого аргумента, а также объекты SnapshotMetadataChange и SnapshotContents , которые вы изменили ранее, в качестве второго и третьего аргументов соответственно.
  6. Если вызов SnapshotsClient.resolveConflict() успешен, API сохраняет объект Snapshot на сервере и пытается открыть объект Snapshot на локальном устройстве.
    • В случае конфликта метод SnapshotsClient.DataOrConflict.isConflict() возвращает true . В этом случае игра должна вернуться к шагу 2 и повторить шаги по изменению снимка, пока конфликты не будут устранены.
    • Если конфликта нет, SnapshotsClient.DataOrConflict.isConflict() возвращает false , а объект Snapshot открыт для изменения вашей игрой.