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

Примечание. Это руководство предназначено для использования SDK Play Games Services v2. Информацию о предыдущем пакете SDK см. в документации Play Games Services v1 .

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

Прежде чем вы начнете

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

• Обязательно включите поддержку сохраненных игр для вашей игры в консоли Google Play.
• Загрузите и просмотрите образец кода сохраненных игр на странице образцов Android .
• Ознакомьтесь с рекомендациями, описанными в контрольном списке качества .

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

Чтобы начать использовать API моментальных снимков, ваша игра должна сначала получить объект SnapshotsClient . Вы можете сделать это, вызвав метод Games.getSnapshotsClient() и передав действие.

Примечание. Класс SnapshotsClient использует класс Task сервисов Google Play для асинхронного возврата результатов. Дополнительные сведения об использовании задач для управления многопоточной работой см. в руководстве разработчика Tasks API .

Указание области Диска

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

Вот пример того, как это сделать в методе 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
          }
        }
      });
}

Отображение сохраненных игр

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

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

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

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

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

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

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

Если игрок выбирает создание новой сохраненной игры или загрузку существующей сохраненной игры, пользовательский интерфейс отправляет запрос в игровые службы 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, как представить эту сохраненную игру игрокам. Эта информация представлена ​​в объекте 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 =
      PlayGames.getSnapshotsClient(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 =
      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.
          // ...
        }
      });
}

Обработка конфликтов сохраненных игр

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

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

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

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

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

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

1. Вызовите SnapshotsClient.open() . Результат задачи содержит класс SnapshotsClient.DataOrConflict .
2. Вызовите метод SnapshotsClient.DataOrConflict.isConflict() . Если результат верен, вам нужно разрешить конфликт.
3. Вызовите SnapshotsClient.DataOrConflict.getConflict() , чтобы получить экземпляр SnaphotsClient.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 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");
              }
            }
          });
}

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

Если вы хотите объединить данные из нескольких сохраненных игр или изменить существующий 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 открыт для изменения вашей игрой.