- ネットワーク記述子 の知識
- 有効な PlayFab
title_player_accountエンティティ トークン の所有 - 招待 識別子 の知識
- 指定された招待にトークンの PlayFab エンティティ ID が存在すること、または指定された招待が オープン招待 であること
招待
招待 (PartyInvitation) は、ネットワーク内のオブジェクトで、ユーザーにネットワークへのアクセスを許可します。招待はネットワークの有効期間を通じて 作成 および 取り消し できます。招待には、作成者、一意の 識別子、取り消し可能性設定、および任意の ユーザーのセット (エンティティ ID として指定) があります。ネットワークには、0 個を含む任意の数のアクティブな招待を持つことができます。ネットワークは常に初期招待とともに作成されます。
招待の有効期間
招待は、作成されたときから取り消されるまでアクティブです。作成
招待を作成するには 2 つの方法があります。1 つ目の方法は、PartyManager::CreateNewNetwork() を呼び出すことです。ネットワークに参加するには招待が必要なため、ネットワークが作成されるときに 1 つ存在する必要があります。この招待は初期招待と呼ばれ、以下に説明する 特別なプロパティを持ちます。2 つ目の方法は、PartyNetwork::CreateInvitation() を呼び出すことです。
招待の作成者は、PartyNetwork::CreateInvitation() を呼び出すときに指定されるユーザーです。初期招待には作成者がありません。
招待が作成される (または、アクティブな初期招待でネットワークに参加する) と、PartyInvitationCreatedStateChange が生成されます。
初期招待は、ネットワークの作成者にネットワークへの参加を暗黙的に許可しません。オープン招待 が使用されている場合を除き、作成者のエンティティ ID をユーザー リストに含めるようにしてください。
列挙
アクティブな招待の列挙はPartyNetwork::GetInvitations() を使用して行います。ローカル デバイス上で作成された招待と、まだアクティブな場合は初期招待のみを列挙できます。
取り消し
招待はPartyNetwork::RevokeInvitation() を呼び出して取り消されます。招待を取り消せるのはその作成者のみです。ただし、初期招待の例外があり、これは任意のユーザーが取り消すことができます。加えて、招待を作成したユーザーがネットワークから削除されると、招待は自動的に取り消されます。
招待が取り消されると、その招待を見ることができたすべてのデバイスで PartyInvitationRevokedStateChange が生成されます。
初期招待が取り消されると、再作成することはできません。その識別子は新しい招待で再利用できますが、その新しい招待は初期招待の特別なプロパティを持ちません。
招待の取り消しは、すでにネットワークに参加しているデバイスとユーザーには影響を与えません。ユーザーまたはデバイスをネットワークから削除するには、
PartyNetwork::KickUser() または PartyNetwork::KickDevice() を使用します。これらのメソッドはまだ実装されていないことに注意してください。招待の構成
招待の構成は、作成時にPartyInvitationConfiguration 構造体を使用して指定されます。
識別子
各招待には、ネットワーク内で一意にそれを識別する識別子があります。招待を作成するときに識別子が指定されていない場合、Party が識別子を割り当てます。PartyManager::CreateNewNetwork() の呼び出しでは、割り当てられた識別子が out パラメーターで返され、ネットワークの作成が完了したときに PartyCreateNewNetworkCompletedStateChange でも報告されます。PartyManager::CreateInvitation() の呼び出しでは、招待の作成が完了したときに、割り当てられた識別子は invitation out パラメーターまたは PartyCreateInvitationCompletedStateChange の invitation フィールドから取得できます。
招待識別子は一意である必要がありますが、招待が取り消された後は、その識別子を新しい招待の作成時に再利用できます。
初期招待とその他の招待
招待には 1 種類しかありませんが、PartyManager::CreateNewNetwork() の呼び出しによって作成される初期招待は、後で PartyNetwork::CreateInvitation() を介して作成される招待と少し異なります。違いは以下の表にまとめられています。
初期招待以外の招待は、プライバシー上の理由から他のデバイスから隠されます。これがなぜ重要かの例については、フレンド リストの使用パターン を参照してください。
ユーザーとオープン招待
招待には、title_player_account エンティティ ID として指定される 0 人以上のユーザーが含まれます。招待にユーザーが含まれる場合、その招待はそれらのユーザーにのみネットワークへの参加アクセスを許可します。しかし、招待にユーザーが含まれない場合、それはオープン招待です。オープン招待の識別子を使用して、任意のユーザーがネットワークに参加できます。
ゲーム コンソールなどのマルチユーザー デバイスでは、正しい招待を正しいユーザーで使用するようにしてください。各招待で指定されるユーザーによっては、デバイス上の異なるユーザーが PartyNetwork::AuthenticateLocalUser() を介してネットワークにユーザーを認証するときに異なる招待を使用する必要がある場合があります。
不変性
招待が作成されると、その構成は変更できません。ただし、招待が取り消された後は、同じ識別子で異なる構成の別の招待を作成できます。動的な単一招待の使用パターン を参照してください。使用パターン
PlayFab Party の招待はシンプルですが柔軟です。ネットワークへの異なるアクセス モデルを実現するために、それらを使う効果的な方法は多数あります。オープン ネットワーク
オープン ネットワークは、理解と実装が最もシンプルです。ネットワーク記述子と招待識別子を持つ誰もが参加できるようにします。PartyManager::CreateNewNetwork() を呼び出すときに initialInvitationConfiguration パラメーターに null を渡すことで、オープン ネットワークを作成します。オープン招待の識別子は out パラメーターとして返されます。ネットワークの作成が完了したら、ユーザーが参加できるようにネットワーク記述子と招待識別子を共有します。
必要に応じて、いつでも初期招待を取り消すことでネットワークをクローズできます。
静的なユーザー リスト
バックフィルなしでマッチメイキングによって作成されたゲームなど、事前にすべてのプレイヤーがわかっているゲームの場合、静的なユーザー リストが簡単で効果的なパターンです。これにより、ゲームが始まる前に識別されたユーザーのみがネットワークに参加できます。PartyInvitationConfiguration 構造体を作成し、その entityIds フィールドに既知のユーザーを追加します。この構造体を PartyManager::CreateNewNetwork() に渡します。ネットワークの作成が完了したら、ユーザーが参加できるようにネットワーク記述子と招待識別子を共有します。
1 対 1 の招待
既存のユーザーが個別に他のユーザーを招待するゲームでは、1 対 1 の招待パターンが効果的でシンプルです。PartyInvitationConfiguration 構造体を作成し、その entityIds フィールドに作成者のみを追加します。この構造体を PartyManager::CreateNewNetwork() に渡します。作成者がネットワークに接続したら、必要に応じて初期招待を取り消すことができます。あるいは、ネットワークの作成者は オープン ネットワーク を作成し、接続後すぐに初期招待を取り消すことができます。
ネットワークに参加するべきユーザーごとに別の PartyInvitationConfiguration 構造体を作成します。これらの構造体を PartyNetwork::CreateInvitation() に渡して招待を作成します。各ユーザーに固有の招待識別子とともにネットワーク記述子を共有します。ユーザーが参加するにつれて、このパターンを繰り返して他のユーザーを招待できます。
ユーザーが参加すると、必要に応じてそのユーザーに固有の招待を取り消すことができます。
フレンド リスト
1 対 1 の招待 を作成せずに、各ユーザーのフレンドが容易に参加できるようにしたいゲームでは、ユーザーの全フレンド リストを含む招待を作成できます。 ネットワークに接続した後、各ユーザーはPartyInvitationConfiguration 構造体を作成し、その entityIds フィールドにそれぞれのソーシャル プラットフォームのフレンドを追加します。この構造体を PartyNetwork::CreateInvitation() に渡し、フレンドとネットワーク記述子と招待識別子を共有します。ユーザーのフレンド リストが変わったときは、招待を取り消し、新しいフレンド リストで新しい招待を作成する必要があります。
動的な単一招待
多くのゲームには、指定されたネットワークに参加すべきユーザーを制御するロビーまたはその他の外部サービスがあります。ネットワークを外部サービスと同期させるには、動的な単一招待パターンを使用できます。このパターンは、既知の識別子を持つ単一の招待を使用します。 このパターンには 2 つのバリエーションがあります。外部サービスがネットワークの招待を管理する単一のユーザーを選択するか、すべてのユーザーに招待の管理を試行するように依頼します。どちらの場合も、ネットワークに含まれるべきユーザーのセットが変わるたびに、外部サービスはユーザーに通知し、ユーザーは現在の招待を取り消して、新しい完全なユーザー セットを含む同じ既知の識別子で新しい招待を作成しようとします。単一ユーザーによる管理
現在の招待の取り消しと新しい招待の作成の責任を持つユーザーを 1 人にすることで、招待の所有権を予測可能にします。ただし、外部サービスは以下を行う必要があります。- 招待を管理するユーザーを選択する。
- 前のユーザーがネットワークを離れたときに新しいユーザーを選択する。
すべてのユーザーによる管理
すべてのユーザーに招待管理を試行させると、招待の所有権が予測できなくなりますが、外部サービスが単一のユーザーを選択する必要がなくなります。代わりに、各デバイス上のユーザーは以下を行います。- 現在の招待の取り消しを試みる。初期招待の場合、すべてのユーザーがこれを試みますが、1 人だけが成功します。他の招待の場合、招待は他のユーザーには見えないため、前回の招待を作成したユーザーのみが取り消しを試行できます。
- 新しい招待の作成を試みる。招待は一意の識別子を持つ必要があるため、1 人のユーザーのみが成功します。招待は他のデバイスでは見えないため、そのユーザーは自分が新しい招待の所有者であることを他のユーザーに通知する必要があります。
- 現在の招待の作成者が作成側のデバイスを離れたとき、すべてのユーザーが再び新しい招待の作成を試みなければなりません。
招待を取り消して同じ識別子で新しい招待を作成するとき、招待識別子が無効になる小さな時間ウィンドウがあります。このアプローチを使用している場合、
PartyNetwork::AuthenticateLocalUser() の呼び出しが妥当な待機期間の後に失敗した場合、再試行する必要があります。ローリング オープン招待
ロビーまたは他の外部サービスが指定されたネットワークに参加すべきユーザーを制御するゲームでは、動的な単一招待 パターンの代替として、ローリング オープン招待パターンがあります。このパターンでは、常に単一のオープン招待があります。以前に参加を許可されていたユーザーが外部サービスのユーザー リストから削除されたときはいつでも、招待は取り消され、新しい識別子で再作成されます。招待識別子はパスワードのように機能し、同様に保護する必要があります。このパターンは以下の手順で実装できます。- 外部サービスがネットワークを作成するデバイスを選択し、使用する招待識別子を指定する。
- 外部サービスがネットワークに参加すべき他のすべてのユーザーに招待識別子を送信する。
- 新しいユーザーがネットワークに参加すべきとき、外部サービスがそのユーザーに現在の招待識別子を共有する。
- 現在の招待を持つユーザーが参加を許可されなくなったとき、外部サービスは以下を行うことで「パスワードを変更」する必要があります。
- 新しい招待識別子を選択する。
- 1 人またはすべてのユーザーに、現在の招待を取り消し、選択した招待識別子で新しい招待を作成するように要求する。単一ユーザーによる管理とすべてのユーザーによる管理の議論については、動的な単一招待 を参照してください。
- ネットワークへの参加を許可されるべきすべてのユーザーに新しい招待識別子を共有する。