Интегрируйте API отзыва PGS в свою игру.

На этой странице объясняется, как реализовать API возврата в вашей игре. Сначала он описывает настройку вашего игрового сервера и клиента для поддержки API, а затем рассказывает о том, как хранить и получать токены.

Настройка игрового сервера

Настройте свой игровой сервер для выполнения вызовов API Recall на серверы Google.

1. Настройте проект игровых сервисов Play.

(Если это еще не выполнено) Следуйте инструкциям в разделе «Настройка игровых сервисов Google Play» .

Примечание. Токены отзыва и персонажи доступны для каждого проекта PGS. Это означает, что токены и персоны хранятся для каждого проекта PGS, а для отдельных проектов PGS существуют отдельные коллекции ссылок между профилями PGS и персонами. Мы рекомендуем просмотреть эту документацию при определении того, как настроить проекты PGS.

2. Настройте сервисную учетную запись для игры.

Следуйте инструкциям по созданию сервисной учетной записи . В конце у вас должен получиться файл JSON с учетными данными сервисной учетной записи.

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

3. Загрузите серверную библиотеку Java для PlayGamesServices.

Загрузите последнюю версию библиотеки google-api-services-games и загрузите ее на свой сервер.

4. Подготовьте учетные данные для вызовов API отзыва.

Дополнительную информацию см. в разделе Подготовка к авторизованному вызову API .

import com.google.api.client.googleapis.auth.oauth2.GoogleCredential;
import com.google.api.services.games.Games;
import com.google.api.services.games.GamesScopes;

// ...

GoogleCredential credential =
  GoogleCredential.fromStream(new FileInputStream("<credentials>.json"))
    .createScoped(Collections.singleton(GamesScopes.ANDROIDPUBLISHER));

Games gamesApi =
    new Games.Builder(httpTransport, JSON_FACTORY, credential).build();

Настройка игрового клиента

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

Java SDK

Настройте Java SDK в своем клиенте и обязательно включите com.google.android.gms:play-services-games-v2:19.0.0 и com.google.android.gms:play-services-tasks:18.0.2 или выше в вашем файле Gradle.

Чтобы обмениваться информацией с серверами Google с правильной информацией, вам необходимо запросить идентификатор сеанса отзыва из клиентского SDK, который вы отправляете на сервер вашей игры.

Котлин

PlayGames.getRecallClient(getActivity())
                .requestRecallAccess()
                .addOnSuccessListener { recallAccess -> val recallSessionId: String = recallAccess.getSessionId() }
                // Send the recallSessionId to your game server

Ява

PlayGames.getRecallClient(getActivity())
  .requestRecallAccess()
  .addOnSuccessListener(
    recallAccess -> {
      String recallSessionId = recallAccess.getSessionId();
      // Send the recallSessionId to your game server
    });

Unity SDK

Настройте Unity SDK в своем клиенте , если это еще не сделано.

Чтобы обмениваться информацией с серверами Google с правильной информацией, вам необходимо запросить идентификатор сеанса отзыва из клиентского SDK и отправить его на сервер вашей игры.

PlayGamesPlatform.Instance.RequestRecallAccess(
    recallAccess => {
        string recallSessionId = recallAccess.sessionId;
        // Send the recallSessionId to your game server
    });

Используйте API отзыва на своем игровом сервере.

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

Магазин токенов

Личность пользователя и игровой токен можно сохранить с помощью объекта LinkPersonaRequest . Вам необходимо использовать GoogleCredential для вызова API Google (контекст см. в разделе Вызов API Google ). Обратите внимание, что в соответствии с ограничением количества элементов 1:1 вы можете одновременно связать только одну персону с одним профилем PGS (и наоборот). Вам следует установить политику разрешения на случай, если этот профиль PGS уже был связан с другим персоной.

При желании вы можете установить TTL для токена, который определяет, как долго токен действителен, с помощью объекта Durations . Вы можете установить это с помощью SetTtl() (как показано ниже), который устанавливает дату истечения срока действия на основе периода времени, указанного в методе, или setExpireTime() , который позволяет вам установить точное время истечения срока действия токенов.

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

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

Примечание. Ключ шифрования, используемый для шифрования токенов, должен быть уникальным для каждого приложения. Если игра передается другому разработчику, ключ шифрования необходимо передать новому владельцу. Токены отзыва не могут быть расшифрованы без исходного ключа шифрования.

import com.google.api.services.games.Games.Recall.LinkPersona;
import com.google.api.services.games.model.LinkPersonaRequest;
import com.google.api.services.games.model.LinkPersonaResponse;
import com.google.protobuf.util.Durations;

// ...

Games gamesApi =
    new Games.Builder(httpTransport, JSON_FACTORY, credential).build();

String recallSessionId = ... // recallSessionID from game client
String persona = ... // encrypted opaque string, stable for in-game account
String token = ... // encrypted opaque string encoding the progress line

LinkPersonaRequest linkPersonaRequest =
  LinkPersonaRequest.newBuilder()
    .setSessionId(recallSessionId)
    .setPersona(persona)
    .setToken(token)
    .setCardinalityConstraint(ONE_PERSONA_TO_ONE_PLAYER)
    .setConflictingLinksResolutionPolicy(CREATE_NEW_LINK)
    .setTtl(Durations.fromDays(7)) // Optionally set TTL for token
    .build();

LinkPersonaResponse linkPersonaResponse =
  gamesApi.recall().linkPersona(linkPersonaRequest).execute();

if (linkPersonaResponse.getState() == LINK_CREATED) {
  // success
}

Получить токены

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

• Токены, связанные с текущей игрой, включая жетоны отзыва на уровне игры.
• Последний токен, хранящийся во всех играх, принадлежащих учетной записи разработчика.
• Учитывая список игр, принадлежащих учетной записи разработчика, все жетоны отзыва, связанные с каждой игрой.

Примечание. Когда вы запрашиваете токены отзыва, API не возвращает строки, представляющие личность.

Жетоны отзыва в рамках игры

Чтобы получить токены отзыва из текущей игры, получите recallSessionId от клиента и передайте его в API retrieveTokens :

import com.google.api.services.games.Games;
import com.google.api.services.games.model.RetrievePlayerTokensResponse;
import com.google.api.services.games.model.RecallToken;

// ...

String recallSessionId = ... // recallSessionID from game client

RetrievePlayerTokensResponse retrievePlayerTokensResponse =
  gamesApi.recall().retrieveTokens(recallSessionId).execute();

for (RecallToken recallToken : retrievePlayerTokensResponse.getTokens()) {
  String token recallToken.getToken();
  // Same string as was written in LinkPersona call
  // decrypt and recover in-game account
}

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

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

import com.google.api.services.games.Games;
import com.google.api.services.games.model.RetrieveDeveloperGamesLastPlayerTokenResponse;
import com.google.api.services.games.model.GamePlayerToken;
import com.google.api.services.games.model.RecallToken;

// ...

String recallSessionId = ... // recallSessionID from game client

RetrieveDeveloperGamesLastPlayerTokenResponse response =
        gamesApi.recall().lastTokenFromAllDeveloperGames(recallSessionId)
        .execute();

if (response.hasGamePlayerToken()) {
    GamePlayerToken gamePlayerToken = response.getGamePlayerToken();

    // The ID of the application that the token is associated with.
    String applicationId = gamePlayerToken.getApplicationId();

    // Same string as was written in LinkPersona call.
    RecallToken recallToken = gamePlayerToken.getRecallToken();

    // Decrypt and recover in-game account.
}

Все жетоны отзыва в заданном списке игр, принадлежащих учетной записи разработчика.

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

import com.google.api.services.games.Games;
import com.google.api.services.games.model.RetrieveGamesPlayerTokensResponse;
import com.google.api.services.games.model.GamePlayerToken;
import com.google.api.services.games.model.RecallToken;

// ...

String recallSessionId = ... // recallSessionID from game client

// Application IDs for which you would like to retrieve the recall tokens.
List<String> applicationIds = ...

RetrieveGamesPlayerTokensResponse response =
gamesApiClient
        .recall()
        .gamesPlayerTokens(recallSessionId)
        .setApplicationIds(applicationIds)
        .execute();

for (GamePlayerToken gamePlayerToken : response.getGamePlayerTokens()) {
    // The ID of the application that the token is associated with.
    String applicationId  = gamePlayerToken.getApplicationId();


    // Same string as was written in LinkPersona call.
    RecallToken recallToken = gamePlayerToken.getRecallToken();
    
    // Decrypt and recover in-game account.
}

Удалить токен отзыва

При необходимости вы также можете удалить токен отзыва с помощью следующего вызова:

import com.google.api.services.games.Games;
import com.google.api.services.games.model.UnlinkPersonaRequest;
import com.google.api.services.games.model.UnlinkPersonaResponse;

// ...

String recallSessionId = ...
String persona = ...
String token = ...

Games gamesApi =
    new Games.Builder(httpTransport, JSON_FACTORY, credential).build();

UnlinkPersonaRequest unlinkPersonaRequest =
  UnlinkPersonaRequest.newBuilder()
    .setSessionId(recallSessionId)
    .setPersona(persona)
    // .setToken(token) - alternatively set token, but not both
    .build();

UnlinkPersonaResponse unlinkPersonaResponse =
  gamesApi.recall().unlinkPersona(unlinkPersonaRequest).execute();

boolean unlinked = unlinkPersonaResponse.isUnlinked();

Включить беспрофильный режим

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

1. Включите беспрофильный возврат для вашего игрового проекта PGS в консоли разработчика Play.
2. Ознакомьтесь с дополнительными условиями , описанными далее в этом разделе.
3. Добавьте следующий тег метаданных в манифест вашего приложения :

<meta-data
  android:name="com.google.android.gms.games.PROFILELESS_RECALL_ENABLED"
  android:value="true" />

Дополнительные условия

Помимо соблюдения Условий использования игровых сервисов Play , вы соглашаетесь с тем, что если вы используете API отзыва для пользователей без профиля PGS, который позволяет передавать данные конечных пользователей Google без наличия у них профиля игровых сервисов Play, вы должны: прежде чем передавать такие данные в Google, предоставьте конечному пользователю соответствующее уведомление с описанием 1) вашего обмена данными с Google для включения функции привязки учетной записи Play Games, 2) наличия настроек для управления таким обменом, например, через Play Games. настройки и 3) обработку таких данных в соответствии с Политикой конфиденциальности Google и получить соответствующее согласие конечного пользователя на такой обмен, которое соответствует всем применимым законодательным требованиям.