连接接口

连接接口（Connect Interface） 允许外部身份提供者接入并使用 Epic在线服务 （EOS）生态系统。

连接接口（Connect Interface） ：

• 允许访问 Epic在线服务（EOS） 的游戏服务。
• 允许在跨平台服务中生成通用的唯一用户标识符。 将外部身份提供者
• 允许将外部身份提供者的账户与我们的服务关联。

玩家可以将一个或多个外部用户的账户与他们的 产品用户ID （Product User ID，一种唯一的玩家ID）相关联。产品用户ID可用于同一个组织中的所有产品。

你还可以使用验证接口，让玩家从你的游戏直接登录其Epic Games账户。关于受支持的部身份提供者及配置信息，请查阅部身份提供者。验证接口和连接接口的区别在于：

用户需要凭借外部凭证来登录。若此产品中已有用户，则会为此用户提供一个持续一定时间（当前为一小时）的 访问令牌。在令牌过期之前，游戏将得到通知；届时需要刷新现有令牌，给出一个有效的外部凭证。

Epic在线服务接口无法控制外部提供方的访问授权。因此，连接接口

可以：

• 验证外部账号提供方的用户是否仍有效
• 延长用户能够访问我方服务的时间。

无法：

• 隐式刷新令牌
• 提供长期访问

外部账号提供方应具备对于应用程序的授权访问权限。

假如需要访问此用户ID可用的服务，需要通过 EOS_ProductUserId 数据接口进行外部账号验证。所有接口都会明确说明此用法，并应该确保类型的安全性。该数据结构独立于 EOS_EpicAccountId，后者与为Epic账户服务提供的验证接口有关。

如需使用EOS Connect验证用户，请按以下步骤操作：

1. 使用 EOS_Connect_LoginOptions 调用 EOS_Connect_Login，其中包含来自受支持平台的外部凭证。你可以通过任意受支持的身份提供者进行登录（例如通过Steam、Xbox、或任天堂）。请查阅身份提供者管理文档，了解完整的身份提供者信息。例如，为了验证Epic Games账户，从 EOS_Auth_CopyIdToken 中获取本地Epic用户的ID令牌，并将 EOS_EExternalCredentialType 设置为 EOS_ECT_EPIC_ID_TOKEN。

2. 将 EOS_HConnect 句柄，你的 EOS_Connect_LoginOptions 结构，以及你的回调信息传递给 EOS_Connect_Login。

完成验证后，可能会出现以下其他操作:

• 如果 EOS_HPlatform 句柄还在更新，你提供的回调就会在操作完成后执行。
• 在获得成功的结果之后，应用程序可以访问需要认证的其他接口。
• 如果用户不存在，则登录API会返回一个 EOS_InvalidUser 结果以及 EOS_ContinuanceToken。该令牌会提供有关登录尝试的细节，并且为后续步骤所需。

当现有访问令牌即将过期时，将运行提供给 EOS_Connect_AddNotifyAuthExpiration 的一个回调函数。这让应用程序每次都有足够时间来获取另一个外部访问令牌，并通过 EOS_Connect_Login 函数来将其提供给SDK。

使用 EOS_Connect_RemoveNotifyAuthExpiration 函数来停止监听这些通知。

为确保应用程序能够获悉用户身份验证状态发生改变，连接接口将提供此类通知的回调。

本地用户的授权状态发生变化时，将运行你提供给 EOS_Connect_AddNotifyUserLoginStatusChanged 的回调函数。这种情况应只在以下条件下发生：如过期通知被忽略，外部提供方凭证无法刷新访问令牌；或出于某种权限原因，访问被后端服务显式撤销。只有当EOS生态系统中的其他回调检测到此验证令牌无效后，才会触发此回调函数；否则不会自动触发。

你必须处理可能因为验证而失败的调用中的所有错误信息。通常可以进行恢复，办法是调用 EOS_Connect_Login 然后在成功时重新尝试原始调用。

使用 EOS_Connect_RemoveNotifyUserLoginStatusChanged 函数来停止监听通知。

使用 EOS_Connect_GetLoginStatus 函数即可根据需求检查玩家的当前状态。此函数基于与在线服务的最近通信来确定验证状态，因此将即刻返回结果，不使用回调函数。

创建用户时，将为登录时使用给定外部凭证的用户生成一个新的 产品用户ID。在新建用户之前，有必要向用户弹出提示，确定是否存在其他登录方法。这能减少跨平台操作时的困惑和用户进程合并问题。

如果应用程序要为用户创建新产品用户ID，调用 EOS_Connect_CreateUser 即可。EOS_Connect_CreateUserOptions 包含从上个调用到 EOS_Connect_Login 的 EOS_ContinuanceToken。

将 EOS_HConnect 柄、EOS_Connect_CreateUserOptions 结构和回调信息传至函数。假设 EOS_HPlatform 柄正在tick，操作完成时将执行你提供的回调。

如果应用程序登录流程决定用户可以用第二套外部凭证登录，则保存来自首个登录调用的 EOS_ContinuanceToken、重新尝试通过 EOS_Connect_Login 登录，并在成功登录后立即调用 EOS_Connect_LinkAccount。这样便能把两个外部账号关联到一个产品用户ID。我们的服务得到拓展之后，还可以绑定两个以上的账户。

如应用程序的目的是用现有产品用户ID绑定一个新外部账号，则调用 EOS_Connect_LinkAccount。EOS_Connect_LinkAccountOptions 包含从上个调用到 EOS_Connect_Login 的 EOS_ContinuanceToken；已登录用户的产品用户ID成功对 EOS_Connect_Login 进行调用。

将 EOS_HConnect 柄、EOS_Connect_LinkAccountOptions 结构和回调信息传至函数。假设 EOS_HPlatform 柄正在tick，操作完成时将执行你提供的回调。

搜索EOS连接用户的方法是根据其外部账号ID；或使用产品用户ID，通过开发者门户中的“账户绑定（Account Linking）”面板进行。用户绑定外部账号的钥匙串在组织层面上进行管理，因此“账户绑定（Account Linking）”面板处于组织管理菜单项的旁边。通过账号绑定面板可以找到玩家，客户支持也能够借此进行玩家请求的账户解绑。还可以使用此面板在SDK整合测试中移除EOS连接用户或任何绑定账户。我们还随此提供了网络REST API，以便开发者将EOS用户管理整合到现有的内部面板中。

在首次用户登录流程期间，用户可能最终处于这样一种状态，即他们无意中为登录的账号（通常是本地平台账号）创建了新的产品用户ID，而非使用已有的游戏进度；这些进度可能是因为他们在其他平台上玩了游戏，或使用了其他的外部账号凭证。用户可能不知道游戏的跨平台联机对战功能（crossplay）。

在这类情况下，用户会跳过所有的前期登录对话框，继续使用他们默认的平台账号凭证（已登录账号），通过 EOS_Connect_Login 和 EOS_Connect_CreateUser 接口创建新的 EOS_ProductUserId。因此，他们在游戏开始时与 EOS_Connect_Login 一起使用的登录账号现在意外绑定了一个产品用户ID。假如要从这种状态恢复，用户需要将登录账号与新创建的钥匙串解除关联，以便再次进入首次用户登录流程。

一旦他们解除了登录账号的链接，他们就可以使用另一组外部账号凭证（其与现有的其他钥匙串关联）进行登录。如果成功，他们就能按照上文 绑定外部账号 一节的描述，将默认登录账号与所需的现有钥匙串进行绑定。

在另一种情况下，用户可能只是想将登录账号与其当前钥匙串解除绑定，以便在平台之间分离游戏进度，或以其他方式将其与另一钥匙串绑定。

若要将当前已登录的产品用户ID的钥匙串与外部账号与解绑，请使用 EOS_Connect_UnlinkAccountOptions 调用 EOS_Connect_UnlinkAccount，指定 LocalUserId 为上次调用 EOS_Connect_Login 后返回的 EOS_ProductUserId。操作成功后，外部账号将停止与所有钥匙串绑定。这意味着下次尝试使用 EOS_Connect_Login 并使用同一外部账号关联的凭证登录时，会返回 EOS_InvalidUser 结果并附带 EOS_ContinuanceToken。

与账号绑定的创建操作类似，你可以在开发者门户中通过账号仪表板来审查解除绑定的历史操作记录。

为了防止账号被盗，只有本地用户当前登录时使用的账号才能与钥匙串解绑。这可以防止恶意行为者访问其中某个绑定账号，并用它删除与钥匙串绑定的所有其他账号。它还可以防止恶意行为者将未绑定的账号替换为他们自己在同一平台上的账号，因为取消绑定操作能确保这样一个事实，即现有验证会话在未与钥匙串中其他已绑定账号进行验证的情况下，无法用于重新绑定和覆盖条目。

这类限制旨在限制与账号盗窃情景相关的潜在攻击层面。

应用程序认为不足以为用户创建新账户或绑定现有账户时，应用程序可能会使用EOS链接设备ID功能来创建一个新的持久伪账户。此功能让应用程序能够为本地用户创建一个持久访问凭证，而无需使用外部登录凭证。这样后端设备便能在本地设备的多个游戏会话中记住当前用户。设备ID功能在个人移动设备上尤为实用，可以不弹出账户凭证提示而自动登录用户，无需立即要求玩家登录维持游戏进度数据便能开始游戏。

然而，设备ID未绑定到真实用户账户且只能用于独立识别本地设备。因此强烈建议在早期进行到一定时间段后，便要求用户绑定一种外部验证其设备ID账户的方法，以防止凭证和账号的丢失。

如果最终并未以真实用户身份绑定设备ID账号，设备本身一旦出现意外，所有游戏进度和数据便会永久丢失。EOS SDK将把设备ID凭证本地保存在本地设备当前登录用户的钥匙串中。如本地用户档案被重设或丢失，之后则无法恢复设备ID。

要创建新设备ID，应用程序必须用一个包含用户设备型号（DeviceModel）的有效EOS_Connect_CreateDeviceIdOptions结构来调用 EOS_Connect_CreateDeviceId 函数。此调用最终将对绑定到 EOS_Connect_OnCreateDeviceIdCallback 的函数触发一个回调。如新的设备ID已成功创建并被保存在本地设备登录用户的钥匙串中，那么回调参数的ResultCode参数将被设为 EOS_EResult::EOS_Success 。如已存在现有设备ID，则返回 EOS_EResult::EOS_DuplicateNotAllowed 。否则ResultCode参数将识别操作失败的原因。

要用专属设备ID登录本地用户，需要以 EOS_EExternalCredentialType::EOS_ECT_DEVICEID_ACCESS_TOKEN 外部凭证类型调用 EOS_Connect_Login API。因为SDK自动管理保存的设备ID凭证，输出 EOS_Connect_Credentials 结构体的 Token 参数必须被设为空（null）。然而，因为设备ID未绑定真实用户身份，EOS_Connect_UserLoginInfo 输入结构体需要带有用户的有效 DisplayName。

要将本地设备ID绑定到真实外部用户账户，首先让游戏使用设备ID凭证类型正常登录本地用户。然后要求用户使用真实身份登录，在 EOS_Connect_Login 返回一个 EOS_ContinuanceToken 之后，使用 EOS_Connect_Link API绑定外部账号，将本地设备与用户的真实账号关联起来。之后每次游戏开始时便会自动登入用户，因为设备ID仍能用于自动登录用户，无需弹出外部用户账户凭证输入的提示。

你也可以调用 EOS_Connect_DeleteDeviceId API来删除本地设备当前用户档案的设备ID。删除为永久性操作，不可恢复。然而，用户始终可以新建一个设备ID，并将其与现有外部用户账户绑定，以恢复自动登录功能。

在安卓和iOS设备上，卸载应用会自动删除所有由应用创建的本地设备ID凭证。

在桌面平台上（Linux、macOS、Windows），设备ID凭证不会自动删除。应用在重新安装时，可以为本地OS用户复用已有的设备ID凭证，或者在首次运行时调用 EOS_Connect_DeleteDeviceId API，确保用户拥有全新的初始体验。

有一种极端情况，在这种情况中，你无法通过常规渠道将设备ID伪账号与真实的外部用户账号关联。在这种情况中，已登录的真实用户账号已经属于同一EOS组织下的已有钥匙串。在这种情况中，当游戏首先自动使用本地设备ID登录类型登录用户，并且用户使用真实的外部用户账号凭证登录时，EOS_Connect_Login 接口将返回已有的 EOS_ProductUserId，而非 EOS_ContinuanceToken。为了处理这种特殊情况，需要使用 EOS_Connect_TransferDeviceIdAccount 接口。

设备ID伪账号无法关联现有钥匙串，因为 EOS_Connect_Link 接口要求使用 EOS_ContinuanceToken。另外，由于玩家现在面临两个单独的 EOS_ProductUserIds，游戏需要让玩家选择是否将其中一个作为过时的 EOS_ProductUserIds （即游戏档案）丢弃，继而使用另一个。如果玩家选择丢弃其中一个档案，游戏可以将本地设备ID账号关联到后端持续存在的已关联账号的现有钥匙串中。

为了处理出现两个 EOS_ProductUserIds 的情况，游戏需要能够识别：何时使用设备ID登录类型让本地用户登录，然后用户在同一游戏会话中使用外部账号登录 并且 收到另一个 EOS_ProductUserId 会话。当出现这种情况时，游戏应该尝试自动检测是否其中有一个 EOS_ProductUserIds 在后台没有任何有意义的游戏进度。这种情况下，游戏应自动丢弃它，并将本地设备ID伪账号与真实的外部用户账号的现有钥匙串关联起来。

假如游戏无法确定是否可以代表用户自动处理这一特殊情况，它应该提示用户，让用户选择该如何继续。在这类选择对话框中，玩家应该能够查看游戏进度，以比较形式查看每个 EOS_ProductUserId，并选择保留哪一个。应该清楚地告知用户，游戏进度丢弃后将永远丢失，之后将无法恢复。游戏还应该允许用户不丢弃任意一个档案，而是在当前游戏会话中选择继续玩某个档案。

如果用户选择丢弃其中一个游戏档案，永久切换到另一个，游戏应该调用 EOS_Connect_TransferDeviceIdAccount 接口，将本地设备ID伪账号传入与真实外部用户账号关联的密钥串中。在接口中，输入结构体 EOS_Connect_TransferDeviceIdAccountOptions，并将 ProductUserIdToPreserve 参数设置为指向正确的 EOS_ProductUserId，以便在设备ID转移操作中保留。

其他接口将接收远程或其他外部用户的 EOS_ProductUserId（例如同一服务器上好友或玩家的列表）。可以通过映射API将外部用户账户辨识符转换为 EOS_ProductUserId。

EOS_Connect_QueryExternalAccountMappings 是一个异步调用，将把外部账户ID转换为SDK代表。设置 EOS_EExternalAccountType，并以字符串形式提供外部账号ID的一个连续列表即可。

将 EOS_HConnect 柄、EOS_Connect_QueryExternalAccountMappingsOptions 结构和回调信息传至函数。假设EOS_HPlatform柄正在tick，操作完成时将执行你提供的回调。

回调成功返回后，即可通 过 EOS_Connect_GetExternalAccountMapping 获取映射。和之前一样，此函数接受 EOS_EExternalAccountType 并为每次调用返回一个单一 EOS_ProductUserId（此调用以字符串形式提供一个外部账号ID）。

你可以获取外部账户的产品用户ID，同时，你也可以获取某个产品用户ID的外部账户。

EOS_Connect_QueryProductUserIdMappings 是一个异步调用，将把 EOS_ProductUserIds 转换为给定平台上的外部同类，以及包含显示名称和上次登录时间的额外账号数据。将提供产品用户ID的连续列表。

将 EOS_HConnect 柄、EOS_Connect_QueryProductUserIdMappingsOptions 结构和回调信息传至函数。假设 EOS_HPlatform 柄正在tick，操作完成时将执行你提供的回调。

回调成功返回后，即可通 过 EOS_Connect_GetProductUserIdMapping 获取映射。

此函数接受 EOS_EExternalAccountType、一个输入缓冲，以及缓冲长度来填充外部账号ID。如缓冲过小，则会返回缓冲的正常大小。

使用 EOS_Connect_GetProductUserExternalAccountCount 来获取产品使用者绑定的外部账号数量。

使用 EOS_Connect_CopyProductUserExternalAccountByIndex 来获取通过索引绑定到产品用户的外部账号的相关信息。

使用 EOS_Connect_CopyProductUserExternalAccountByAccountType 来获取绑定到产品用户的特定类型外部账号的相关信息。

使用 EOS_Connect_CopyProductUserExternalAccountByAccountId 来获取通过账号ID绑定到产品用户的外部账号的相关信息。

使用 EOS_Connect_CopyProductUserInfo 来获取产品用户的相关信息，以其最近登录所使用的外部账号来当作参考。

如产品用户ID未映射到给定的外部平台，则数据不会出现在为上述操作返回的结果中。这意味着用户从未将此外部账号类型绑定到其产品用户ID。

ID令牌是OpenID Connect协议的一部分，可用于在服务器端验证用户的身份。ID令牌是一种JSON格式的网络令牌（JWT），它包含验证用户相关的信息，如产品用户ID。这允许后端服务和游戏服务器安全地验证从客户端收到的用户标识符。

在用户通过EOS连接的验证后，游戏客户端可以通过调用 EOS_Connect_CopyIdToken SDK API来获取本地用户的ID令牌（传入一个包含用户 EOS_ProductUserId 的 EOS_Connect_CopyIdTokenOptions 结构）。

输出的 EOS_Connect_IdToken 结构包含用户的 EOS_ProductUserId，以及代表ID令牌数据的JWT。注意，等你不再需要时，你必须调用 EOS_Connect_IdToken_Release 来释放ID令牌结构。

获取后，游戏客户端就可以向另一方提供ID令牌。在每次成功的 EOS_Connect_Login 调用后都会提供一个新的ID令牌。

在本地用户的EOS连接认证会话的有效期内，ID令牌一直有效。当游戏客户端刷新验证会话时，它应默认之前使用的ID令牌会很快过期，并且如果需要，可以使用新的ID Token。

EOS连接ID令牌的JSON网络密钥集合（JSON Web Key Set，JWKS）端点是：https://api.epicgames.dev/auth/v1/oauth/jwks。

游戏服务器可以通过调用 EOS_Connect_VerifyIdToken SDK API，并传入包含 EOS_Connect_IdToken 的 EOS_Connect_VerifyIdTokenOptions 来验证ID令牌。注意，游戏服务器应该在调用验证前使用 EOS_ProductUserId_FromString 来填充 EOS_Connect_IdToken 结构中的 EOS_ProductUserId 部分，因为服务器的用户句柄与客户端的用户句柄不同。

后台服务可以验证ID令牌的有效性，并使用所有公开的标准JWT库来提取令牌声明。请参见https://jwt.io/，了解与此相关的库列表。所使用的库应允许自动缓存检索的JWKS信息，以获得最佳性能并降低网络开销。

EOS SDK和其他支持库会处理安全验证ID令牌所需的步骤，然后才能安全地信任其包含的声明。所执行的步骤如下：

1. 验证令牌签名算法（"alg"）是否存在并且没有被设置为 “无（none）”。
2. 使用Epic在线服务托管的JWKS端点，对照预期的公共证书验证JWT签名。
3. 验证令牌发行者（“iss”）是否存在，并且是否以https://api.epicgames.dev的基础URL开头。
4. 验证令牌发行时间（"iat"）是否在过去时段。
5. 验证令牌的到期时间（"exp"）是在未来时段。
6. 验证客户ID（"aud"）与用于初始化EOS SDK以及游戏客户端的客户ID或其他用于验证用户与EOS连接的客户ID一致。

在成功验证ID令牌后，你可以信任产品用户UID（“sub”）值。

ID令牌包含以下JSON结构：

头部

负载

Footnotes

1. See the Auth Interface documentation for more information on linked external accounts. ↩

2. See the Identity Provider Management documentation for more information on identity providers. ↩

3. See the Friends Interface documentation for more information on using the Friends Interface. ↩

4. See the Presence Interface documentation for more information on using the Presence Interface. ↩

5. See the Ecom Interface documentation for more information on using the Ecom Interface. ↩

6. See the Social Overlay Overview documentation for more information on the EOS social overlay. ↩

7. See the Api Reference documentation for more information on calling EOS_Platform_Tick. ↩

8. See the Connect Interface documentation for more information on expiration notification events. ↩