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 extrair tokens.

Configuração do servidor de jogos

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

1. Configurar seu projeto dos serviços do Google Play Games

Se você ainda não fez isso, siga as instruções em Configurar os serviços relacionados a jogos do Google Play.

2. 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.

3. Fazer o download da biblioteca Java do lado do servidor para PlayGamesServices

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

4. Preparar credenciais para chamadas da API Recall

Consulte Preparar-se para fazer uma chamada de API autorizada 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 versões mais recentes 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
    });

SDK do Unity

Configure o SDK do Unity no seu cliente, caso ainda não tenha feito isso.

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 e a envie ao servidor do jogo.

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

SDK nativo v2 (Beta)

Se você ainda não fez isso, comece a usar os serviços do Google Play Games para C e C++.

// Include the following headers

#include "play_games.h"
#include "recall_client.h"
#include "pgs_status_code.h"
// Request Recall Access
// Initializes the Play Games Services v2 Native SDK (beta).
Pgs_initialize(javaVM, activity);

//Creating Recall Client
PgsRecallClient* pgs_recall_client =
      PgsRecallClient_create(activity);

// RequestRecallAccess Function
PgsRecallClient_requestRecallAccess(
    pgs_recall_client,

    // This is your callback function defined as an inline lambda
    [](PgsStatusCode status_code, char* session_id, user_data) {

        if (status_code == PGS_STATUS_SUCCESS) {
            // Recall Session Id Fetched Successfully
        } else {
            // Fetching Recall Session Id Failed
            // Handle error based on status_code.
            // Examples:
            // PGS_STATUS_NETWORK_ERROR: Check internet connection.
            // PGS_STATUS_INTERNAL_ERROR: An unexpected error occurred.
        }

        // Clean up the client instance passed as user_data
        PgsRecallClient* client = static_cast<PgsRecallClient*>(user_data);
        if (client != nullptr) {
            PgsRecallClient_destroy(client);
        }
    },

    user_data // Data to pass to the callback
);

// Shuts down the Play Games Services v2 Native SDK (beta).
Pgs_destroy()

Usar a API Recall no servidor do jogo

Depois de configurar o servidor de jogos e o cliente do jogo, é possível enviar o recallSessionID do cliente do jogo para o servidor de jogos 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

Uma conta de jogador na API Recall do Google Play Games consiste em duas informações:

  • um perfil que serve como um identificador estável para uma conta no jogo
  • um token que serve como a chave para fazer login com segurança em uma conta de jogador

É possível armazenar a persona e o token de um usuário usando o objeto LinkPersonaRequest. Use o GoogleCredential para chamar as APIs do Google (consulte Como chamar as APIs do Google para contexto). Um perfil tem uma restrição de cardinalidade 1:1: um perfil do PGS pode conter apenas um perfil de jogador, e um perfil de jogador pode pertencer a apenas um perfil do PGS. Defina a política de resolução de links conflitantes para definir como as violações da restrição de cardinalidade 1:1 devem ser resolvidas.

Defina opcionalmente o tempo de expiração do token. Use SetTtl() com um objeto Durations para definir um tempo de vida útil ou fornecer um tempo de expiração exato com setExpireTime().

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 perfil e token podem ter no máximo 256 caracteres.

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
}

Extrair tokens

Há três opções para extrair um token, com base nas necessidades dos seus jogos. É possível solicitar o seguinte:

  • Os tokens associados ao jogo atual, incluindo tokens de recuperação com escopo de jogo.
  • O último token armazenado em todos os jogos de propriedade da conta de desenvolvedor.
  • Considerando uma lista de jogos de propriedade da conta de desenvolvedor, todos os tokens de recuperação associados a cada jogo.

Tokens de recuperação com escopo de jogo

Para extrair os tokens de recuperação do jogo atual, extraia o recallSessionId do cliente e transmita-o para a 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
}

Token de recuperação mais recente em todos os jogos de propriedade da conta de desenvolvedor

Para extrair o token mais recente armazenado em todos os jogos de propriedade da conta de desenvolvedor no Google Play Console, extraia o recallSessionId do cliente e transmita-o para a API lastTokenFromAllDeveloperGames, conforme mostrado no snippet de código a seguir. Como parte da resposta, é possível inspecionar o ID do aplicativo associado a esse token.

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.
}

Todos os tokens de recuperação em uma determinada lista de jogos de propriedade da conta de desenvolvedor

Para extrair todos os tokens associados a uma lista de jogos de propriedade da sua conta de desenvolvedor no Google Play Console, extraia o recallSessionId do cliente e transmita-o para a API gamesPlayerTokens. Forneça uma lista de IDs de aplicativos.

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.
}

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

Ativar o modo sem perfil

É possível ativar a funcionalidade limitada da API Recall para usuários que não têm perfis do PGS seguindo estas etapas:

  1. Ative a recuperação sem perfil para seu projeto de jogo do PGS no Play Developer Console. Selecione a opção &quot;Ativar
armazenamento&quot;.
  2. Analise os termos adicionais descritos mais adiante nesta seção.
  3. Adicione a seguinte tag de metadados ao manifesto do app:
<meta-data
  android:name="com.google.android.gms.games.PROFILELESS_RECALL_ENABLED"
  android:value="true" />

Termos adicionais

Você também precisa obedecer aos Termos de Serviço dos serviços do Google Play Games. Se você usar a API Recall para usuários sem um perfil do PGS, o que envolve o compartilhamento de dados do usuário final com o Google, será necessário, antes de compartilhar esses dados com o Google, fornecer aos usuários finais um aviso adequado que descreva o seguinte:

  • Como você compartilha dados com o Google para ativar o recurso de vinculação de contas do Google Play Games.
  • A disponibilidade de configurações para gerenciar esse compartilhamento, por exemplo, nas configurações do Google Play Games.
  • O tratamento desses dados de acordo com a Política de Privacidade do Google e a exigência de obter o consentimento adequado do usuário final para esse compartilhamento que atenda a todos os requisitos legais aplicáveis.