Skip to main content
PlayFab Services SDK 包含一个后台令牌刷新机制,帮助保持玩家会话的活动状态。理解此机制如何工作——以及游戏何时需要采取行动——非常重要,尤其是对支持挂起和恢复的游戏开发工具包(GDK)游戏而言。

自动令牌刷新如何工作

SDK 运行一个后台工作程序,定期检查玩家的实体令牌。如果令牌仍然有效但即将过期(在到期前一小时内),SDK 会使用原始登录调用的凭据自动重新进行身份验证。如果此刷新成功,令牌会被透明地更新,PFEntityHandle 继续有效。你的游戏无需采取任何行动。 你可以通过注册 PFEntityRegisterTokenRefreshedEventHandler 回调来观察这些静默的令牌刷新(请参阅 透明刷新)。

何时你的游戏必须处理令牌过期

在某些情况下,SDK 无法自动刷新令牌:
  • 令牌已经过期。 自动刷新仅在令牌仍然有效时才有效。如果令牌完全过期——例如,在长时间挂起/恢复周期之后——SDK 不会尝试自动重新登录。相反,它会通过 TokenExpiredHandler 通知你的游戏。
  • 原始登录凭据不再有效。 如果最初提供给登录请求的句柄或令牌不再有效,自动刷新会失败并调用 TokenExpiredHandler
建议所有游戏都注册 PFEntityTokenExpiredEventHandler,对于支持挂起和恢复的 GDK 游戏而言更是必不可少。没有此处理程序,你的游戏无法从过期的令牌中恢复。

注册 TokenExpiredHandler

使用 PFEntityRegisterTokenExpiredEventHandler 注册回调,并使用 PFAuthenticationReLoginWith*Async 在令牌过期时重新进行身份验证。

GDK:挂起、恢复和 Quick Resume

在 GDK 平台上(XBOX 主机和带有 GDK 的 Windows),游戏可能被长时间挂起,例如当玩家切换到另一个游戏,稍后通过 Quick Resume 返回时。在挂起期间,实体令牌可能过期。由于挂起期间没有代码运行,SDK 的周期性后台刷新无法保持令牌存活。

恢复时会发生什么

当你的游戏恢复时,SDK 会立即检测到恢复状态并检查实体令牌。它不会等待下一个周期性刷新周期。如果令牌在挂起期间过期:
  1. SDK 检测到过期的令牌。
  2. 调用 TokenExpiredHandler 回调。
  3. 你的游戏必须从该处理程序调用 PFAuthenticationReLoginWith*Async 以获取新令牌。
恢复时的令牌检查在网络连接恢复后立即触发。如果恢复后网络需要一些时间重新初始化,SDK 会等待连接性再检查令牌。不会丢失任何令牌检查。

透明刷新

如果你希望游戏在 SDK 自动刷新玩家实体令牌时得到通知,可以注册回调。当 SDK 成功刷新一个即将过期的令牌时,会调用此处理程序——你的游戏无需采取任何行动。

取消注册处理程序

当关闭 PlayFab 或想停止接收令牌过期和刷新回调时,调用相应的取消注册函数。

参考

API 参考文档
最后修改于 2026年8月25日