Connect Interface

The Connect Interface handles connections between users' accounts under different identity providers.

The Connect Interface provides access to the heart of the Epic Online Services (EOS) ecosystem, a user's identity within all the services provided. It is an abstraction of an external identity provider's account for use inside our services. Identity providers include Epic Games and Steam, and as that list expands, it will be possible to connect a user on any supported platform to their singular account within each individual application.

Each organization will have the ability to associate one or more external user accounts with a single account per application.

Managing Accounts

Typically, you will want to log a user in using a set of external credentials. If the user already exists for this product, an access token will be granted that lasts for a set period of time (currently one hour). The game will be notified prior to the token expiration and will be required to refresh the existing token given a valid external credential at that time.

Because we do not control the access permissions of the external provider, this interface is not intended to implicitly refresh tokens or otherwise grant lengthy access. We simply verify the user is still valid with the external account provider and extend the time the user is able to access our services. The external account provider is also expected to have authority over access to the application.

Click to enlarge image.

Access to services available via this account will require account identification via the EOS_ProductUserId data structure. All interfaces will clearly indicate this usage and type safety should be assured. It is separate from EOS_EpicAccountId, which is associated with the authentication interface provided for Epic Games accounts. An Epic Games account is not required to work with this service.

Logging In

To login, call EOS_Connect_Login with the EOS_Connect_LoginOptions containing external credentials from a supported platform.

In the case of Epic Games accounts, retrieving the current auth token from EOS_Auth_CopyUserAuthToken and setting the EOS_EExternalCredentialType to EOS_ECT_EPIC is sufficient.

Pass the EOS_HConnect handle, your EOS_Connect_LoginOptions structure, and your callback information to the function. Provided that the EOS_HPlatform handle is ticking, the callback you provided will execute when the operation finishes.

If the result is successful, the application may proceed to access additional interfaces that require authentication. If the user does not exist, the login API will return a EOS_InvalidUser result. Additionally, a EOS_ContinuanceToken will be included. This token provides details about the login attempt and will be required during the next steps in the login flow.

At this juncture, a decision needs to be made. Ask the user if they have a secondary set of external credentials known to be registered with the service (see Linking an External Account), or if they'd like to create a new account (see Creating a User).

Auth Token Refresh Notification

A callback function provided to EOS_Connect_AddNotifyAuthExpiration will run whenever an existing access token is about to expire. This should give the application enough time to acquire another external access token and provide it to the SDK via the EOS_Connect_Login function each time.
Use the EOS_Connect_RemoveNotifyAuthExpiration function to stop listening for these notifications.

Status Change Notification

To assure that your application knows whenever a user's authentication status has changed, the Connect Interface provides a callback for such notifications.

The callback function you provide to EOS_Connect_AddNotifyUserLoginStatusChanged will run whenever a local user's authentication status changes. This should only occur if the expiration notification is ignored, the external provider credentials are unable to refresh the access token, or the access was revoked explicitly by the backend service for some administrative reason.

Use the EOS_Connect_RemoveNotifyUserLoginStatusChanged function to stop listening for notifications.

Checking Current Authentication Status

To check the player's current status on demand, use the EOS_Connect_GetLoginStatus function. This function determines authentication status based on the most recent communication with the online service, so the result is returned instantly and does not use a callback function.

Creating a User

Creating a user will generate a new product user ID for the user given the external credentials used during login. It is almost always necessary to prompt the user and see if there is an alternate way to login before creating a new user. This will reduce confusion and account/user merging issues in cross-platform situations.

If the application intends to create a new product user ID for the user, then simply call EOS_Connect_CreateUser with the EOS_Connect_CreateUserOptions containing the EOS_ContinuanceToken from the previous call to EOS_Connect_Login.

Pass the EOS_HConnect handle, your EOS_Connect_CreateUserOptions structure, and your callback information to the function. Provided that the EOS_HPlatform handle is ticking, the callback you provided will execute when the operation finishes.

Linking an External Account

If during the application login flow, it is determined that the user is able to login with a secondary set of external credentials, store the EOS_ContinuanceToken from the first login call, reattempt to login via EOS_Connect_Login, and once successfully logged in, immediately call EOS_Connect_LinkAccount. This will associate the two external accounts to the one product user ID. It is possible to link more than two accounts as the capabilities of our services grow.

If the intent of the application is to link a new external account with an existing product user ID, then simply call EOS_Connect_LinkAccount with the EOS_Connect_LinkAccountOptions containing the EOS_ContinuanceToken from the previous call to EOS_Connect_Login and the product user ID for the user logged in with a successful call to EOS_Connect_Login.

Pass the EOS_HConnect handle, your EOS_Connect_LinkAccountOptions structure, and your callback information to the function. Provided that the EOS_HPlatform handle is ticking, the callback you provided will execute when the operation finishes.

You can search EOS Connect users by their external account IDs or using the product user ID through the Account Linking dashboard in the Developer Portal. As the keychain of a player's linked external accounts is managed at the Organization level, the Account Linking dashboard can be found next to the Organization management menu items. Through the Account Linking dashboard, you will be able to find players and your customer support will be able to help to remove account linkings by player requests. You can also use this dashboard to remove your EOS Connect user or any linked accounts during SDK integration testing.

Along with this, we will provide web REST APIs for developers to integrate EOS user management into their existing internal dashboards.

Using Device ID

In cases where an application believes that users may not yet be invested enough to create a new account or link an existing account, an application may create a new persistent pseudo-account using the EOS Connect Device ID feature. This feature allows an application to create a persistent access credential for a local user without using any external login credentials. This allows the backend services to remember the current user on the local device across game sessions. The Device ID feature is used especially on mobile personal devices to allow automatically logging in a user without prompting for account credentials, as well as allowing to start playing the game without immediately requiring a user login to persist the game progression data.

However, as the Device ID is not tied to a real user account and can only be used to uniquely identify the local device, it is highly recommended to ask the user to link an external authentication method to their Device ID account once a user has progressed through some early progression milestone to prevent losing the credential and thus their account.

Without eventually linking the Device ID account with a real user identity, all progress and game data will be permanently lost should something happen to the device itself. The EOS SDK stores the Device ID credential locally in the keychain of the currently logged in user of the local device. If the local user profile is reset or otherwise lost, it is not possible to recover a lost Device ID after that.

To create a new Device ID, an application must call the EOS_Connect_CreateDeviceId function with a valid EOS_Connect_CreateDeviceIdOptions structure containing the user's DeviceModel. This call will eventually trigger a callback to the function bound to the EOS_Connect_OnCreateDeviceIdCallback. If a new Device ID was successfully created and stored in the keychain for the logged in user of the local device, the ResultCode parameter in the callback parameters will be set to EOS_EResult::EOS_Success. If an existing Device ID was already present, EOS_EResult::EOS_DuplicateNotAllowed is returned. Otherwise, the ResultCode parameter identifies the reason for the operation failure.

To login the local user with their unique Device ID, call the EOS_Connect_Login API with the EOS_EExternalCredentialType::EOS_ECT_DEVICEID_ACCESS_TOKEN external credential type. As the SDK manages the stored Device ID credential automatically, the Token parameter of the input EOS_Connect_Credentials struct must be set to NULL. However, as the Device ID is not tied to a real user identity, the EOS_Connect_UserLoginInfo input struct needs to be provided with a valid DisplayName for the user.

To link the local Device ID with a real external user account, first have the game login the local user normally using the Device ID credential type. Then, ask the user to login with a real identity and after EOS_Connect_Login returns back with a ContinuanceToken, link the external account using the EOS_Connect_Link API to associate the local device with the user's real account. This will allow logging in the user automatically each time the game is started, as the Device ID can still be used as intended to automatically login the user without prompting for external user account credentials.

You may also delete the Device ID for the current user profile of the local device by calling the EOS_Connect_DeleteDeviceId API. The deletion operation is a permanent and nonrecoverable operation. However, it is always possible to create a new Device ID and link it with an existing external user account to restore the automated login functionality.

Retrieving External Account Mappings

Other interfaces will expect the EOS_ProductUserId for remote or otherwise external users; say a list of friends or players on the same server. It is possible to convert external user account identifiers to the SDK's representation via the mapping API.

EOS_Connect_QueryExternalAccountMappings is an asynchronous call that will convert external account ids to the SDK representation. Simply set the EOS_EExternalAccountType and provide a contiguous list of external account ids in string form.

Pass the EOS_HConnect handle, your EOS_Connect_QueryExternalAccountMappingsOptions structure, and your callback information to the function. Provided that the EOS_HPlatform handle is ticking, the callback you provided will execute when the operation finishes.

Once the callback has successfully returned, it is possible to retrieve the mappings via EOS_Connect_GetExternalAccountMapping. This function takes the EOS_EExternalAccountType as before and returns a single EOS_ProductUserId for each call that provides an external account ID in string form.

Retrieving Product User ID Mappings

Just as one may retrieve the external mappings for a given product user ID, the converse is also true. EOS_Connect_QueryProductUserIdMappings is an asynchronous call that will convert EOS_ProductUserIds to their external counterpart on a given platform, along with additional account data including the display name and the last login time. Simply provide a contiguous list of product user IDs.

Pass the EOS_HConnect handle, your EOS_Connect_QueryProductUserIdMappingsOptions structure, and your callback information to the function. Provided that the EOS_HPlatform handle is ticking, the callback you provided will execute when the operation finishes.

Once the callback has successfully returned, it is possible to retrieve the mappings via EOS_Connect_GetProductUserIdMapping. This function takes the EOS_EExternalAccountType, an input buffer, and buffer length to fill with the external account ID. If the buffer is too small, the proper size of the buffer will be returned.

Use EOS_Connect_GetProductUserExternalAccountCount to retrieve the number of linked external accounts for a product user.

Use EOS_Connect_CopyProductUserExternalAccountByIndex to fetch information about an external account linked to a product user using the index.

Use EOS_Connect_CopyProductUserExternalAccountByAccountType to fetch information about an external account of a specific type linked to a product user.

Use EOS_Connect_CopyProductUserExternalAccountByAccountId to fetch information about an external account linked to a product user using the account ID.

Use EOS_Connect_CopyProductUserInfo to fetch information about a product user, using the external account that they most recently logged in with as the reference.

If the product user ID does not map to the given external platform, then the data will not be present in the results returned for the above. This means that the user has never connected that external account type to their product user ID.