The EOS Online Subsytem (OSS) Plugin | Unreal Engine 4.27 Documentation

Epic Online Services (EOS) is an engine-agnostic system that provides a range of cross-platform online features, including: player-centric features such as achievements and leaderboards, commercial features such as the ability to purchase in-game items, and social features such as voice communication and friends lists.

Unreal Engine can help you implement EOS in your project through its Online Subsystem (OSS) plugin, without the need to write code using the EOS SDK directly. The Online Subsystem plugin provides a common interface across all exposed online services in Unreal Engine. To use this feature, developers must register and configure their products with Epic Account Services (EAS), and then enable and configure a few plugins to expose EOS functionality through the OSS interface.

For more information on EAS and EOS, please see the Epic Online Services developer documentation.

Setup

To begin leveraging EOS in your project, you must first enable the EOS OSS plugins. You can find them by going to the Edit menu and selecting Plugins to open the Plugin Browser.

Within the Plugin Browser, locate and enable Online Subsystem EOS and EOS Shared. If you want to add voice chat support through EOS, enable the EOS RTC IVoiceChat plugin as well.

After enabling the plugins, you will need to configure them. Some of the following configuration steps require product-related settings or identifiers received after registering your product with EOS.

If you have not registered your product with EOS, you can register it on the Epic Developer Portal.

EOS Settings

The following settings relate to EOS' platform-specific configuration. For more detail, see the EOS API Reference page about the Platform Options data structure.

Cache Dir: This is the location in which EOS stores temporary data.
Default Artifact Name: Games shipped on the Epic Games Store and that run through the Epic Games Launcher use an artifact name to look up settings data. This field specifies a default name.
Tick Budget in Milliseconds: This setting establishes a per-tick time limit on EOS' operations. You can remove the limit by setting this value to zero.
Enable Overlay: Use this to enable or disable all overlays. Some overlays may be platform-specific, such as the e-commerce overlay which is only valid for titles shipping on the Epic Games Store.
Enable Social Overlay: The social overlay shows information about friends, achievements, and extra authentication steps. You can disable this overlay individually while leaving other overlays enabled. This setting has no effect if Enable Overlay is turned off.
Require Being Launched by Epic Games Store: For titles that ship on the Epic Games Store, activating this setting causes the game to verify ownership before launching, and requires launching through the Epic Games Launcher. If the end user attempts to launch the game using any other method, the game’s process will terminate and relaunch itself through the Epic Games Launcher.

Artifacts: The Epic Games Store supports multiple artifacts for a single product. For example, your product can have separate internal artifacts for development, testing, and for the released version that your customers use. This array contains settings for each named artifact. There must be at least one artifact in the array, and the Default Artifact Name value must match the name of one of the array elements. See Artifact Settings for more information about these settings.

Artifact Settings

Artifact settings that you configure here should match the settings for your registered product. You can find settings for your products on the Developer Portal (requires login).

Artifact Name: This is the name of the artifact. For example, MyGameStaging or MyGameRelease.
Client ID: This ID should start with “xyz” as the first 3 characters.
Client Secret: This is the password that is used to verify your Client ID.
Product ID: The EOS SDK uses this ID to identify your product.
Sandbox ID: The artifact belongs to the sandbox with this ID value. Typically, the product has only a single Sandbox ID.
Deployment ID: Deployment IDs differ for each artifact. For example, if you have MyGameStaging and MyGameRelease artifacts, they will each have their own Deployment IDs.
Encryption Key: When you upload data to an EOS service, this 64-byte hexadecimal string is used to encrypt it. Unlike other settings, EOS does not manage this Encryption Key and it is not stored in your product settings. The key is unique to your game and not known to Epic Games, to protect users’ data privacy.

EOS Plus Plugin Settings

EOS Plus is an experimental OSS plugin that combines the features of the EOS SDK with those of another online platform (such as Xbox Live, PlayStation, Steam, and so on) into a single, crossplay-compatible Online Subsystem.

To use this plugin, you must first register and configure your product in the Developer Portal for each platform you want to support. The platform-specific versions of EOS SDK contain detailed instructions for using the features of the platform they support.

Before using this plugin, you must configure the following settings:

Use Epic Account Services: When enabled, the EOS OSS plugin will use the platform-specific authentication token to sign the user into their Epic Account automatically. This requires that the user has linked their Epic Account to their account from the other platform; if they have not, the logs will report this event as an error. You can redirect the user to the account linking page to complete this process, where they can log in and complete the account linking process on their own through the Accounts tab.
User Cross-platform User IDs: This setting enables EOS Connect features with the platform specific authentication token.
Mirror Stats to EOS: If this option is enabled, EOS Plus will send a duplicate of all Stats information to the EOS OSS plugin.
Mirror Achievements to EOS: If this option is activated, EOS Plus will send a duplicate of all Achievement data to the EOS OSS plugin.
Use Crossplay Sessions: This setting is required to play cross-platform network games. It also makes the EOS Sessions Interface the primary session interface.
Mirror Presence to EAS: This option determines whether the EOS Plus plugin will also send Presence data to the EOS OSS plugin. Presence data is only available when using Epic Account Services.

Project Settings

Once you have set up your product on the Developer Portal and configured the plugins, there are a few settings you need to configure in the project's DefaultEngine.ini file.

Engine Settings

Follow these steps to configure your project to use the Online Subsystem EOS plugin:

In the [OnlineSubsystemEOS] section, verify or add the following line to ensure that the Online Subsystem EOS is enabled:

		bEnabled=true

In the [OnlineSubsystem] section, verify or add the following line to ensure that EOS is your default platform:

		DefaultPlatformService=EOS

In the [/Script/Engine.GameEngine] section, verify or add the following line to ensure that the engine will use the EOS NetDriver:

	+NetDriverDefinitions=(DefName="GameNetDriver",DriverClassName="OnlineSubsystemEOS.NetDriverEOS",DriverClassNameFallback="OnlineSubsystemUtils.IpNetDriver")

If you intend to use EOS' P2P socket functionality for player hosted matches, verify or add the following line to the [/Script/OnlineSubsystemEOS.NetDriverEOS] section:

		bIsUsingP2PSockets=true

Your DefaultEngine.ini file should now contain the following lines within their respective sections:

		[OnlineSubsystemEOS]
		bEnabled=true

		[OnlineSubsystem]
		DefaultPlatformService=EOS

		[/Script/Engine.GameEngine]
		+NetDriverDefinitions=(DefName="GameNetDriver",DriverClassName="OnlineSubsystemEOS.NetDriverEOS",DriverClassNameFallback="OnlineSubsystemUtils.IpNetDriver")

		[/Script/OnlineSubsystemEOS.NetDriverEOS]
		bIsUsingP2PSockets=true

EOS Plus Settings (Optional)

If you want to configure your project to implement crossplay between EOS and another online platform, make these additional modifications:

Verify that the EOS Plus plugin is enabled by looking for the following line in the [OnlineSubsystemEOSPlus] section:

		bEnabled=true

In the [OnlineSubsystem] section, change your default online platform from EOS to EOSPlus, and add the name of the other online platform. In this example, we will use Steam as our second platform. When you are finished, you should have these lines:

		DefaultPlatformService=EOSPlus
		NativePlatformService=Steam

The engine needs to know that EOS and EOSPlus network ID types are compatible in order to enable interaction between the platforms. Add the following lines to the [/Script/OnlineSubsystemUtils.OnlineEngineInterfaceImpl] section:

		+CompatibleUniqueNetIdTypes=EOS
		+CompatibleUniqueNetIdTypes=EOSPlus

Your DefaultEngine.ini file should now contain the following lines within their respective sections. You may also need to replace Steam with a different online platform name:

	[OnlineSubsystemEOSPlus]
	bEnabled=true

	[OnlineSubsystem]
	DefaultPlatformService=EOSPlus
	NativePlatformService=Steam

	[/Script/OnlineSubsystemUtils.OnlineEngineInterfaceImpl]
	+CompatibleUniqueNetIdTypes=EOS
	+CompatibleUniqueNetIdTypes=EOSPlus

The DefaultPlatformService setting in the [OnlineSubsystem] section replaces the value that you set earlier.

EOS Voice Communications

You can configure Lobby sessions to create a linked voice chat room. Users who join the lobby (including the lobby creator) will automatically join the voice chat room. To configure this, set both the FOnlineSessionSettings::bUseLobbiesIfAvailable and FOnlineSessionSettings::bUseLobbiesVoiceChatIfAvailable values to true.

Individual users can control their interaction with voice chat rooms using their IVoiceChatUser interface instances, which you can retrieve using FOnlineSubsystemEOS::GetVoiceChatUserInterface.

The IVoiceChatUser interface enables interaction with local hardware, online chat rooms, and other voice chat users. You can select input or output devices, change volume levels, block or mute specific users, and register for events such as players joining or leaving the channel, starting or stopping talking, and so on.

When using FOnlineSubsystemEOS::GetVoiceChatUserInterface, the system will handle the initializing, connecting, and log in automatically. However, depending on how you integrate IVoiceChat, you can still manually join and leave trusted server channels. Refer to the [Trusted Server Integration] section of the EOSVoiceChat plugin documentation for more information.

The method to process user authentication varies depending on whether the basic OnlineSubsystemEOS Plugin is being used, or if it’s being used along with OnlineSubsystemEOSPlus. There are two methods to start the login process in the Online Identity Interface.

Method	Description
AutoLogin	Requires a local user number to be passed.
Login	Requires a FOnlineAccountCredentials object.

In this next section, you will understand how to get a user logged in using both methods in both of the aforementioned plugins.

Login with OnlineSubsystemEOS

In addition to providing a valid local user number, the Login method also requires a FOnlineAccountCredentials object to be passed. This struct has three fields:

Type
Id
Token

These three fields indicate which method of authentication the OnlineSubsystemEOS Plugin should use, depending on their values. These are examples of how to set up all the different types of authentication:

Account Portal

Type: AccountPortal
Id:
Token:

With this method, a browser window will open when the Login call is made, and the user will be asked to input their epic account information. If the user is already logged in to Epic Games in that browser, they will be asked to accept the access scopes for the product in question. This method does not require Dev Auth Tool to be running.

Developer

Type: Developer
Id: localhost: (where is the port specified in Dev Auth Tool)
Token: CredentialsName

This method requires the EOS Developer Authentication Tool(Dev Auth Tool) to be running. See the following Developer Authenthication Tool.

After setting up the Dev Auth Tool, remember which Port and Credentials Name you used since they will be required to fill the Id and Token fields of the FOnlineAccountCredentials object as indicated above.

This login method will open when the Login call is made, and the user will be asked to input their Epic Ganes account information.

If the user is already logged in to Epic Games in that browser, they will be asked to accept the access scopes for the product in question (this step will only occur the first time a user logs in).

This is the recommended method to use during development using OnlineSubsystemEOS in desktop platforms.

Exchange Code

Type: “ExchangeCode”
Id:
Token: “<exchange code>” (where <exchange code> is the exchange code provided by the Epic Launcher)

This method should only be used if the application is being launched from the Epic Launcher, as it needs the exchange code provided by it. This method does not require Dev Auth Tool to be running and is what you would use with the shipping version of your game.

Login successful

If any of these methods are completed successfully, the login process will end by registering all the necessary EOS notification services (login status, friends and own presence updates, and auth refresh) and triggering the following registered delegates:

Method	Description
OnLoginComplete	parameters include if the login was successful, and the UniqueNetId for the newly authenticated user.
OnLoginStatusChanged	parameters correspond with previous and current login status, and the UniqueNetId for the newly authenticated user.

AutoLogin with OnlineSubsystemEOS

For the AutoLogin method to work in OnlineSubsystemEOS, it requires command line parameters to be added to the game's execution, which translate directly to the three fields in the FOnlineAccountCredentials object otherwise passed to the Login method.

All three parameters need to be set for AutoLogin to work, even if some won’t be used (like in the Account Portal or Exchange Code methods). The parameters are as follows:

Type = AUTH_TYPE
Id = AUTH_LOGIN
Token = AUTH_PASSWORD

Below are some examples of the parameters needed for all three login methods that explained in the previous section. If these are added to the game execution command, then the login will process successfully, however it is subject to the requirements explained in the previous section. (Dev Auth Tool, Epic Games Launcher)

Developer

	-AUTH_TYPE=”Developer”
	-AUTH_LOGIN=”localhost:<port>”
	-AUTH_PASSWORD=”CredentialsName”

ExchangeCode

	-AUTH_TYPE=”ExchangeCode”
	-AUTH_LOGIN=”Empty”
	-AUTH_PASSWORD=”Exchange_Code_From_Launcher”

Login with OnlineSubsystemEOSPlus

There is no difference between using AutoLogin and Login in OnlineSubsystemEOSPlus, additionally, Login only needs specific values to be set in the FOnlineAccountCredentials objects for a few selected platforms.

External Authentication

The login method that OnlineSubsystemEOSPlus uses to process EOS authentication is different from those used by OnlineSubsystemEOS.

It starts by making a copy of the FOnlineAccountCredentials object passed on to the Login method (in case any of the optional values were set). Then, the system will start the native platform’s user login process (in case this hasn't been done already). This means logging in with the active platform account, or asking for user selection if needed on a console platform. The login process will stop if this initial platform login is not successful, triggering the registered OnLoginComplete delegates with information about the error.

After this first platform login succeeds, if any of the two settings mentioned in the previous section is enabled, EOS login is initiated with the credentials we saved at the beginning. Regardless of which was set, the first part of this new login process is the same: we will query the native platform subsystem for an external authentication token.

Using Cross Platform User IDs

If this setting is enabled and Using Epic Account Services is not, the external authentication token will be added to the set of credentials needed for the login method, and EOS will try to authenticate by calling the EOS_Connect_Login method.

Here’s where some more setup in the EOS Project Dev Portal is needed. For EOS authentication to complete successfully, the platform in question needs to have been added to the Identity Providers list as described in this article. With the Identity Provider set correctly, EOS authentication should complete successfully, unlocking access to all EOS game features.

Using Epic Account Services

If this setting is enabled, the login process will continue as if Using Cross Platform User IDs were enabled too. The external authentication token will be added to the set of credentials needed for the login method, and EOS will try to authenticate by calling the EOS_Auth_Login method. This method requires an Epic Games account to be linked beforhand with the platform account that is going to be used for EOS authentication.

At the moment, Account linking during the login process is only available in the Steam platform, and attempting login in any other platform will result in the following authentication error to appear in the log:

Log Error

	LogEOSSDK: Warning: LogEOS: Error response received from backend. ServiceName=[OAuth], OperationName=[TokenGrant], Url=[<Redacted>], HttpStatus=[400], ErrorCode=[errors.com.epicgames.account.oauth.authorization_pending], NumericErrorCode=[1012], ErrorMessage=[The authorization server request is still pending as the end user has yet to visit and enter the verification code.], CorrId=[...]

This functionality will be available in other platforms in future releases. In the meantime, manual account linking can be done via the Accounts tab in the Connections section of the Epic Games Account Settings.

The Epic account that was used in the linking process needs to accept the application access scopes (as described in the section Login with OnlineSubsystemEOS) or this other error will appear in the log:

Log Error

	LogEOSSDK: Warning: LogEOS: Error response received from backend. ServiceName=[OAuth], OperationName=[TokenGrant], Url=[<Redacted>], HttpStatus=[400], ErrorCode=[errors.com.epicgames.oauth.scope_consent_required], NumericErrorCode=[58005], ErrorMessage=[The user has not consented to required scopes.], CorrId=[...]

Once the account is linked, and the access scopes accepted, and if EOS authentication has been configured properly as well, login will complete successfully and the application will be able to use all of EAS’ additional features.