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

# 處理權杖到期

> 在 C SDK 中處理 PlayFab 實體權杖到期、背景權杖重新整理和手動重新登入，包括 GDK 暫停與繼續流程。

PlayFab Services SDK 包含背景權杖重新整理機制，可協助讓玩家的工作階段保持作用中。了解此機制的運作方式，以及您的遊戲何時需要採取動作非常重要，尤其是支援暫停與繼續的 Game Development Kit (GDK) 遊戲。

## 自動權杖重新整理的運作方式

SDK 會執行背景工作者，定期檢查玩家的實體權杖。如果權杖**仍然有效但即將到期** (距離到期一小時以內)，SDK 會使用原始登入呼叫中的認證自動重新驗證。如果重新整理成功，權杖會以透明的方式更新，而 **PFEntityHandle** 會繼續有效。您的遊戲不需要採取任何動作。

您可以註冊 [**PFEntityRegisterTokenRefreshedEventHandler**](/zh-TW/services/playfab/api-references/c/pfentity/functions/pfentityregistertokenrefreshedeventhandler) 回呼來觀察這些無聲的權杖重新整理 (請參閱[透明重新整理](#transparent-refresh))。

## 您的遊戲何時必須處理權杖到期

在某些情況下，SDK **無法**自動重新整理權杖：

* **權杖已經到期。** 自動重新整理只有在權杖仍然有效時才能運作。如果權杖已完全到期 (例如，在長時間的暫停/繼續週期之後)，SDK 不會嘗試自動重新登入，而是透過 **TokenExpiredHandler** 通知您的遊戲。
* **原始登入認證已不再有效。** 如果原本提供給登入要求的控制代碼或權杖已不再有效，自動重新整理就會失敗，並叫用 **TokenExpiredHandler**。

<Info>
  建議所有遊戲都註冊 [**PFEntityTokenExpiredEventHandler**](/zh-TW/services/playfab/api-references/c/pfentity/functions/pfentitytokenexpiredeventhandler)，而對於支援暫停與繼續的 GDK 遊戲來說，這是**不可或缺**的。如果沒有此處理常式，您的遊戲將無法從已到期的權杖中復原。
</Info>

### 註冊 TokenExpiredHandler

使用 [**PFEntityRegisterTokenExpiredEventHandler**](/zh-TW/services/playfab/api-references/c/pfentity/functions/pfentityregistertokenexpiredeventhandler) 註冊回呼，並在權杖到期時使用 **PFAuthenticationReLoginWith\*Async** 重新驗證。

```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：暫停、繼續和快速繼續

在 GDK 平台 (XBOX 主機和使用 GDK 的 Windows) 上，遊戲可能會暫停很長一段時間，例如當玩家切換至另一款遊戲，之後再透過快速繼續返回時。在暫停期間，實體權杖可能會到期。由於暫停期間不會執行任何程式碼，SDK 的定期背景重新整理無法讓權杖保持有效。

### 繼續時會發生什麼事

當您的遊戲繼續時，SDK 會**立即**偵測到繼續狀態並檢查實體權杖，而不會等候下一個定期重新整理週期。如果權杖在暫停期間到期：

1. SDK 會偵測到已到期的權杖。
2. 叫用 **TokenExpiredHandler** 回呼。
3. 您的遊戲必須從處理常式呼叫 **PFAuthenticationReLoginWith\*Async**，以取得新的權杖。

<Note>
  網路連線一旦恢復，就會觸發繼續時的權杖檢查。如果網路在繼續後需要一點時間重新初始化，SDK 會等候連線恢復後再檢查權杖。不會遺漏任何權杖檢查。
</Note>

<a id="transparent-refresh" />

## 透明重新整理

如果您想讓遊戲知道 SDK 何時自動重新整理玩家的實體權杖，可以註冊回呼。當 SDK 成功重新整理即將到期的權杖時，就會叫用此處理常式，您的遊戲不需要採取任何動作。

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

## 取消註冊處理常式

關閉 PlayFab 時，或當您想要停止接收權杖到期和重新整理回呼時，請呼叫適當的取消註冊函式。

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

## 參考

[API 參考文件](/zh-TW/services/playfab/api-references/c/pfauthentication/pfauthentication_members)


## Related topics

- [實體控制代碼](/zh-TW/services/playfab/sdks/c/entity-handles.md)
- [XBOX 服務驗證](/zh-TW/services/xbox-services/fundamentals/s2s-auth-calls/service-authentication/live-xbox-live-authentication.md)
- [GDK 快速入門](/zh-TW/services/playfab/sdks/c/quickstart-gdk.md)
- [處理 PlayFab 錯誤](/zh-TW/services/playfab/sdks/c/errors.md)
- [PlayFab 支援的語言](/zh-TW/services/playfab/sdks/languages/index.md)