> ## 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 はバックグラウンドワーカーを実行し、プレイヤーのエンティティ トークンを定期的にチェックします。トークンが **まだ有効だが有効期限が近づいている** (有効期限まで 1 時間以内) 場合、SDK は最初のサインイン呼び出しで指定された認証情報を使用して自動的に再認証を行います。この更新が成功すると、トークンは透過的に更新され、**PFEntityHandle** は引き続き有効です。ゲーム側からのアクションは必要ありません。

これらの静かなトークン更新を監視するには、[**PFEntityRegisterTokenRefreshedEventHandler**](/services/playfab/api-references/c/pfentity/functions/pfentityregistertokenrefreshedeventhandler) コールバックを登録します ([透過的更新](#transparent-refresh) を参照)。

## ゲームがトークンの有効期限を処理する必要がある場合

SDK がトークンを自動的に更新 **できない** シナリオがあります:

* **トークンがすでに期限切れの場合。** 自動更新はトークンがまだ有効な場合にのみ機能します。トークンが完全に期限切れになっている場合 (たとえば、長時間のサスペンド/再開サイクルの後)、SDK は自動再ログインを試みません。代わりに、**TokenExpiredHandler** を介してゲームに通知します。
* **元のサインイン認証情報がもはや有効でない場合。** サインイン リクエストで元々提供されたハンドルまたはトークンがもはや有効でない場合、自動更新は失敗し、**TokenExpiredHandler** が呼び出されます。

<Info>
  すべてのタイトルで [**PFEntityTokenExpiredEventHandler**](/services/playfab/api-references/c/pfentity/functions/pfentitytokenexpiredeventhandler) の登録を推奨します。サスペンドと再開をサポートする GDK タイトルでは **必須** です。このハンドラーがない場合、ゲームは期限切れのトークンから復旧する手段がありません。
</Info>

### TokenExpiredHandler の登録

[**PFEntityRegisterTokenExpiredEventHandler**](/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>

## 透過的更新

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 リファレンス ドキュメント](/services/playfab/api-references/c/pfauthentication/pfauthentication_members)


## Related topics

- [XBOX services 認証](/ja-jp/services/xbox-services/fundamentals/s2s-auth-calls/service-authentication/live-xbox-live-authentication.md)
- [タイトル サービス向け XBOX services 認証](/ja-jp/services/xbox-services/fundamentals/s2s-auth-calls/service-authentication/live-title-service-authentication.md)
- [PFEntityToken](/ja-jp/services/playfab/api-references/c/pfentity/structs/pfentitytoken.md)
- [PlayFab がサポートする言語](/ja-jp/services/playfab/sdks/languages/index.md)
- [PlayFab Party リリース ノート](/ja-jp/services/playfab/multiplayer/networking/release-notes.md)