友達とゲームをしたり、オンラインで新しいプレイヤーに会ったりすることは、多くのオンラインサービスの重要な部分です。Epic Online Services (EOS) SDK では、「Friends (フレンド) インターフェース」 を使用してログイン ユーザーのフレンド リストを取得します。
フレンド リストはオンライン サービスのサーバーによって格納され、フレンドが追加または削除されたり、フレンドがゲームで自分の情報が使用されることを許可したり、その許可を取り消したりすると、セッション中に変更されます。
フレンド リストのクエリが正常に完了すると、フレンド インターフェースではローカル キャッシュを作成します。このローカル キャッシュは他のすべてのフレンド インターフェース関数で使用されます。さらに、この SDK では、フレンドの削除、招待の受け入れ、ゲームで自分の情報が使用されることに対する許可をフレンドが取り消すなど、フレンド リストに変更が生じるイベントに関する通知をバックエンドから受信します。
フレンド インターフェースを使用するには、お使いの製品で Epic アカウント サービス (EAS) が有効になっており、フレンド リスト のデータにアクセスするための ユーザーからの許可 を得る必要があります。EAS は Developer Portal 上で有効にすることができます。詳細は「Epic のドキュメント」を参照してください。
フレンド リストを取得してキャッシュする
ユーザーのフレンド リストを取得するには、EOS_HFriends ハンドルが必要です。このハンドルは、Platform (プラットフォーム) インターフェース の関数である EOS_Platform_GetFriendsInterface を使用して取得することができます。このハンドルは、フレンド インターフェースの関数がログイン ユーザーのフレンド リストにアクセスするために必要です。Friends Interface 関数は、ログインしているユーザーのフレンドリストにアクセスするために、このハンドルを必要とします。EOS_Friends_QueryFriends は、少なくとも一度はゲームをプレイし、同意を得たフレンドのみを返すことに注意してください。同意は、プレイヤーが Epic Account Services(EAS) を使用してアプリケーションにログインし、EAS が彼らのアカウント データにアクセスすることを許可したときに与えられます。
ユーザーのフレンド リストを処理する最初のステップは、EOS_Friends_QueryFriendsOptions データ構造体を指定して EOS_Friends_QueryFriends を呼び出すことです。この呼び出しにより、最新バージョンのユーザーのフレンド リストをローカル キャッシュにダウンロードされます。完了時には、EOS_Friends_QueryFriends コールバック関数を呼び出します。
EOS_Friends_QueryFriends 呼び出しを実行するには、次のように EOS_Friends_QueryFriendsOptions 構造体を作成して初期化します。
| プロパティ | 値 |
|---|---|
ApiVersion | EOS_FRIENDS_QUERYFRIENDS_API_LATEST |
LocalUserId | フレンド リストを取得する対象のログイン ユーザーの EOS_EpicAccountId。 |
フレンド インターフェース ハンドル、EOS_Friends_QueryFriendsOptions 構造体、およびコールバック情報を関数に渡します。EOS_HPlatform ハンドルがティックしている場合、操作が終了すると、指定したコールバックが実行されます。
コールバックが実行されたら、EOS_Friends_QueryFriendsCallbackInfo 構造体の ResultCode フィールドを確認すると、操作が成功したか、失敗したかを判断できます。成功コードは、SDK によってサーバーから最新のデータがキャッシュされ、いつでもデータを調査できることを示します。
フレンド リストを調べる
EOS_Friends_QueryFriends の呼び出しに成功したら、デベロッパーはローカル キャッシュを使用して次の便利な関数を実行できます。
EOS_Friends_GetFriendsCountを呼び出してリストのフレンドの人数を特定する。EOS_Friends_GetFriendAtIndexを呼び出して各フレンドのEOS_EpicAccountIdを取得する。
この関数によって返された EOS_EpicAccountId を User Info Interface に渡すことで、ユーザーに関する追加情報を取得できます。
EOS_Friends_GetStatusを呼び出してソーシャル リレーションシップの現在のステータスを特定する。この関数は次の 4 ついずれかの値を返します。
| 値 | 説明 |
|---|---|
EOS_FS_NotFriends | ユーザーがフレンドではない。 |
EOS_FS_InviteSent | ローカル ユーザーが他のユーザーにフレンド招待を送信した。 |
EOS_FS_InviteReceived | 他のユーザーがローカル ユーザーにフレンド招待を送信した。 |
EOS_FS_Friends | ユーザーがフレンドである。 |
フレンド リストは、新しいプレイヤーとの出会いなどのゲーム内イベント、およびユーザーが別のシステムからアカウントを変更するなどのゲーム外イベントの両方から、いつでも変更が可能です。ゲームでは、プレイヤーがログインするたびに何度も EOS_Friends_QueryFriends を呼び出す必要はありません。ただし、プレイヤーがログアウトしてから再ログインした場合は、そのフレンド リストをもう一度クエリする必要があります。フレンド リストのゲームのローカル コピーを最新の状態に維持するには、フレンド ステータスの更新通知をサブスクライブします。
フレンド ステータスの更新をサブスクライブする
フレンドのステータスが変更されたときに通知を受け取るには、次のパラメータを指定して EOS_Friends_AddNotifyFriendsUpdate を呼び出します。
| パラメータ | 説明 |
|---|---|
Options | EOS_Friends_AddNotifyFriendsUpdateOptions 構造体。唯一のパラメータとして ApiVersion を含みます。 |
Callback | EOS_Friends_OnFriendsUpdateCallback に一致する有効なコールバック関数。 |
このコールバック関数はフレンドが更新を取得すると呼び出されます。このコールバックは次のパラメータを含む EOS_Friends_OnFriendsUpdateInfo 構造体を受け取ります。
| パラメータ | 説明 |
|---|---|
LocalUserId | フレンドに関する更新を受け取るローカル ユーザーの EOS_EpicAccountId。 |
TargetUserId | ステータスが更新されるユーザーの EOS_EpicAccountId。 |
PreviousStatus | ターゲット ユーザーのステータスの更新前の値。 |
CurrentStatus | ターゲット ユーザーのステータスの更新後の値。 |
EOS_Friends_AddNotifyFriendsUpdate は EOS_NotificationId を返します。これは、通知が不要になったら、通知のサブスクライブの解除に使用する必要のある専用のハンドルです。失敗した場合、この関数は、結果コード EOS_INVALID_NOTIFICATIONID を返します。
フレンド ステータスの更新のサブスクライブを解除するには、関数 EOS_Friends_RemoveNotifyFriendsUpdate を使用します。この関数では、サブスクリプション中に受け取った通知 ID を受け入れます。
フレンド リストを管理する
このセクションで説明されているフレンドリスト管理 API は、現在 Windows PC 上のゲームでのみ使用できます。
Nintendo Switch、PlayStation、Xbox コンソール プラットフォームのサポートが計画されています。 macOS、Linux、Android、iOS のさsポートが計画されています。
EOS_Friends_SendInvite SDK API の呼び出しにより、ローカル ユーザーはゲーム内の他のユーザーにフレンド リクエストを送信できるようにすることができます。受信したフレンドの招待を承認または拒否するゲーム UI 機能を実装するには、EOS_Friends_AcceptInvite と EOS_Friends_RejectInvite のSDK API をそれぞれに使用することができます。
これらの API は、まだ利用できないプラットフォームでは EOS_NotImplemented を返します。