在线子系统EOS插件

Epic在线服务（Epic Online Services (EOS)） 是一种与引擎无关的系统，提供了一系列跨平台在线功能，包括：

• 以玩家为中心的功能，例如：
  • 成就
  • 排行榜
• 商业功能，例如：
  • 游戏内购买
• 社交功能，例如：
  • 语音通信
  • 好友列表

你可以通过在线子系统Epic在线服务（OSS EOS）插件在虚幻引擎项目中使用EOS。在线子系统Epic在线服务（Online Subsystem Epic Online Services） 插件可帮助你与游戏中的Epic在线服务交互，而不必编写直接与EOS SDK交互的代码。要使用此功能，你必须通过 EOS开发人员门户（EOS Developer Portal） 注册并配置你的产品，然后启用并配置一些插件来通过OSS接口公开EOS功能。

如需详细了解Epic在线服务，包括有关注册和配置产品的信息，请参阅Epic在线服务开发人员文档。

EOS插件概述

OSS EOS插件在 在线子系统（Online Subsystem (OSS)） 插件基础上构建。在线子系统插件是一种通用插件，提供了访问各种在线服务的公共接口。OSS EOS插件实现了通过Epic在线服务提供的特定功能，并将与EOS SDK的通信集成到插件中，从而扩展了OSS插件。本页面介绍了OSS EOS插件的以下功能：

• 产品注册
• 启用插件
• 配置
• 登录
• 支持的接口

你可以选择通过 OSS EOS Plus 插件扩展OSS EOS插件。EOS Plus表示"EOS + 基础平台"，将EOS与另一个平台（例如Steam、主机平台等）相结合。将EOS与另一个平台相结合提供了更多功能，例如自动会话镜像。你可以在使用或不使用Epic账号服务（EAS）的情况下使用EOS Plus。

何时使用EOS Plus

如果你在Epic Games商城发行游戏，则需要使用OSS EOS插件；此外，无需使用EOS Plus。如果你在另一个平台上发行游戏，请使用OSS EOS Plus插件以及OSS EOS插件。本指南可能存在例外情况。继续阅读本页面，确定适合你的项目的最佳插件组合。

如何使用OSS EOS

Epic开发人员社区上的OSS EOS插件课程可指导你完成在虚幻引擎项目中使用OSS EOS的过程。

设置

使用Epic在线服务注册产品

Epic开发人员资源文档为你提供了Epic Games商城（EGS）、Epic在线服务、儿童网络服务（KWS）及其关联工具的资源。要利用OSS EOS插件，你必须首先使用Epic在线服务注册产品。要使用EOS注册产品，请找到Epic开发人员门户并执行入门步骤。尤其是，本指南在入门步骤的第1步中概括了产品注册过程。稍后需要使用注册产品时提供的信息在虚幻引擎中配置OSS EOS插件。

虚幻引擎是使用EOS SDK的副本发行的，所以如果你想使用虚幻引擎随附的EOS SDK版本，不需要单独下载EOS SDK。要使用不同版本的EOS SDK，请按照入门步骤的第2步中的说明操作，下载所需版本的EOS SDK。下载所需版本的EOS SDK后，按照我们的升级EOS SDK文档上的说明操作，了解有关如何升级虚幻引擎使用的EOS SDK的更多信息。

如果你升级EOS SDK，我们推荐你查阅EOS SDK版本说明，了解升级所需的必要更新。

启用OSS EOS插件

要在项目中使用EOS，你必须在虚幻引擎中启用OSS EOS插件。要启用OSS EOS插件，请执行以下步骤：

1. 找到 编辑（Edit）> 插件（Plugins） 。这会打开 插件浏览器（Plugin Browser） ，其中你可以搜索要启用的插件。
2. 在 插件浏览器（Plugin Browser） 中，找到并启用 在线子系统EOS（Online Subsystem EOS） 插件。

在线子系统EOS实现了Epic在线服务的在线子系统插件。当你启用OSS EOS插件时，会默认启用以下额外的插件：

• EOS Plus
  • 将EOS与另一个平台相结合。
• EOS共享（EOS Shared）
  • 负责初始化和关闭EOS SDK。
  • 默认作为OSS EOS的依赖项启用。
• EOS语音聊天（EOS Voice Chat）
  • 通过EOS支持语音聊天。

启用所需插件后，你需要配置它们以在项目中使用。以下某些配置步骤需要与产品相关的设置，或者需要向EOS注册产品之后接收的标识符。这些在你的Epic开发人员门户中可用。

配置OSS EOS插件

要继续，请确保你已经执行以下操作：

1. 使用Epic在线服务注册产品。
2. 启用OSS EOS插件。

要配置OSS EOS插件，请执行以下步骤：

1. 从工具栏，点击 编辑（Edit）> 项目设置（Project Settings） 。
2. 找到 插件（Plugins）> 在线子系统EOS（Online Subsystem EOS） 。

EOS设置

这些设置与EOS的特定于平台的配置有关。如需详细信息，请参阅有关EOS_Platform_Options数据结构的EOS API参考页面。下表介绍了每个EOS设置：

构件设置

构件设置包括你在EOS开发人员门户中注册的产品的设置。你在此处配置的设置应该匹配你在EOS开发人员门户中注册的产品的设置。你可以在EOS开发人员门户上找到产品的设置。

要编辑 构件设置（Artifact Settings） ，请执行以下步骤：

1. 点击 EOS设置（EOS Settings） 分段中的 构件（Artifacts） 旁边的 添加元素（Add Element） 按钮。这会在 EOS设置的构件（EOS Settings' Artifact） 数组中创建新元素。
2. 要自定义这个新构件的设置，请点击新创建的数组元素旁边的箭头。如果这是数组中的第一个元素，名称为 Index[0] 。

下表说明了可用的构件设置：

EOS Plus设置

要使用此插件，请首先在开发人员门户中为你想支持的每个平台注册并配置你的产品。特定于平台的EOS SDK版本包含关于使用每个版本支持的平台的功能的详细说明。

在使用EOS Plus插件之前，你必须配置EOS Plus登录设置和跨平台游戏设置。

EOS Plus登录设置

下表说明了EOS Plus登录设置：

跨平台游戏设置

下表说明了跨平台游戏设置：

EOS插件的引擎配置

在开发人员门户上设置了你的产品并配置了插件之后，你就需要配置一些设置。你可以在引擎配置层级中配置这些插件，例如 DefaultEngine.ini 。

OSS EOS配置设置

将以下配置设置添加到你的项目的 DefaultEngine.ini 文件：

1. 检查是否在项目中启用了在线子系统EOS插件。

        [OnlineSubsystemEOS]
        bEnabled=true
   Copy full snippet

   [OnlineSubsystemEOS] bEnabled=true

2. 将EOS设置为项目的在线服务的默认平台。

        [OnlineSubsystem]
        DefaultPlatformService=EOS
   Copy full snippet

   [OnlineSubsystem] DefaultPlatformService=EOS

3. 指定网络驱动程序。

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

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

4. 将EOS的点对点套接字功能用于玩家托管的比赛。此设置是可选的。

        [/Script/OnlineSubsystemEOS.NetDriverEOS]
        bIsUsingP2PSockets=true
   Copy full snippet

   [/Script/OnlineSubsystemEOS.NetDriverEOS] bIsUsingP2PSockets=true

下面是上面介绍的针对OSS EOS的所有配置设置：

[OnlineSubsystemEOS]
bEnabled=true

[OnlineSubsystem]
DefaultPlatformService=EOS

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

[/Script/OnlineSubsystemEOS.NetDriverEOS]
bIsUsingP2PSockets=true
Copy full snippet

[OnlineSubsystemEOS] bEnabled=true [OnlineSubsystem] DefaultPlatformService=EOS [/Script/Engine.GameEngine] +NetDriverDefinitions=(DefName="GameNetDriver",DriverClassName="OnlineSubsystemEOS.NetDriverEOS",DriverClassNameFallback="OnlineSubsystemUtils.IpNetDriver") [/Script/OnlineSubsystemEOS.NetDriverEOS] bIsUsingP2PSockets=true

从Epic Games启动程序启动作品

如果你要从Epic Games启动程序启动作品，需要在Epic Games商城（EGS）启动的所有Epic应用和Epic沙盒对的引擎配置文件层级中添加配置条目。确保项目设置或引擎配置中的 默认构件名称（Default Artifact Name） 和 构件名称（Artifact Name） 匹配Epic在线服务开发人员门户中的构件名称。

在EGS上发售作品时，将忽略默认构件名称。EGS始终会改为传递它使用的 -epicapp 命令行参数。默认构件名称适合在不传递 -epicapp 的其他店面上发售时使用。

EOS Plus配置设置

如果你想配置项目以在EOS和另一个在线平台之间实现跨平台游戏，请将以下配置设置添加到你的项目的 DefaultEngine.ini 文件：

1. 检查是否在项目中启用了在线子系统EOS Plus插件。

   • 前面说过，EOS Plus插件允许你将EOS与不同的在线服务一起使用。

           [OnlineSubsystemEOSPlus]
           bEnabled=true
     Copy full snippet

     [OnlineSubsystemEOSPlus] bEnabled=true
2. 将你的默认平台在线服务更改为EOS Plus。

   • 这会告知引擎，你要将EOS与不同的平台服务一起使用。此外，添加你想使用的额外原生平台在线服务。在本例中，它设置为Steam，但可以是任何在线服务，包括主机在线服务。

           [OnlineSubsystem]
           DefaultPlatformService=EOSPlus
           ；在下面添加你的额外平台在线服务
           NativePlatformService=Steam
     Copy full snippet

     [OnlineSubsystem] DefaultPlatformService=EOSPlus ；在下面添加你的额外平台在线服务 NativePlatformService=Steam
3. 说明哪些网络ID类型与默认OSS兼容。

   • 这只需要在EOS/EOS Plus是默认OSS时设置。

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

     [/Script/OnlineSubsystemUtils.OnlineEngineInterfaceImpl] +CompatibleUniqueNetIdTypes=EOS +CompatibleUniqueNetIdTypes=EOSPlus
4. 支持EOS与EOS Plus客户端之间的通信。

   • 例如，考虑这样一种情况，有一个EOS Plus玩家使用了另一个在线平台（例如Steam）登录，托管着一个EOS会话，然后一个EOS（不是EOS Plus）客户端加入前者的EOS会话。纯EOS客户端需要此映射，以便EOS Plus网络ID能够正确路由到EOS，并反序列化为EOS网络ID。此 MappedUniqueNetIdTypes 配置添加到与上一步中的配置相同的配置分段。

           [/Script/OnlineSubsystemUtils.OnlineEngineInterfaceImpl]
           MappedUniqueNetIdTypes=(("EOSPlus","EOS"))
     Copy full snippet

     [/Script/OnlineSubsystemUtils.OnlineEngineInterfaceImpl] MappedUniqueNetIdTypes=(("EOSPlus","EOS"))

下面是上面介绍的针对EOS Plus的所有配置设置：

[OnlineSubsystemEOSPlus]
bEnabled=true

[OnlineSubsystem]
DefaultPlatformService=EOSPlus
NativePlatformService=Steam

[/Script/OnlineSubsystemUtils.OnlineEngineInterfaceImpl]
+CompatibleUniqueNetIdTypes=EOS
+CompatibleUniqueNetIdTypes=EOSPlus
MappedUniqueNetIdTypes=(("EOSPlus","EOS"))
Copy full snippet

[OnlineSubsystemEOSPlus] bEnabled=true [OnlineSubsystem] DefaultPlatformService=EOSPlus NativePlatformService=Steam [/Script/OnlineSubsystemUtils.OnlineEngineInterfaceImpl] +CompatibleUniqueNetIdTypes=EOS +CompatibleUniqueNetIdTypes=EOSPlus MappedUniqueNetIdTypes=(("EOSPlus","EOS"))

登录

有两种方法可在在线身份接口中开始登录过程：

• 自动登录（Auto Login） ：需要你传递本地用户编号。
• 登录（Login） ：需要你使用 FOnlineAccountCredentials 对象。

下一个小节介绍了如何在OSS EOS中使用自动登录或登录来使用户登录。

使用OSS EOS登录

除了提供有效的本地用户编号之外，此登录方法还需要你传递 FOnlineAccountCredentials 对象。此类有三个字段：

• 类型（Type）
• ID
• 令牌（Token）

登录方法

这三个字段表示OSS EOS应该使用哪种身份验证方法，具体取决于其值。以下小节提供了示例，说明如何设置可用的每种不同类型的身份验证：

• 账号门户
• 开发人员
• 交换代码

账号门户

• 类型（Type）： AccountPortal
• ID：
• 令牌（Token）：

账号门户是最通用的登录方法，因为它不需要 EOS开发人员身份验证工具（Dev Auth工具） ，也不需要你的应用程序从Epic Games启动程序启动。

利用此方法，如果你使用的是EOS SDK版本1.15或更高版本，发起登录调用时将显示游戏覆层UI。如果未启用游戏覆层，将打开浏览器窗口。用户需要在系统提示时输入Epic账号信息。如果用户已经登录Epic Games，用户必须接受相关产品的访问范围。

由于凭证由用户在游戏覆层UI或浏览器中提供，你不需要提供ID或令牌。

开发人员

• 类型（Type）： Developer
• ID： localhost:<PORT>
  • PORT 是Dev Auth工具中指定的端口
• 令牌（Token）： <CREDENTIALS_NAME>
  • CREDENTIALS_NAME 在Dev Auth工具中指定

"开发人员"是桌面平台上使用OSS EOS开发的推荐方法。此方法需要运行Dev Auth工具。请参阅Epic在线服务站点上的以下文档，详细了解开发人员身份验证工具。

设置Dev Auth工具后，记住你使用的端口和凭证名称，因为需要它们来填写 FOnlineAccountCredentials 对象的 Id 和 Token 字段，如上所述。此登录方法会在发起登录调用时打开，并且系统会要求用户输入Epic Games账号信息。如果用户已经登录Epic Games，用户必须接受相关产品的访问范围。此步骤仅在用户首次登录时执行。

交换代码

• 类型（Type）： ExchangeCode
• ID：
• 令牌（Token）： <EXCHANGE_CODE>
  • <EXCHANGE_CODE> 由Epic Games启动程序提供

你应该仅在你的应用程序从Epic Games启动程序启动时才使用"交换代码"方法，因为它需要启动程序提供的交换代码。此方法不需要运行Dev Auth工具，你应该对游戏的发布版本使用此方法。

由于Epic Games启动程序会提供交换代码令牌，你不需要提供ID或令牌。

登录成功

如果上述任一方法成功完成，登录过程会注册所有必要的EOS通知服务（登录状态、好友、在线状态更新和身份验证刷新）并触发以下注册的委托来结束：

• OnLoginComplete: 参数包括登录是否成功，以及新通过身份验证的用户的 UniqueNetId 。
• OnLoginStatusChanged: 参数对应之前和当前的登录状态以及新通过身份验证的用户的 UniqueNetId 。

使用OSS EOS自动登录

要对在线子系统EOS使用自动登录，你必须在启动时将额外的命令行参数传递到游戏的可执行文件。这些参数对应于原本传递给登录方法的 FOnlineAccountCredentials 对象中的三个字段。

上面登录中的参数对应如下所示的命令行参数：

登录方法

此小节包含所有三种登录方法所需的参数的示例，如上一小节所述。

账号门户

-AUTH_TYPE="accountportal" 
Copy full snippet

-AUTH_TYPE="accountportal"

开发人员

-AUTH_TYPE="developer" -AUTH_LOGIN="localhost:<PORT>" -AUTH_PASSWORD="<NAME_IN_DEV_AUTH_TOOL>"
Copy full snippet

-AUTH_TYPE="developer" -AUTH_LOGIN="localhost:<PORT>" -AUTH_PASSWORD="<NAME_IN_DEV_AUTH_TOOL>"

此命令中的参数如下：

• <PORT> 是你在Dev Auth工具中配置的端口。
• <NAME_IN_DEV_AUTH_TOOL> 是你在Dev Auth工具中选择的凭证名称。

交换代码

-AUTH_TYPE="exchangecode" -AUTH_PASSWORD="<EXCHANGE_CODE_FROM_LAUNCHER>"
Copy full snippet

-AUTH_TYPE="exchangecode" -AUTH_PASSWORD="<EXCHANGE_CODE_FROM_LAUNCHER>"

此命令中的参数如下：

• <EXCHANGE_CODE_FROM_LAUNCHER> 是Epic Games启动程序中的交换代码。

使用外部账号凭证的登录流程

此小节介绍使用外部账号的OSS EOS登录流程。你必须启用EOS Plus才能使用外部账号登录。

如果Epic账号服务和连接接口（ EOS_Connect ）都已启用，将使用非EOS平台（例如Steam）的外部账号凭证调用 EOS_Auth_Login 。如果此登录失败并返回用户无效的错误（ EOS_InvalidUser ），将调用 EOS_Auth_LinkAccount 。此调用会提示用户通过Web浏览器或用户界面覆层登录Epic Games账号。此登录将用户的Epic Games账号关联到外部非EOS账号。

请参阅下面的已知问题，详细了解账号关联过程。

如果未启用Epic账号服务，但启用了连接接口，将使用外部账号凭证调用 EOS_Connect_Login 。

身份验证接口（ EOS_Auth ）连接接口都需要身份提供程序配置。要使用你预期的外部平台，请将其添加到EOS项目开发人员门户中的身份提供程序列表。如果你在身份提供程序中正确配置了你的平台，EOS身份验证应该会成功完成并解锁所有EOS游戏功能的访问权限。如需详细信息，请参阅有关身份提供程序管理的Epic开发人员资源文档。

必须启用EOS Plus，才能使用外部账号登录。

使用Epic账号服务

如果启用此设置，登录过程会像同时启用了"使用跨平台用户ID"那样继续。外部身份验证令牌会添加到登录方法所需的一组凭证，EOS会尝试调用 EOS_Auth_Login 方法来进行身份验证。

接口

此小节提供了有关在线子系统EOS插件中实现的接口的更多信息。如需详细了解其中每个接口，请参阅在线子系统文档。OSS EOS插件支持以下EOS SDK接口：

支持的接口

会话

Bucket ID

在OSS EOS会话中， BucketId 是特定于游戏的顶层筛选信息，用于搜索会话。如需详细了解会话 BucketId ，请参阅有关会话的EOS文档。

BucketId 可以使用添加到 FOnlineSessionSettings::Settings 的自定义属性设置为你的项目需要的内容。为此，将以下内容添加到你的项目代码：

SessionSettings.Settings.Add(OSSEOS_BUCKET_ID_ATTRIBUTE_KEY, FOnlineSessionSetting(FString(TEXT("BUCKET_ID_PLACEHOLDER")), EOnlineDataAdvertisementType::ViaOnlineService));
Copy full snippet

SessionSettings.Settings.Add(OSSEOS_BUCKET_ID_ATTRIBUTE_KEY, FOnlineSessionSetting(FString(TEXT("BUCKET_ID_PLACEHOLDER")), EOnlineDataAdvertisementType::ViaOnlineService));

其中：

• BUCKET_ID_PLACEHOLDER 是你想使用的Bucket ID。

此自定义 BucketId 还需要以类似方式添加到会话搜索参数。

统计数据

统计数据名称

OSS EOS会将所有统计数据名称转换为大写，然后再将其传递给EOS。在EOS开发人员门户中配置你的项目时，务必将统计数据名称配置为大写名称，确保兼容OSS EOS。

已知问题

账号关联

目前，登录过程中的账号关联仅在Steam平台中可用，尝试登录其他平台会导致日志中显示以下身份验证错误：

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=[...]
Copy full snippet

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=[...]

在未来的版本中，此功能将在其他平台可用。同时，你可以通过Epic Games账号设置"连接（Connections）"分段中的"账号（Accounts）"选项卡手动完成账号链接。

关联过程中使用的Epic账号需要接受应用程序访问范围（如分段使用OSS EOS登录中所述），否则日志中还将显示如下错误：

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=[...]
Copy full snippet

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=[...]

关联账号后，会接受访问范围，并且如果EOS身份验证配置正确无误，登录将成功完成，应用程序也能够使用EAS的所有其他功能。