User Info Interface

用于获取显示命名或国家/地区等用户相关信息,并且将显示命名映射到帐户辨识符的接口。

阅读时间6分钟

所有 Epic在线服务(EOS)用户帐户都有专属辨识符,服务将通过内部使用来引用帐户。用户信息接口 在用户的帐户辨识符和用户相关信息(如显示命名、国家/地区和首选语言等)之间架起连接。可为远程用户以及登录的本地用户检索此类信息。

为保护用户隐私,用户信息接口仅提供远程用户的显示名称和专属帐户辨识符。

如需使用用户信息界面,你的产品必须开通 Epic账号服务(EAS),并且必须获得用户同意]才能访问 用户数据。你可以在开发者门户开通EAS,或者在Epic文档了解更多信息。在没有EAS和用户同意的情况下,你仍然可以初始化EOS SDK和用户信息界面,但是用户信息界面对后端服务的所有函数调用都会失败。

检索和缓存用户信息

要访问用户信息接口,需要 EOS_HUserInfo 句柄;可通过 EOS_Platform_GetUserInfoInterface 函数在 平台函数 处进行获取。用户信息接口函数需要该句柄来访问用户信息。 在线服务的服务器存储用户信息,而用户更新其帐户时该信息会悄然变更。用户信息接口会自动创建本地缓存,需要最新信息时可通过查询服务器来更新该缓存。

以帐户辨识符检索用户信息

处理用户信息的首步是使用 EOS_UserInfo_QueryUserInfoOptions 数据结构并调用 EOS_UserInfo_QueryUserInfo。此操作会将最新用户信息下载到本地缓存。要执行 EOS_UserInfo_QueryUserInfo 调用,使用下列字段值创建并初始化 EOS_UserInfo_QueryUserInfoOptions

属性
ApiVersionEOS_USERINFO_QUERYUSERINFO_API_LATEST
LocalUserId已登录用户的 EOS_EpicAccountId
TargetUserId要检索相关信息的用户 EOS_EpicAccountId

将用户信息接口句柄、EOS_UserInfo_QueryUserInfoOptions 结构和回调信息传递给函数。若 EOS_HPlatform 句柄正在tick,提供给 EOS_UserInfo_QueryUserInfo 的回调将在操作结束时运行。 回调执行时,可检查 EOS_UserInfo_QueryUserInfoCallbackInfo 结构的 ResultCode 字段来确定操作是否成功。成功代码表明SDK已经缓存了服务器中的最新数据,可随时进行检查。

以显示名称检索用户信息

EOS SDK中几乎所有函数都根据用户专属帐户辨识符来处理用户,但玩家仅可知道好友的帐户名称。EOS_UserInfo_QueryUserInfoByDisplayName 提供将显示名称映射到其帐户辨识符的方法。使用 EOS_UserInfo_QueryUserInfoByDisplayNameOptions 数据结构并调用 EOS_UserInfo_QueryUserInfoByDisplayName 来检索和缓存最新用户信息。调用此函数时,请按如下设置初始化 EOS_UserInfo_QueryUserInfoByDisplayNameOptions 结构:

属性
ApiVersionEOS_USERINFO_QUERYUSERINFOBYDISPLAYNAME_API_LATEST
LocalUserId已登录用户的 EOS_EpicAccountId
DisplayName要检索相关信息的用户显示名称

将用户信息接口句柄、EOS_UserInfo_QueryUserInfoByDisplayNameOptions 结构和回调信息传递给函数。在 EOS_HPlatform 句柄在计时的前提下,你提供的回调将在操作结束时运行。在回调函数中,可检查 EOS_UserInfo_QueryUserInfoByDisplayNameCallbackInfo 结构的 ResultCode 字段来确定操作是否成功。如成功,则SDK已缓存服务器中的最新数据,可随时进行检查。

通过外部账户获取用户信息

EOS_UserInfo_QueryUserInfoByExternalAccount 允许你通过关联的外部账户来查询用户信息。请调用 EOS_UserInfo_QueryUserInfoByExternalAccount 并使用 EOS_UserInfo_QueryUserInfoByExternalAccountOptions 数据结构来获取和缓存用户的最新信息。在调用此函数时,请参照以下信息初始化你的 EOS_UserInfo_QueryUserInfoByExternalAccountOptions 结构:

属性
ApiVersionEOS_USERINFO_QUERYUSERINFOBYEXTERNALACCOUNT_API_LATEST
LocalUserId登录用户的 EOS_EpicAccountId
ExternalAccountId希望获取信息的相关用户的外部账户ID
AccountType需要查询外部用户信息的账户类型。请参见EOS_EExternalCredentialType了解所有可用方法。

将用户信息接口句柄、EOS_UserInfo_QueryUserInfoByExternalAccountOptions 结构和你的回调信息传递给该函数。如果 EOS_HPlatform 在每帧执行,则你提供的回调会在操作完成后运行。在你的回调函数中,你可以查看 EOS_UserInfo_QueryUserInfoByExternalAccountCallbackInfo 结构的 ResultCode 字段,确定操作成功还是失败了。你还可以查看 TargetUserId(被检索到信息的玩家的 EOS_EpicAccountId)。如果成功,表示SDK已从服务器上缓存了最新的数据,供你随时检查。 你可以在一帧内查询多个外部账户ID。这些查询将被分批进行,当每一批全部完成后,会单独调用各个 EOS_UserInfo_QueryUserInfoByExternalAccountCallback 函数。

检查用户信息

在在线服务中检索到特定用户的相关信息后,就可使用 EOS_UserInfo_CopyUserInfo 函数请求该数据的副本。此函数需要包含下列信息的 EOS_UserInfo_CopyUserInfoOptions 结构:

属性
ApiVersionEOS_USERINFO_COPYUSERINFO_API_LATEST
LocalUserId已登录用户的 EOS_EpicAccountId
TargetUserId需要相关信息的用户 EOS_EpicAccountId。其可与 LocalUserId 相同。

传递用户信息接口句柄、EOS_UserInfo_CopyUserInfoOptions 结构和指向 EOS_UserInfo 数据结构的指针的地址。如缓存包含目标用户的相关信息,将填充 EOS_UserInfo 数据结构,而函数则返回 EOS_Success

此函数将复制数据,以防游戏代码正在访问的用户信息被用户信息接口删除。此操作意味着代码会占有内存且需负责进行释放。否则将造成内存泄漏。可将 EOS_UserInfo 对象传递到 EOS_UserInfo_Release 函数来释放此类对象。

对于非本地用户,EOS_UserInfo 结构中的多数信息将为空。这是为了确保EOS不向其他用户提供身份识别信息(PII)。EOS SDK只会固定填充 DisplayNameUserId 字段。

显示名与昵称

用户可以设置其他用户的昵称。如果用户为其他用户指定昵称,则其将包含在 Nickname 字段中,只有创建的用户才能使用。如昵称未指定,则 Nickname 字段将为空。

建议多多考虑用户习惯,避免出现重复昵称,因为本地用户可能会将指定的昵称视为私人信息。

外部用户信息

从1.6版本开始便可以获取用户绑定帐户的相关数据(即SDK的外部用户信息)。接口将公开数个API函数,以协助获取此数据。注意:和用户的 EOS_UserInfo 一样,用户的 EOS_UserInfo_ExternalUserInfo 不会被缓存并供获取,除非之前已调用 EOS_UserInfo_QueryUserInfo

EOS_UserInfo_GetExternalUserInfoCount 将返回目标用户可获取的外部用户信息条目数量。

EOS_UserInfo_CopyExternalUserInfoByIndex 将输出给定索引目标用户的外部用户信息。

EOS_UserInfo_CopyExternalUserInfoByAccountType 将输出需要获取信息的特定类型外部账户的目标用户的外部用户信息。在1.6版本中,外部用户信息的支持帐户类型有 EOS_EAT_PSNEOS_EAT_XBLEOS_EAT_NINTENDOEOS_EAT_STEAM

EOS_UserInfo_CopyExternalUserInfoByAccountId 将输出外部账户给定账户ID目标用户的外部用户信息。

完成时,请记得用外部用户信息条目来调用 EOS_UserInfo_ExternalUserInfo_Release,防止出现泄漏。