Playing games with your friends and meeting new players online are important parts of many online services. The Epic Online Services (EOS) SDK uses the Friends Interface to retrieve the friends list for a logged-in player.
Friend lists are stored by the online service's servers, and can change during a session as friends are added or removed or if friends grant or revoke consent for the game to use their information.
Upon successful completion of a friends list query, the Friends Interface creates a local cache that is used by all other Friends Interface functions. Additionally the SDK receives notifications from the backend about events that lead to mutations of the friends list, such as a friend being removed, an invite being accepted or a friend revoking their consent to have their information used by the game.
To use the Friends Interface, your product must have Epic Account Services (EAS) active, and must obtain user consent to access Friends List data. You can activate EAS on the Developer Portal, or learn more in Epic's documentation.
Retrieving and Caching the Friends List
To retrieve a player's friends list, you will need an EOS_HFriends handle. You can acquire this handle through the Platform Interface function, EOS_Platform_GetFriendsInterface. Friends Interface functions require this handle to access your logged-in user's friends list. It is important to note that EOS_Friends_QueryFriends will only return friends who have played the game at least once and has given their consent. Consent is given when a player logs in to an application using Epic Account Services (EAS) and allows EAS access to their account data.
The first step in dealing with a player's friends list is to call EOS_Friends_QueryFriends with an EOS_Friends_QueryFriendsOptions data structure. This will download the most up-to-date version of a player's friends list into the local cache, then invoke your EOS_Friends_QueryFriends callback function upon completion.
To perform the EOS_Friends_QueryFriends call, create and initialize an EOS_Friends_QueryFriendsOptions structure as follows:
| Property | Value |
|---|---|
ApiVersion | EOS_FRIENDS_QUERYFRIENDS_API_LATEST |
LocalUserId | The EOS_EpicAccountId of the logged-in player whose friends list you want to retrieve. |
Pass the Friends Interface handle, the EOS_Friends_QueryFriendsOptions structure, and your callback information to the function. Provided that the EOS_HPlatform handle is ticking, the callback you provided will run when the operation finishes.
When your callback executes, you can check the ResultCode field of the EOS_Friends_QueryFriendsCallbackInfo structure to determine whether the operation succeeded or failed. A success code indicates that the SDK has cached the latest data from the server, which you can examine at any time.
Examining the Friends List
After a successful call to EOS_Friends_QueryFriends, developers can perform the following useful functions using the local cache:
- Determine the number of friends on the list by calling
EOS_Friends_GetFriendsCount. - Retrieve the
EOS_EpicAccountIdof each friend by callingEOS_Friends_GetFriendAtIndex.
The EOS_EpicAccountId returned by this function can be passed to the User Info Interface to retrieve additional information about the user.
- Determine the current status of the social relationship by calling
EOS_Friends_GetStatus. This function returns one of four values:
| Value | Description |
|---|---|
EOS_FS_NotFriends | The users are not friends. |
EOS_FS_InviteSent | The local user has sent a friend invite to the other user. |
EOS_FS_InviteReceived | The other user has sent a friend invite to the local user. |
EOS_FS_Friends | The users are friends. |
Friends lists can change at any time, both from in-game events like meeting new players, and from out-of-game events like the player modifying the account from a separate system. Games do not need and should not call EOS_Friends_QueryFriends more than once per login of a player. However, after a player logs out, their friends list must be queried again if they log in again. To keep a game's local copy of the friends list up to date, subscribe to friend status update notifications.
Subscribing to Friend Status Updates
To receive a notification when friend's status changes call EOS_Friends_AddNotifyFriendsUpdate with following parameters:
| Parameter | Description |
|---|---|
Options | An EOS_Friends_AddNotifyFriendsUpdateOptions structure, with ApiVersion as its only parameter. |
Callback | A valid callback function consistent with EOS_Friends_OnFriendsUpdateCallback. |
The callback function will be called when a friend gets an update. The callback receives an EOS_Friends_OnFriendsUpdateInfo structure with the following parameters:
| Parameter | Description |
|---|---|
LocalUserId | The EOS_EpicAccountId of the local user receiving the update about their friends. |
TargetUserId | The EOS_EpicAccountId of the user whose status is being updated. |
PreviousStatus | The previous value of the target user's status. |
CurrentStatus | The updated value of the target user's status. |
EOS_Friends_AddNotifyFriendsUpdate will return an EOS_NotificationId, which is a special handle that must be used to unsubscribe from notifications when they are no longer needed. In the event of a failure, it will return a result code of EOS_INVALID_NOTIFICATIONID.
To unsubscribe from friend status updates, use the function EOS_Friends_RemoveNotifyFriendsUpdate, which that accepts notification ID received during subscription.
Managing the Friends List
The friends list management APIs described in this section are currently only available for games on Windows PC.
Support for Nintendo Switch, PlayStation, and Xbox console platforms is planned. Support for macOS, Linux, Android and iOS is planned.
You can allow the local user to send friend requests to other users in the game, by calling the EOS_Friends_SendInvite SDK API. To implement game UI functionality for accepting or rejecting any received friend invites, you can use the EOS_Friends_AcceptInvite and EOS_Friends_RejectInvite SDK APIs respectively.
These APIs will return EOS_NotImplemented on platforms without yet the availability.