A API Recall ajuda você a vincular os usuários dos serviços do Google Play Games às contas deles no jogo, permitindo a restauração automática do progresso. Você armazena tokens de recuperação em servidores de jogos, que associam esses tokens a um perfil dos Serviços Relacionados a Jogos do Google Play de um usuário. O uso da API Recall é opcional e é o método recomendado para implementar a restauração perfeita se você não tiver seu próprio back-end de identidade robusto.
Terminologia
Este documento usa a seguinte terminologia:
Token de recuperação: uma chave segura armazenada em servidores de jogos que atua como um link entre a conta dos serviços do Google Play Games de um jogador e a conta dele no jogo.
ID da sessão: um identificador temporário e exclusivo gerado pelo SDK dos serviços do Google Play Games no dispositivo do jogador. Ele indica que uma solicitação feita pelo servidor de back-end se originou de uma sessão de jogo legítima e ativa no dispositivo de um jogador.
Exemplos de situações
Confira alguns exemplos de como a API Recall pode ser usada:
Um usuário está jogando um jogo em que o desenvolvedor tem um sistema de identidade para acompanhar o progresso do usuário e usa o PGS em paralelo com outros métodos de autenticação para conectar os usuários ao jogo. Neste exemplo, o usuário fez login na conta do PGS Laura e cria uma conta no jogo com o sistema de identidade do desenvolvedor chamado Racer94. À medida que o usuário joga, o servidor de jogos do desenvolvedor sincroniza o progresso.
Separadamente, o desenvolvedor salva um token de recuperação com o Google, que corresponde à conta no jogo do usuário. O Google armazena automaticamente esse token no perfil do PGS do usuário.
Agora, o usuário decide jogar no Google Play Games no PC pela primeira vez. O usuário é autenticado automaticamente com a conta do PGS, e o cliente do jogo verifica se há algum progresso disponível para esse usuário. Em seguida, o servidor de jogos consulta o Google para saber se há tokens para essa conta do PGS. Como há, o Google envia o token de recuperação, e o servidor de jogos usa esse token para encontrar a conta associada do usuário Racer94 e restaurar o progresso. Como a autenticação com o PGS é uma experiência simples, o progresso do usuário é restaurado pelo app sem que seja necessário inserir um nome de usuário ou uma senha. Além disso, o desenvolvedor pode usar a autenticação do PGS com o sistema de identidade atual e confiar no Google para armazenar o vínculo entre o progresso e a conta do jogador.
Conforme mostrado no exemplo anterior, há duas ações principais que são realizadas pela API Recall:
Armazenar o token com o Google quando um usuário faz login com uma das contas no jogo.
Extrair o token de um usuário para restaurar as contas dele no jogo.
Além dos tokens de recuperação, a API Recall também requer um identificador estável correspondente à conta no jogo, conhecido como perfil. Pense em um perfil como o rótulo que representa a conta no jogo do usuário no sistema de identidade do desenvolvedor, e o token de recuperação como uma chave usada para restaurar a conta do usuário no jogo. Os valores de perfil e o token não podem ser reutilizados em projetos diferentes do PGS. Além disso, embora os tokens de recuperação possam ser alterados ao longo do tempo, o perfil precisa ser estável de acordo com a conta do usuário no jogo.
Fluxos técnicos para armazenar e extrair os tokens de recuperação
Nesta seção, abordamos o fluxo técnico entre o cliente os servidores do jogo em relação os servidores do Google ao armazenar e extrair tokens de recuperação.
Etapa 1: autenticar o usuário do PGS e extrair o ID da sessão
O jogo inicializa o SDK do PGS e tenta autenticar o usuário com esses serviços.
Supondo que o usuário esteja autenticado, solicite um ID de sessão do SDK do Google Play Games no cliente do jogo e um token do OAuth 2.0 do back-end de OAuth do Google. O ID da sessão e os tokens OAuth 2.0 são usados para se comunicar com o back-end do Google Games.
Etapa 2: extrair todos os tokens de recuperação disponíveis
Solicite todos os tokens de recuperação associados à conta do usuário do PGS. Se um token estiver presente, prossiga para a Etapa 3a e restaure o progresso. Caso contrário, se for um novo usuário e ele não tiver um token, prossiga para a Etapa 3b e armazene um novo token.
Etapa 3a: restaurar o progresso se o token estiver presente
Se houver um token, extraia e descriptografe o token e restaure os dados do usuário.
Etapa 3b: armazenar um token, se nenhum estiver presente
Como não há nenhum token, nenhum progresso é restaurado. O usuário faz a autenticação da plataforma usando o sistema de identidade do desenvolvedor ou cria uma nova conta, caso não exista uma. Observação: esse não é um login no PGS (que já foi feito), mas com um sistema de identidade do desenvolvedor fora do PGS.
Crie um token de recuperação criptografado que codifique a conta do usuário no jogo e o envie ao Google com o ID da sessão e o token OAuth 2.0. Nesse momento, o Google criará uma associação entre o token de recuperação que foi enviado e a conta do PGS do jogador.
Fluxos para usuários sem um perfil dos Serviços Relacionados a Jogos do Google Play
Você pode armazenar tokens de recuperação para um usuário que ainda não criou um perfil dos Serviços Relacionados a Jogos do Google Play usando o modo sem perfil. No entanto, há duas ressalvas importantes:
- Não é possível recuperar tokens de um usuário que não tem um perfil dos Serviços Relacionados a Jogos do Google Play. A criação de perfil é solicitada automaticamente quando o usuário tenta fazer login no jogo com os Serviços Relacionados a Jogos do Google Play em um segundo dispositivo.
- Você precisa seguir outras diretrizes
para garantir que tenha um aviso adequado descrevendo os seguintes itens e
recebendo o consentimento do usuário final apropriado:
- Seu compartilhamento dos 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, como as do Google Play Games.
- O tratamento desses dados de acordo com a Política de Privacidade do Google.
Armazenar um token e um perfil
- Um usuário sem um perfil dos Serviços Relacionados a Jogos do Google Play abre um jogo que tem a recuperação sem perfil ativada.
- O SDK do Google Play Games aciona uma autenticação automática da plataforma, que falha porque o usuário não tem um perfil dos Serviços Relacionados a Jogos do Google Play.
- O SDK do Google Play Games mostra uma barra de notificação que informa ao usuário que o jogo tem integração com o Google. Essa barra de notificação é acionável: o usuário pode desativar a recuperação até que um perfil seja criado.
- O jogo solicita acesso de recuperação. Observação: o PGS rejeita solicitações de acesso de recuperação quando há perfis do PGS no dispositivo ou quando não há Contas do Google no dispositivo. Nesse caso, o jogo precisa continuar sem usar o PGS.
- Depois que o usuário faz login com uma conta no jogo, o jogo cria um token e um perfil para o usuário que corresponde à conta dele no jogo. O jogo armazena esse par com o Google. O jogo poderá armazenar mais tokens mais tarde se o usuário fizer login em outras contas no jogo.
Iniciar um jogo em um novo dispositivo
- Um usuário sem um perfil dos Serviços Relacionados a Jogos do Google Play abre um jogo que tem a recuperação sem perfil ativada em um dispositivo.
- O jogo registra um token de recuperação sem perfil, conforme descrito em Armazenar um token e um perfil.
- O usuário abre o mesmo jogo em um dispositivo diferente que tem a mesma configuração de conta.
- O SDK do Google Play Games aciona a criação de perfil. O usuário pode analisar e rejeitar tokens de recall armazenados anteriormente. O usuário cria um perfil do PGS nesse momento.
- A autenticação automática da plataforma no PGS é concluída, e o jogo recebe o status autenticado.
- O jogo extrai tokens de recuperação para o usuário como de costume.
Próximas etapas
Para integrar a API Recall ao cliente e ao servidor de jogos, siga estas orientações.