Pular para o conteúdo principal
O SDK do PlayFab Services inclui um mecanismo de atualização de tokens em segundo plano que ajuda a manter ativa a sessão do jogador. Entender como esse mecanismo funciona (e quando seu jogo precisa agir) é importante, especialmente para títulos do Game Development Kit (GDK) que dão suporte a suspensão e retomada.

Como funciona a atualização automática de tokens

O SDK executa um trabalho em segundo plano que verifica periodicamente o token de entidade do jogador. Se o token ainda for válido, mas estiver perto de expirar (a menos de uma hora da expiração), o SDK se autentica novamente de forma automática usando as credenciais da chamada de login original. Se essa atualização for bem-sucedida, o token será atualizado de forma transparente e o PFEntityHandle continuará válido. Nenhuma ação é necessária do seu jogo. Você pode observar essas atualizações silenciosas de token registrando um retorno de chamada PFEntityRegisterTokenRefreshedEventHandler (consulte Atualização transparente).

Quando seu jogo precisa tratar a expiração de tokens

Há cenários em que o SDK não consegue atualizar o token automaticamente:
  • O token já expirou. A atualização automática só funciona quando o token ainda é válido. Se o token tiver expirado totalmente (por exemplo, após um longo ciclo de suspensão/retomada), o SDK não tentará um novo login automático. Em vez disso, ele notificará seu jogo por meio do TokenExpiredHandler.
  • As credenciais de login originais não são mais válidas. Se o identificador ou o token fornecido originalmente à solicitação de login não for mais válido, a atualização automática falhará e o TokenExpiredHandler será invocado.
Registrar um PFEntityTokenExpiredEventHandler é recomendado para todos os títulos e é essencial para títulos do GDK que dão suporte a suspensão e retomada. Sem esse manipulador, seu jogo não tem como se recuperar de um token expirado.

Registrando o TokenExpiredHandler

Use PFEntityRegisterTokenExpiredEventHandler para se registrar em um retorno de chamada e PFAuthenticationReLoginWith*Async para se autenticar novamente quando o token expirar.

GDK: suspensão, retomada e Quick Resume

Nas plataformas do GDK (consoles XBOX e Windows com o GDK), um jogo pode ficar suspenso por um longo período, como quando o jogador muda para outro jogo e depois volta por meio do Quick Resume. Durante a suspensão, o token de entidade pode expirar. Como nenhum código é executado durante a suspensão, a atualização periódica em segundo plano do SDK não consegue manter o token ativo.

O que acontece na retomada

Quando seu jogo é retomado, o SDK detecta imediatamente o estado retomado e verifica o token de entidade. Ele não espera o próximo ciclo de atualização periódica. Se o token tiver expirado durante a suspensão:
  1. O SDK detecta o token expirado.
  2. O retorno de chamada TokenExpiredHandler é invocado.
  3. Seu jogo deve chamar PFAuthenticationReLoginWith*Async no manipulador para obter um novo token.
A verificação do token na retomada é disparada assim que a conectividade de rede é restaurada. Se a rede demorar um pouco para ser reinicializada após a retomada, o SDK aguardará a conectividade antes de verificar o token. Nenhuma verificação de token é perdida.

Atualização transparente

Se você quiser que seu jogo saiba quando o SDK atualiza automaticamente o token de entidade do jogador, pode se registrar em um retorno de chamada. Esse manipulador é invocado quando o SDK atualiza com êxito um token que estava perto de expirar; nenhuma ação é necessária do seu jogo.

Cancelar o registro dos manipuladores

Ao desligar o PlayFab, ou quando quiser parar de receber os retornos de chamada de expiração e atualização de tokens, chame a função de cancelamento de registro apropriada.

Referência

Documentação de referência da API
Última modificação em 8 de outubro de 2026