Connect Interface

连接接口处理不同身份提供方之下用户账号之间的连接。

阅读时间18分钟

连接接口

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

连接接口(Connect Interface)

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

玩家可以将一个或多个外部用户的账户与他们的 产品用户ID (Product User ID,一种唯一的玩家ID)相关联。

产品用户ID可用于同一个组织中的所有产品。

关于受支持的部身份提供者及配置信息,请查阅部身份提供者

管理用户

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

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

可以:

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

无法:

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

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

连接接口 - 账户流程

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

当连接接口可用于所有受支持的外部账户类型时,不需要Epic Games账户。

验证用户

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

  1. 使用 EOS_Connect_LoginOptions 调用 EOS_Connect_Login,其中包含来自受支持平台的外部凭证。例如,为了验证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用户(参见链接账户)。否则,你可以询问他们是否希望新建一个EOS用户来重新开始(参见创建用户)。

用户验证刷新通知

当现有访问令牌即将过期时,将运行提供给 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_LoginEOS_ContinuanceToken

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

绑定外部账号