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
構造体を作成して初期化します。
プロパティ |
値 |
---|---|
|
|
|
フレンド リストを取得する対象のログイン ユーザーの |
フレンド インターフェース ハンドル、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
を呼び出します。
パラメータ |
説明 |
---|---|
|
|
|
|
このコールバック関数はフレンドが更新を取得すると呼び出されます。このコールバックは次のパラメータを含む EOS_Friends_OnFriendsUpdateInfo
構造体を受け取ります。
パラメータ |
説明 |
---|---|
|
フレンドに関する更新を受け取るローカル ユーザーの |
|
ステータスが更新されるユーザーの |
|
ターゲット ユーザーのステータスの更新前の値。 |
|
ターゲット ユーザーのステータスの更新後の値。 |
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 の使用方法と予期されるビヘイビアが記載されます。