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

このガイドは、古い 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 が共存します。移行するには:

古い参照を削除: PlayFab.Services.Cpp、PlayFab.Party.Cpp、およびその他の個別 SDK 拡張機能への参照を削除します。
統合参照を追加: 新しい PlayFab 統合 SDK を参照するか、include/library パスを統合された場所に更新します。
将来を見据える: 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))

認証の移行手順

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

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

PlayFab Core

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

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

PlayFab Services

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

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

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

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

初期化の変更

v1 の初期化:

PartyManager& partyManager = PartyManager::GetSingleton();
PartyError err = partyManager.Initialize("YOUR_PLAYFAB_TITLE_ID");

v2 の初期化:

PartyManager& partyManager = PartyManager::GetSingleton();

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

PartyError err = partyManager.Initialize(&partyInitConfig);

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

v1 のアプローチ:

PartyLocalUser* localUser = nullptr;
PartyError err = partyManager.CreateLocalUser(entityId, titlePlayerEntityToken, &localUser);

v2 のアプローチ:

PartyLocalUser* localUser = nullptr;
PartyError err = partyManager.CreateLocalUser(entityHandle, &localUser);

Party の移行手順

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

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

移行の影響: 小規模な変更が必要コア概念 (Lobby、マッチメイキング Ticket) は同じですが、関数は文字列ではなくエンティティハンドルを期待するようになりました。

Lobby 操作の変更

v1 のアプローチ:

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

v2 のアプローチ:

HRESULT hr = PFMultiplayerJoinLobbyWithEntityHandle(pfmHandle, entityHandle, connectionString, &joinConfig, nullptr, &lobby);

Multiplayer の移行手順

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

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

コードの更新

インクルードパスの更新: 統合 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 は最終的に非推奨となる

次のステップ

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

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

​変更の概要

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

​GDK ユーザー向け

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

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

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

​トークン管理の変更

​認証の移行手順

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

​PlayFab Core

​PlayFab Services

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

​初期化の変更

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

​Party の移行手順

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

​Lobby 操作の変更

​Multiplayer の移行手順

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

​コードの更新

​テスト チェックリスト

​一般的な問題と解決策

​移行のメリット

​コードの簡素化

​改善された相互運用性

​将来性

​次のステップ