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

# PlayFab スタンドアロン SDK v1 から統合 SDK v2 への移行

> PlayFab タイトルを v1 スタンドアロン SDK から v2 統合 SDK に移行します。プロジェクト レイアウト、認証、トークン管理の変更を扱います。

このガイドは、古い PlayFab v1 SDK から新しい PlayFab 統合 SDK v2 への移行を支援します。統合 SDK は、以前は別々だった SDK (Core、Services、Party、Multiplayer) を、より優れた相互運用性と簡素化された認証を備えた単一の統合ソリューションに集約します。

## 変更の概要

PlayFab 統合 SDK v2 では、次の主要な改善が導入されています:

* **統合アーキテクチャ**: すべての PlayFab サービス (Core、Services、Party、Multiplayer、GameSave) が単一の SDK に統合されている
* **簡素化された認証**: 1 回のログインで、エンティティ ハンドルを介してすべての PlayFab サービスにアクセスできる
* **自動トークン管理**: 手動のトークン更新やエンティティ ID 管理は不要
* **改善された相互運用性**: 異なる PlayFab サービス間のシームレスな通信
* **合理化されたプロジェクト構造**: 複数の個別パッケージではなく単一の SDK インストール

## プロジェクト構造の変更

### GDK ユーザー向け

**従来のレイアウト (GDK 2504 以前):**

* 各 SDK コンポーネントに対する個別の拡張機能
* 個別の include およびライブラリ フォルダー: PlayFab.Services.Cpp、PlayFab.Party.Cpp、PlayFab.Multiplayer.Cpp
* 各サービスは GDK 内で異なる ExtensionLibrary 名を持っていた
* GitHub からさまざまな PlayFab サービスの複数のダウンロードが必要だった

**新しいレイアウト (GDK 2510 以降):**

* 単一の統合 PlayFab SDK
* プラットフォームごとに整理された構造 (xbox、windows などのサブフォルダー)
* すべてのヘッダーが 1 つの includes フォルダーに統合 (Core、Services、Multiplayer、Party、GameSave)
* 統合された lib フォルダー内の結合ライブラリ

#### プロジェクト参照の更新

移行期間中 (GDK 2510) は、古い SDK と新しい SDK が共存します。移行するには:

1. **古い参照を削除**: PlayFab.Services.Cpp、PlayFab.Party.Cpp、およびその他の個別 SDK 拡張機能への参照を削除します。
2. **統合参照を追加**: 新しい PlayFab 統合 SDK を参照するか、include/library パスを統合された場所に更新します。
3. **将来を見据える**: Microsoft は将来の GDK リリース (2026 年までに可能性あり) で古いフォルダーを削除するため、プロジェクト ファイルをそれに応じて更新してください。

### GitHub/スタンドアロン ユーザー向け

* 複数の SDK ダウンロードを単一の統合 SDK パッケージに置き換えます。
* プロジェクト パスを更新し、新しいプラットフォームごとに整理されたフォルダー構造を使用します。

## 認証とエンティティ処理

エンティティとエンティティ トークンの概念は両バージョンに存在しますが、使い方は v2 で簡素化されました。

### トークン管理の変更

**PlayFab スタンドアロン SDK (v1) のアプローチ:**

* `PFAuthenticationGetEntityTokenAsync` を使用した手動のトークン取得
* トークンの有効期限が切れたときの手動更新
* エンティティ ID とトークン文字列を他のサービスに渡す (例: `partyManager.CreateLocalUser(entityId, titlePlayerEntityToken, &localUser)`)

**PlayFab 統合 SDK (v2) のアプローチ:**

* Core SDK による自動トークン管理
* 有効期限前のバックグラウンド トークン更新
* 他のサービスに `PFEntityHandle` を直接渡す (例: `partyManager.CreateLocalUser(entityHandle, &localUser)`)

### 認証の移行手順

1. **手動トークン管理の削除**: PlayFab トークンを手動で取得またはチェックするコードを削除します。
2. **エンティティ ハンドルの保存**: ログインからの `PFEntityHandle` を保持し、すべての PlayFab サービスで使用します。
3. **サービス呼び出しの更新**: エンティティ ID/トークン パラメーターをエンティティ ハンドルに置き換えます。
4. **再認証の処理**: 再認証シナリオには `PFAuthenticationReLogin*Async` API を使用します。

## コンポーネント別の破壊的な API 変更

### PlayFab Core

**移行の影響**: 必要な変更は最小限

* ほとんどの Core サービス呼び出しは変更なし
* インクルード パスを統合 SDK ヘッダーを指すように更新

### PlayFab Services

**移行の影響**: 必要な変更は最小限

* ほとんどの Service 呼び出しは変更なし
* インクルード パスを統合 SDK ヘッダーを指すように更新

### PlayFab Party (ネットワーキング/ボイス)

**移行の影響**: 小規模な変更が必要

#### 初期化の変更

**v1 の初期化:**

```cpp theme={null}
PartyManager& partyManager = PartyManager::GetSingleton();
PartyError err = partyManager.Initialize("YOUR_PLAYFAB_TITLE_ID");
```

**v2 の初期化:**

```cpp theme={null}
PartyManager& partyManager = PartyManager::GetSingleton();

PartyInitializationConfiguration partyInitConfig = {};
partyInitConfig.titleId = "YOUR_PLAYFAB_TITLE_ID";
partyInitConfig.audioTaskQueue = nullptr;
partyInitConfig.networkingTaskQueue = nullptr;

PartyError err = partyManager.Initialize(&partyInitConfig);
```

#### ローカル ユーザー作成の変更

**v1 のアプローチ:**

```cpp theme={null}
PartyLocalUser* localUser = nullptr;
PartyError err = partyManager.CreateLocalUser(entityId, titlePlayerEntityToken, &localUser);
```

**v2 のアプローチ:**

```cpp theme={null}
PartyLocalUser* localUser = nullptr;
PartyError err = partyManager.CreateLocalUser(entityHandle, &localUser);
```

#### Party の移行手順

1. **初期化の更新**: シンプルな `PartyManager::Initialize()` 呼び出しを構成構造体アプローチに置き換えます。
2. **トークン取得の削除**: Party のためにエンティティ ID/トークンを手動で取得するコードを削除します。
3. **エンティティ ハンドルの受け渡し**: 文字列パラメーターの代わりに `PFEntityHandle` を直接使用します。
4. **トークン更新ロジックの削除**: Party トークンを定期的にチェックまたは更新するコードを削除します。
5. **依存関係の更新**: `PartyManager::Initialize()` の前に PlayFab Core が初期化されていることを確認します。
6. **XBOX 固有の呼び出しの削除**: XBOX 上で `PartyXblManagerInitialize()` を汎用の `PartyInitialize()` に置き換えます。

### PlayFab Multiplayer (ロビーとマッチメイキング)

**移行の影響**: 小規模な変更が必要

コア概念 (Lobby、マッチメイキング Ticket) は同じですが、関数は文字列ではなくエンティティ ハンドルを期待するようになりました。

#### Lobby 操作の変更

**v1 のアプローチ:**

```cpp theme={null}
PFEntityKey newMember{ entityId, entityType };
HRESULT hr = PFMultiplayerJoinLobby(pfmHandle, &newMember, connectionString, &joinConfig, nullptr, &lobby);
```

**v2 のアプローチ:**

```cpp theme={null}
HRESULT hr = PFMultiplayerJoinLobbyWithEntityHandle(pfmHandle, entityHandle, connectionString, &joinConfig, nullptr, &lobby);
```

#### Multiplayer の移行手順

1. **関数呼び出しの更新**: PlayFab ID とエンティティ トークン パラメーターを `PFEntityHandle` に置き換えます。
2. **認証手順の削除**: 個別の「Authenticate Multiplayer」呼び出しを削除します。
3. **明示的な初期化**: `PFMultiplayerInitialize()` および場合によっては `PFMultiplayerStartProcessing()` を呼び出します。
4. **マッチメイキングの更新**: マッチメイキング チケットの作成時にエンティティ ハンドルを使用します。

## 一般的な移行チェックリスト

### コードの更新

* [ ] **インクルード パスの更新**: 統合 SDK のインクルード ディレクトリを指すようにします
* [ ] **ライブラリ リンクの更新**: 個別のライブラリではなく統合ライブラリをリンクします
* [ ] **非推奨関数の削除**: `PartyManager::CreateLocalUserWithEntityType` などの削除された関数への呼び出しを削除します
* [ ] **手動トークン管理の置換**: トークン キャッシングと更新ロジックを削除します
* [ ] **初期化順序の更新**: 他のサービスの前に PlayFab Core が初期化されるようにします

### テスト チェックリスト

移行後は、各サブシステムを検証してください:

* [ ] **認証**: ログインが有効なエンティティ ハンドルを返す
* [ ] **Lobby 操作**: ロビーの作成/参加が正しく動作する
* [ ] **Party ネットワーキング**: プレイヤーがマシン間で接続および通信できる
* [ ] **エラー処理**: すべての PlayFab 呼び出しがエラーを適切に処理する
* [ ] **マルチユーザー シナリオ**: 該当する場合、複数のローカル ユーザーが動作する

### 一般的な問題と解決策

**パラメーターの欠落に関するコンパイラ エラー**:

* 関数シグネチャが `PFEntityHandle` を要求するように変更されたか確認します
* 文字列 ID の代わりにエンティティ ハンドルを渡していることを確認します

**ランタイム認証の失敗**:

* 他のサービスの前に PlayFab Core が初期化されていることを確認します
* Party/Multiplayer でローカル ユーザーを作成する前にログインが完了していることを確認します

**パフォーマンスの低下**:

* まれですが、v2 がパフォーマンス クリティカルなコード パスで問題を引き起こしていないか確認します

## 移行のメリット

### コードの簡素化

* **複雑さの低減**: v1 のサービス分離のための回避策コードを削除
* **統合されたエラー処理**: すべての PlayFab サービスで一貫したエラー報告を使用
* **一元化された認証**: すべての PlayFab 機能に対する 1 つのログイン フロー

### 改善された相互運用性

* **シームレスな統合**: 新しい PlayFab 機能を追加する際のセットアップが最小限
* **より良いマルチユーザー サポート**: 統合 SDK は複数のローカル ユーザーをより効率的に処理
* **一貫したエンティティ モデル**: すべてのサービスで同じ認証アプローチ

### 将来性

* **アクティブな開発**: v2 はアクティブにメンテナンスされているバージョン
* **新機能**: 将来の PlayFab 機能は統合 SDK を対象とする
* **長期サポート**: v1 SDK は最終的に非推奨となる

## 次のステップ

1. **プロジェクト構造の更新**: 統合 SDK レイアウトに移行します
2. **認証のリファクタリング**: エンティティ ハンドル ベースのアプローチを実装します
3. **十分にテスト**: すべての PlayFab 機能が正しく動作することを検証します
4. **コードのクリーンアップ**: 非推奨の v1 の回避策と手動トークン管理を削除します
5. **パフォーマンスの監視**: 移行がパフォーマンス問題を引き起こしていないことを確認します

追加のヘルプについては、お使いのプラットフォームに固有の PlayFab 統合 SDK ドキュメントとサンプルを参照してください。


## Related topics

- [PlayFab SDK 製品](/ja-jp/services/playfab/sdks/sdk-products.md)
- [PlayFab 統合 SDK](/ja-jp/services/playfab/sdks/unified-sdk/overview.md)
- [スタンドアロン SDK の概要](/ja-jp/services/playfab/sdks/sdk-overview.md)
- [保護された SDK とサンプルへのアクセスを申請する](/ja-jp/services/playfab/sdks/request-access-for-sdks-samples.md)
- [October 2025 GDK での Game Saves の実装](/ja-jp/services/playfab/player-progression/game-saves/october-2025-gdk-changes.md)