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

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

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

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

在某些情況下,SDK 無法自動重新整理權杖:
  • 權杖已經到期。 自動重新整理只有在權杖仍然有效時才能運作。如果權杖已完全到期 (例如,在長時間的暫停/繼續週期之後),SDK 不會嘗試自動重新登入,而是透過 TokenExpiredHandler 通知您的遊戲。
  • 原始登入認證已不再有效。 如果原本提供給登入要求的控制代碼或權杖已不再有效,自動重新整理就會失敗,並叫用 TokenExpiredHandler。
建議所有遊戲都註冊 PFEntityTokenExpiredEventHandler,而對於支援暫停與繼續的 GDK 遊戲來說,這是不可或缺的。如果沒有此處理常式,您的遊戲將無法從已到期的權杖中復原。

註冊 TokenExpiredHandler

使用 PFEntityRegisterTokenExpiredEventHandler 註冊回呼,並在權杖到期時使用 PFAuthenticationReLoginWith*Async 重新驗證。

GDK:暫停、繼續和快速繼續

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

繼續時會發生什麼事

當您的遊戲繼續時,SDK 會立即偵測到繼續狀態並檢查實體權杖,而不會等候下一個定期重新整理週期。如果權杖在暫停期間到期:
  1. SDK 會偵測到已到期的權杖。
  2. 叫用 TokenExpiredHandler 回呼。
  3. 您的遊戲必須從處理常式呼叫 PFAuthenticationReLoginWith*Async,以取得新的權杖。
網路連線一旦恢復,就會觸發繼續時的權杖檢查。如果網路在繼續後需要一點時間重新初始化,SDK 會等候連線恢復後再檢查權杖。不會遺漏任何權杖檢查。

透明重新整理

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

取消註冊處理常式

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

參考

API 參考文件
最後修改於 2026年10月8日