Integrar a API Recall do PGS ao jogo

Esta página explica como implementar a API Recall no seu jogo. Primeiro, vamos abordar a configuração do servidor de jogos e do cliente para oferecer suporte à API. Em seguida, vamos mostrar como armazenar e recuperar tokens.

Configuração do servidor de jogos

Configure o servidor de jogos para fazer chamadas da API Recall para os servidores do Google.

Configurar seu projeto dos serviços relacionados a jogos do Google Play

Siga as instruções em Como configurar os serviços relacionados a jogos do Google Play, caso ainda não tenha feito isso.

Observação: os tokens de recuperação e perfis estão disponíveis por projeto do PGS. Isso significa que tokens e perfis são armazenados por projeto do PGS e, para outros projetos, há coleções separadas de links entre perfis de recuperação e do PGS. É recomendável consultar esta documentação ao determinar como configurar seus projetos do PGS.

Configurar uma conta de serviço para o jogo

Siga as instruções para criar uma conta de serviço. No final, você terá um arquivo JSON com as credenciais da conta de serviço.

Observação: a API Recall é uma API pura de servidor para servidor. Por isso, a API Recall usa contas de serviço para autenticar o servidor de jogos, e não o OAuth normal de três etapas, que é usado por outra API Games para autenticar servidores de jogo e usuários finais.

Fazer o download da biblioteca Java do lado do servidor para os serviços relacionados a jogos do Google Play

Faça o download da biblioteca google-api-services-games mais recente e faça upload dela para seu servidor.

Preparar credenciais para chamadas da API Recall

Consulte Como se preparar para fazer uma chamada de API delegada para mais contexto.

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

Configuração do cliente do jogo

Configure o cliente do jogo para extrair os IDs de sessão de recuperação usados pelo servidor para se comunicar com os servidores do Google.

SDK do Java

Configure o SDK do Java no seu cliente e inclua com.google.android.gms:play-services-games-v2:19.0.0 e com.google.android.gms:play-services-tasks:18.0.2 ou uma versão mais recente no arquivo do Gradle.

Para se comunicar com os servidores do Google com as informações corretas, solicite um ID de sessão de recuperação do SDK do cliente, que você vai enviar ao servidor do jogo:

Kotlin

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

Java

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

Usar a API Recall no servidor do jogo

Depois de configurar o servidor e o cliente, é possível enviar o recallSessionID do cliente do jogo para o servidor do seu jogo e seguir as orientações abaixo para começar a usar a API Java para armazenar, extrair ou excluir os tokens de recuperação do lado do servidor.

Armazenar tokens

Armazene o perfil do usuário e o token do jogo usando o objeto LinkPersonaRequest. Use o GoogleCredential para chamar as APIs do Google. Para seguir a restrição de cardinalidade 1:1, só é possível vincular um perfil a um perfil do PGS por vez, e vice-versa. Defina a política de resolução caso esse perfil dos Serviços relacionados a jogos do Google Play já tenha sido vinculado a outra persona.

Opcionalmente, defina um TTL no token, que declara por quanto tempo ele é válido usando um objeto Durations. É possível definir isso usando SetTtl() (como mostrado abaixo), que define a data de validade a partir do período especificado no método, ou setExpireTime(), que permite definir um horário exato de expiração dos tokens.

Você precisa criptografar o perfil e o token do jogo, e eles não podem conter informações de identificação pessoal. As strings de perfis e tokens podem ter no máximo 256 caracteres e podem haver no máximo 20 perfis ou tokens armazenados por jogador em cada jogo.

Somente um token pode ser armazenado por perfil e por jogador em um determinado momento. Se você tentar armazenar outro token com o mesmo perfil, o sistema vai substituir o token original.

Observação: a chave de criptografia usada para criptografar tokens precisa ser exclusiva para cada aplicativo. Se o jogo for transferido para outro desenvolvedor, a chave de criptografia vai precisar ser transmitida para o novo proprietário. Os tokens de recuperação não podem ser descriptografados sem a chave de criptografia original.

import com.google.api.services.games.Games.Recall.LinkPersona;
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
}

Extrair tokens

Para extrair o token de recuperação, acesse o recallSessionId do cliente e transmita-o à API retrieveTokens:

import com.google.api.services.games.Games.Recall.RetrieveTokens;

// ...

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
}

Observação: as strings que representam o perfil não são retornadas pela API ao solicitar tokens de recuperação.

Excluir token de recuperação

Se necessário, também é possível excluir o token de recuperação com esta chamada:

import com.google.api.services.games.Games.Recall.UnlinkPersona;

// ...

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

// Confirm that the unlinking process completed successfully.
boolean unlinked = unlinkPersonaResponse.isUnlinked();