Each Epic Online Services (EOS) user account has a unique identifier that the service uses internally to refer to the account. The User Info Interface bridges the gap between the user's account identifier and information about the user, such as display name, country and preferred language, and so on. You can retrieve this information for both remote users and logged-in, local users.
To protect user privacy, the User Info Interface will only provide the display name and unique account identifier for remote users.
To use the User Info Interface, your product must have Epic Account Services (EAS) active, and must obtain user consent to access User data. You can activate EAS on the Developer Portal, or learn more in Epic's documentation. Without EAS and user consent, you will still be able to initialize the EOS SDK and the User Info Interface, but all User Info Interface function calls to the back-end service will fail.
Retrieving and Caching User Info
To access the User Info Interface, you need an EOS_HUserInfo handle, which you can acquire from the Platform Interface through the EOS_Platform_GetUserInfoInterface function. User Info Interface functions require this handle to access user information.
The online service's servers store user information, and this information can change without notification as people make updates to their accounts. The User Info Interface automatically creates a local cache that you can update by querying the server when you need the latest information.
Retrieving User Info by Account Identifier
The first step in dealing with user info is to call EOS_UserInfo_QueryUserInfo with an EOS_UserInfo_QueryUserInfoOptions data structure. This will download the most up-to-date version of a user's information into the local cache. To perform the EOS_UserInfo_QueryUserInfo call, create and initialize an EOS_UserInfo_QueryUserInfoOptions with the following field values:
| Property | Value |
|---|---|
ApiVersion | EOS_USERINFO_QUERYUSERINFO_API_LATEST |
LocalUserId | The EOS_EpicAccountId of the logged-in user |
TargetUserId | The EOS_EpicAccountId of the user whose information you want to retrieve |
Pass the User Info Interface handle, the EOS_UserInfo_QueryUserInfoOptions structure, and your callback information to the function. Provided that the EOS_HPlatform handle is ticking, the callback you provided to EOS_UserInfo_QueryUserInfo will run when the operation finishes.
When your callback executes, you can check the ResultCode field of the EOS_UserInfo_QueryUserInfoCallbackInfo 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.
Retrieving User Info by Display Name
Almost every function in the EOS SDK deals with users based on their unique account identifiers, but players should only ever know their friends' account names. EOS_UserInfo_QueryUserInfoByDisplayName provides a way to map a display name to its account identifier. Call EOS_UserInfo_QueryUserInfoByDisplayName with an EOS_UserInfo_QueryUserInfoByDisplayNameOptions data structure to retrieve and cache the most up-to-date version of a user's information. When calling this function, initialize your EOS_UserInfo_QueryUserInfoByDisplayNameOptions structure as follows:
| Property | Value |
|---|---|
ApiVersion | EOS_USERINFO_QUERYUSERINFOBYDISPLAYNAME_API_LATEST |
LocalUserId | The EOS_EpicAccountId of the logged-in user |
DisplayName | The display name of the user whose information you want to retrieve |
Pass the User Info Interface handle, the EOS_UserInfo_QueryUserInfoByDisplayNameOptions 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. In your callback function, you can check the ResultCode field of the EOS_UserInfo_QueryUserInfoByDisplayNameCallbackInfo structure to determine whether the operation succeeded or failed. On success, the SDK has cached the latest data from the server, which you can examine at any time.
Retrieving User Info by External Account
EOS_UserInfo_QueryUserInfoByExternalAccount provides a way to query for user info using information about a linked external account. Call EOS_UserInfo_QueryUserInfoByExternalAccount with an EOS_UserInfo_QueryUserInfoByExternalAccountOptions data structure to retrieve and cache the most up-to-date version of a user's information. When calling this function, initialize your EOS_UserInfo_QueryUserInfoByExternalAccountOptions structure as follows:
| Property | Value |
|---|---|
ApiVersion | EOS_USERINFO_QUERYUSERINFOBYEXTERNALACCOUNT_API_LATEST |
LocalUserId | The EOS_EpicAccountId of the logged-in user |
ExternalAccountId | The external account ID of the user whose information you want to retrieve |
AccountType | The account type of the external user info to query. See EOS_EExternalCredentialType for a list of all available methods. |
Pass the User Info Interface handle, the EOS_UserInfo_QueryUserInfoByExternalAccountOptions 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. In your callback function, you can check the ResultCode field of the EOS_UserInfo_QueryUserInfoByExternalAccountCallbackInfo structure to determine whether the operation succeeded or failed, along with a TargetUserId (the EOS_EpicAccountId of the player whose information has been retrieved). On success, the SDK has cached the latest data from the server, which you can examine at any time.
Multiple external account IDs may be queried in a frame. These queries will be batched, and individual calls to each EOS_UserInfo_QueryUserInfoByExternalAccountCallback function will be made when the entire batch has been completed.
Examining User Information
Once you have retrieved information about a specific user from the online service, you can request a copy of that data with the EOS_UserInfo_CopyUserInfo function. This function requires an EOS_UserInfo_CopyUserInfoOptions structure with the following information:
| Property | Value |
|---|---|
ApiVersion | EOS_USERINFO_COPYUSERINFO_API_LATEST |
LocalUserId | The EOS_EpicAccountId of the logged-in user. |
TargetUserId | The EOS_EpicAccountId of the user whose information you want. This can be the same as LocalUserId. |
Pass the User Info Interface handle, the EOS_UserInfo_CopyUserInfoOptions structure, and the address of a pointer to an EOS_UserInfo data structure. If the cache contains information about the target user, the EOS_UserInfo data structure will be filled in, and the function will return EOS_Success.
This function makes a copy of the data to prevent user information that your game code is accessing from being deleted by the User Info Interface. This means that your code owns the memory, and is responsible for freeing it. Failure to do so will cause a memory leak. You can free EOS_UserInfo objects by passing them to the EOS_UserInfo_Release function.
Most of the information in the EOS_UserInfo structure will be empty for non-local users. This is to ensure that EOS does not provide personally identifiable information (PII) to other users. The DisplayName and UserId fields are the only ones the EOS SDK guarantees to populate.
Display Names and Nicknames
Users can set nicknames for other users. If a user assigns a nickname to another user it will be contained in the Nickname field, and it will only be available to the user who created it. If a nickname is not assigned then the Nickname field will be null.
We recommend that you be considerate of users and avoid replicating nicknames, as the local user may consider their assigned nicknames to be private information.
External User Info
As of 1.6, it's possible to retrieve data about a user's linked accounts, known in the SDK as their external user info. The interface exposes several API functions to assist with the retrieval of this data. Note that like a user's EOS_UserInfo, a user's EOS_UserInfo_ExternalUserInfo will not be cached and available for retrieval unless you have previously made a call to EOS_UserInfo_QueryUserInfo.
EOS_UserInfo_GetExternalUserInfoCount returns the number of external user info entries available to be retrieved for a target user.
EOS_UserInfo_CopyExternalUserInfoByIndex outputs the external user info of a target user given an index.
EOS_UserInfo_CopyExternalUserInfoByAccountType outputs the external user info of a target user given the specific type of the external account you want to retrieve info for. In 1.6, the supported account types for external user info are EOS_EAT_PSN, EOS_EAT_XBL, EOS_EAT_NINTENDO, and EOS_EAT_STEAM.
EOS_UserInfo_CopyExternalUserInfoByAccountId outputs the external user info of a target user given the account id of their external account.
Remember to call EOS_UserInfo_ExternalUserInfo_Release when you are finished using an external user info entry to prevent leaks.