Friends インターフェース

フレンド リストの取得、他のユーザーの追加や削除を行うためのインターフェースです。

2022年10月より前に Epic Account Services が統合されたコンソールでゲームを起動する予定の場合、リリース計画を調整するために eas-on-console-beta@epicgames.com までご連絡ください。

友達とゲームをしたり、オンラインで新しいプレイヤーに会ったりすることは、多くのオンラインサービスの重要な部分です。Epic Online Services (EOS) SDK では、「Friends (フレンド) インターフェース」 を使用してログイン ユーザーのフレンド リストを取得します。

フレンド リストはオンライン サービスのサーバーによって格納され、フレンドが追加または削除されたり、フレンドがゲームで自分の情報が使用されることを許可したり、その許可を取り消したりすると、セッション中に変更されます。

フレンド リストのクエリが正常に完了すると、フレンド インターフェースではローカル キャッシュを作成します。このローカル キャッシュは他のすべてのフレンド インターフェース関数で使用されます。さらに、この SDK では、フレンドの削除、招待の受け入れ、ゲームで自分の情報が使用されることに対する許可をフレンドが取り消すなど、フレンド リストに変更が生じるイベントに関する通知をバックエンドから受信します。

フレンド インターフェースを使用するには、お使いの製品で Epic アカウント サービス (EAS) が有効になっており、フレンド リスト のデータにアクセスするための ユーザーからの許可 を得る必要があります。EAS は Developer Portal 上で有効にすることができます。詳細は「Epic のドキュメント」を参照してください。EAS が有効になっておらず、ユーザーの許可を得ていない場合でも、EOS SDK とフレンド インターフェースを初期化することはできます。ただし、バックエンド サービスへのすべてのフレンド インターフェースの関数呼び出しが失敗します。

フレンド リストを取得してキャッシュする

ユーザーのフレンド リストを取得するには、EOS_HFriends ハンドルが必要です。このハンドルは、Platform (プラットフォーム) インターフェース の関数である EOS_Platform_GetFriendsInterface を使用して取得することができます。このハンドルは、フレンド インターフェースの関数がログイン ユーザーのフレンド リストにアクセスするために必要です。

ユーザーのフレンド リストを処理する最初のステップは、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 はすべて非推奨になりました。次のいずれかの関数を呼び出すと、結果として EOS_NotImplemented が返されます。

  • EOS_Friends_AcceptInvite

  • EOS_Friends_RejectInvite

  • EOS_Friends_SendInvite

  • EOS_Friends_DeleteFriend

Epic Games では、SDK でこの機能を再度利用できるようにする方法について検討しています。これらの API が再び利用可能になった場合は、このドキュメントが更新され、該当する API の使用方法と予期されるビヘイビアが記載されます。