> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Tratando a expiração de tokens

> Trate a expiração de tokens de entidade do PlayFab, a atualização de tokens em segundo plano e o novo login manual no SDK para C, incluindo os fluxos de suspensão e retomada do GDK.

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**](/pt-BR/services/playfab/api-references/c/pfentity/functions/pfentityregistertokenrefreshedeventhandler) (consulte [Atualização transparente](#transparent-refresh)).

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

<Info>
  Registrar um [**PFEntityTokenExpiredEventHandler**](/pt-BR/services/playfab/api-references/c/pfentity/functions/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.
</Info>

### Registrando o TokenExpiredHandler

Use [**PFEntityRegisterTokenExpiredEventHandler**](/pt-BR/services/playfab/api-references/c/pfentity/functions/pfentityregistertokenexpiredeventhandler) para se registrar em um retorno de chamada e **PFAuthenticationReLoginWith\*Async** para se autenticar novamente quando o token expirar.

```cpp theme={null}
    PFRegistrationToken registrationTokenExpired{};
    hr = PFEntityRegisterTokenExpiredEventHandler(nullptr, nullptr, [](void* ctx, PFEntityKey const* entityKey)
    {
        PFAuthenticationLoginWithXUserRequest request{};
        request.createAccount = true;
        request.user = user; // An XUserHandle obtained from XUserAddAsync

        XAsyncBlock async{};
        HRESULT hr = PFAuthenticationReLoginWithXUserAsync(GlobalState()->entityHandle, &request, &async); // This assumes the entity handle was stored in the game's global state
        hr = XAsyncGetStatus(&async, true); // This is doing a blocking wait for completion, but you can use the XAsyncBlock to set a callback instead for async style usage

        // After login we could potentially get back a new player entity with a new entity key
        PFEntityKey const* pEntityKey{};
        std::vector<char> entityKeyBuffer;
        size_t size{};
        hr = PFEntityGetEntityKeySize(GlobalState()->entityHandle, &size); // Add your own error handling when FAILED(hr) == true

        entityKeyBuffer.resize(size);
        hr = PFEntityGetEntityKey(GlobalState()->entityHandle, entityKeyBuffer.size(), entityKeyBuffer.data(), &pEntityKey, nullptr);
    }, &registrationTokenExpired);
```

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

<Note>
  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.
</Note>

<a id="transparent-refresh" />

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

```cpp theme={null}
    PFRegistrationToken registrationTokenRefreshed{};
    hr = PFEntityRegisterTokenRefreshedEventHandler(nullptr, nullptr, [](void* ctx, PFEntityKey const* entityKey, const PFEntityToken* newToken)
    {
        // Perform any logging or other desired actions on token refresh
    }, &registrationTokenRefreshed);
```

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

```cpp theme={null}
    PFEntityUnregisterTokenExpiredEventHandler(registrationTokenExpired);
    PFEntityUnregisterTokenRefreshedEventHandler(registrationTokenRefreshed);
```

## Referência

[Documentação de referência da API](/pt-BR/services/playfab/api-references/c/pfauthentication/pfauthentication_members)


## Related topics

- [Tratando erros do PlayFab](/pt-BR/services/playfab/sdks/c/errors.md)
- [Identificadores de entidade](/pt-BR/services/playfab/sdks/c/entity-handles.md)
- [Início rápido GDK](/pt-BR/services/playfab/sdks/c/quickstart-gdk.md)
- [Declarações de tokens de segurança dos serviços do XBOX](/pt-BR/services/xbox-services/fundamentals/s2s-auth-calls/service-authentication/security-tokens/live-token-claims.md)
- [Autenticação dos serviços do XBOX para serviços de título](/pt-BR/services/xbox-services/fundamentals/s2s-auth-calls/service-authentication/live-title-service-authentication.md)