Friends Interface

Interface to retrieve friends list, or to add or remove other players.

5 mins to read

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 signed-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 have given their consent. Consent is either give upon game purchase or when a player signs 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:

PropertyValue
ApiVersionEOS_FRIENDS_QUERYFRIENDS_API_LATEST
LocalUserIdThe 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_EpicAccountId of each friend by calling EOS_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:
ValueDescription
EOS_FS_NotFriendsThe users are not friends.
EOS_FS_InviteSentThe local user has sent a friend invite to the other user.
EOS_FS_InviteReceivedThe other user has sent a friend invite to the local user.
EOS_FS_FriendsThe users are friends.

Note: The EOS_AS_FriendsManagement scope controls whether the signed-in player can make changes or view pending changes to their social graph (for example, their friend status). By default, this scope isn't enabled. The EOS SDK returns only the Friends (EOS_FS_Friends) and Not Friends (EOS_FS_NotFriends) statuses to your game. The Social Overlay handles pending invites for you, which includes the remaining Invite Sent (EOS_FS_InviteSent) and Invite Received (EOS_FS_InviteReceived) statuses. While these statuses are available in the header, you do not need to handle these statuses in your game.

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:

ParameterDescription
OptionsAn EOS_Friends_AddNotifyFriendsUpdateOptions structure, with ApiVersion as its only parameter.
CallbackA 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:

ParameterDescription
LocalUserIdThe EOS_EpicAccountId of the local user receiving the update about their friends.
TargetUserIdThe EOS_EpicAccountId of the user whose status is being updated.
PreviousStatusThe previous value of the target user's status.
CurrentStatusThe 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.