如何将Epic在线服务与艾克索拉登录管理器配合使用

运行机制

Epic在线服务(EOS)是一组跨平台服务,可让开发者更轻松、更快捷地成功发行、运营游戏及实现规模化。

要使用Epic在线服务,需先设置登录管理器并为各个服务创建接口。Epic在线服务支持使用外部OpenID提供商进行用户认证。采用该方式认证时,各外部提供商用户将收到一个Epic系统中的内部OpenID。

适用对象

集成了启动器艾克索拉登录管理器的合作伙伴。

如何获取

创建并设置项目

  1. Epic开发者门户中创建一个新产品。
  1. 前往Product Settings
  1. 打开Client Credentials部分,然后点击New client
  1. 新建一个客户端并填写如下参数:
    • Client Name字段中输入客户端名称;
    • Client Role字段中,选择Game Server。这将授予应用创建会话的权限。
  1. Identity Providers部分,选择OpenID提供商,然后点击CONFIGURE
  1. 在显示的选项卡中点击NEW ENTRY,并填写如下字段:
    • UserInfo API Endpoint字段中,插入https://login.xsolla.com/api/users/me. 该URL是艾克索拉登录管理器方法,Epic向其发送访问用户数据的请求。作为响应,它将一个收到包含用户数据的JSON文件;
    • 在HTTP Method中,选择GET
    • 对于Name of the AccountId字段,输入id。它将是包含唯一用户ID的字段的名称;
    • 对于Name of the DisplayName field,输入external_id。它将是外部资源可用的用户ID的字段名称。
  1. 将所创建的身份提供商添加至沙盒。方法是前往Sandboxes部分,然后点击IDENTITY PROVIDERS
  1. 在窗口的OpenID部分指定提供商。

要设置EOS SDK,您需要以下参数:

  • 产品ID:

  • 沙盒ID:
  • 部署ID:

您可在Sandboxes > Deployment中找到部署列表。

  • 客户端ID:
  • 客户端密钥:
  1. 前往Epic开发者门户的Dashboard部分并下载SDK。
  1. 解压缩文件包并将库关联至您的项目:

初始化EOS SDK

初始化EOS SDK以访问其功能。

以下是EOS SDK初始化代码的示例:

Copy
Full screen
Small screen
EOS_InitializeOptions SDKOptions;
SDKOptions.ApiVersion = EOS_INITIALIZE_API_LATEST;
SDKOptions.AllocateMemoryFunction = NULL;
SDKOptions.ReallocateMemoryFunction = NULL;
SDKOptions.ReleaseMemoryFunction = NULL;
SDKOptions.ProductName = "MyProduct";
SDKOptions.ProductVersion = "1.0";
SDKOptions.Reserved = NULL;
SDKOptions.SystemInitializeOptions = NULL;
EOS_Initialize(&SDKOptions);

初始化后,平台接口即可用。平台接口是提供其他EOS SDK组件访问权限的对象。要创建平台接口,需要用到创建项目后获得的一些ID。

通过调用包含EOS_Platform_Options结构的EOS_Platform_Create函数创建平台接口。

EOS_Platform_Options结构描述如下:

Copy
Full screen
Small screen
/** API version of EOS_Platform_Create. */
int32_t ApiVersion;
/** A reserved field that should always be nulled. */
void* Reserved;
/** The product id for the running application, found on the dev portal */
const char* ProductId;
/** The sandbox id for the running application, found on the dev portal */
const char* SandboxId;
/** Set of service permissions associated with the running application */
EOS_Platform_ClientCredentials ClientCredentials;
/** Is this running as a server */
EOS_Bool bIsServer;
/** Only used by Player Data Storage. Must be null initialized if unused. 256-bit Encryption Key for file encryption in hexadecimal format (64 hex chars)*/
const char* EncryptionKey;
/** The override country code to use for the logged in user. (EOS_COUNTRYCODE_MAX_LENGTH)*/
const char* OverrideCountryCode;
/** The override locale code to use for the logged in user. This follows ISO 639. (EOS_LOCALECODE_MAX_LENGTH)*/
const char* OverrideLocaleCode;
/** The deployment id for the running application, found on the dev portal */
const char* DeploymentId;
/** Platform creation flags, e.g. EOS_PF_LOADING_IN_EDITOR. This is a bitwise-or union of the defined flags. */
uint64_t Flags;
/** Only used by Player Data Storage. Must be null initialized if unused. Cache directory path. Absolute path to the folder that is going to be used for caching temporary data. The path is created if it's missing. */
const char* CacheDirectory;
/**
 * A budget, measured in milliseconds, for EOS_Platform_Tick to do its work. When the budget is met or exceeded (or if no work is available), EOS_Platform_Tick will return.
 * This allows your game to amortize the cost of SDK work across multiple frames in the event that a lot of work is queued for processing.
 * Zero is interpreted as "perform all available work"
 */
uint32_t TickBudgetInMilliseconds;

创建平台界面时,指定接下来的参数:

  • PlatformOptions.bIsServer参数的值必须等于创建客户端时指定的Client Role
  • PlatformOptions.CacheDirectory是应用的工作路径;
  • PlatformOptions.ProductIdPlatformOptions.SandboxIdPlatformOptions.DeploymentIdPlatformOptions.ClientCredentials.ClientIdPlatformOptions.ClientCredentials.ClientSecret是创建及设置项目时收到的值。

Copy
Full screen
Small screen
EOS_Platform_Options PlatformOptions;
PlatformOptions.ApiVersion = EOS_PLATFORM_OPTIONS_API_LATEST;
PlatformOptions.Reserved = NULL;
PlatformOptions.bIsServer = false;
PlatformOptions.EncryptionKey = NULL;
PlatformOptions.OverrideCountryCode = NULL;
PlatformOptions.OverrideLocaleCode = NULL;
PlatformOptions.Flags = 0;
PlatformOptions.CacheDirectory = "path/to/cache/directory";

PlatformOptions.ProductId = "product id";
PlatformOptions.SandboxId = "sandbox id";
PlatformOptions.DeploymentId = "deployment id";
PlatformOptions.ClientCredentials.ClientId = "client id";
PlatformOptions.ClientCredentials.ClientSecret = "client secret";
EOS_HPlatform platformInterface = EOS_Platform_Create(&PlatformOptions);

EOS SDK初始化后,即可使用platformInterface对象来认证用户。

认证用户

初始化EOS SDK并创建平台接口对象后,请按照准备步骤进行操作,并运行用户认证请求

准备步骤

执行认证方法之前,设置在计时器上调用EOS_Platform_Tick。将platformInterface对象作为参数传入该方法。这可确保执行传入多个方法(包括授权方法)中的回调函数。

用户认证请求

使用外部提供商的认证通过connectInterface对象执行。要获取该对象,请运行以下代码:
Copy
Full screen
Small screen
EOS_HConnect connectInterface = EOS_Platform_GetConnectInterface(platformInterface);

其中,platformInterface是在初始化EOS SDK步骤中收到的平台接口。

获取connectInterface对象后,请调用EOS_Connect_Login方法并传递如下参数:

  • connectInterface是上一步中收到的连接接口;
  • EOS_Connect_LoginOptions结构。请参阅下方描述;
  • void *clientData是执行CompletionDelegate回调函数时传回的数据;
  • CompletionDelegate是完成认证过程后必须执行的回调函数。

传入方法的EOS_Connect_LoginOptions结构必须填充如下:

Copy
Full screen
Small screen
EOS_Connect_LoginOptions loginOptions;
loginOptions.ApiVersion = EOS_CONNECT_LOGIN_API_LATEST;
loginOptions.UserLoginInfo = NULL;
loginOptions.Credentials = &connectCredentials;

其中,connectCredentialsEOS_Connect_Credentials包含用户令牌的结构。填充如下:

Copy
Full screen
Small screen
EOS_Connect_Credentials connectCredentials;
connectCredentials.ApiVersion = EOS_CONNECT_CREDENTIALS_API_LATEST;
connectCredentials.Token = "jwt token";
connectCredentials.Type = EOS_EExternalCredentialType::EOS_ECT_OPENID_ACCESS_TOKEN;

将以下数据加入代码:

  • connectCredentials.Token,用户JWT令牌。游戏从启动器收到该令牌(以启动器参数形式)。
  • connectCredentials.Type,认证类型。所给示例为使用外部OpenID提供商进行认证的示例。

用选项创建并填充结构后,调用EOS_Connect_Login方法:

Copy
Full screen
Small screen
EOS_Connect_Login(
  connectHandle,
  &loginOptions,
  NULL,
  &onLoginConnect
);

onLoginConnect静态函数在认证过程结束时调用。作如下声明:

Copy
Full screen
Small screen
static void EOS_CALL onLoginConnect(const EOS_Connect_LoginCallbackInfo *Data);

其中,*Data是包含认证尝试数据的EOS_Connect_LoginCallbackInfo的结构的指针。

结构描述如下:

Copy
Full screen
Small screen
/** Result code for the operation. EOS_Success is returned for a successful query, otherwise one of the error codes is returned. See eos_result.h */
EOS_EResult ResultCode;
/** Context that was passed into EOS_Connect_Login */
void* ClientData;
/** If login was successful, this is the account ID of the local player that logged in */
EOS_ProductUserId LocalUserId;
/**
* If the user was not found with credentials passed into EOS_Connect_Login,
* this continuance token can be passed to either EOS_Connect_CreateUser
* or EOS_Connect_LinkAccount to continue the flow
*/
EOS_ContinuanceToken ContinuanceToken;

回调函数示例:

Copy
Full screen
Small screen
static void EOS_CALL onLoginConnect(const EOS_Connect_LoginCallbackInfo *Data) {
  if (Data->ResultCode == EOS_EResult::EOS_InvalidUser) {
    continuanceToken = Data->ContinuanceToken;
  }
  if (Data->ResultCode == EOS_EResult::EOS_Success) {
    userId = Data->LocalUserId;
  }
}

认证过程中,系统检查是否存在一个已关联外部提供商帐户的Epic帐户。

如果该类型的Epic帐户存在:

  • Data对象中,ResultCode参数返回值EOS_EResult::EOS_Success (0)
  • Data对象中,LocalUserId参数返回帐户ID。请保存该信息以便后续与其他Epic服务交互时使用。

如果没有关联的Epic帐户:

  • Data对象中,ResultCode参数返回值OS_EResult::EOS_InvalidUser (3)
  • Data->ContinuanceToken参数返回关于认证尝试的数据。请保存该信息以新建一个Epic用户,并将其与外部提供商帐户关联。

要新建一个Epic用户,请调用EOS_Connect_CreateUser方法。请参考下方代码示例,其中:

  • connectHandle是已使用的connectInterface对象;
  • options是包含上一步中收到的continuanceTokenEOS_Connect_CreateUserOptions结构;
  • NULL是同上一步中的EOS_Connect_Login方法收到的clientData
  • onCreateUser是静态回调函数,在同上一步中的函数一起创建帐户后调用。

Copy
Full screen
Small screen
EOS_Connect_CreateUserOptions options;
options.ApiVersion = EOS_CONNECT_CREATEUSER_API_LATEST;
options.ContinuanceToken = continuanceToken;
EOS_Connect_CreateUser(
  connectHandle,
  &options,
  NULL,
  &onCreateUser
);

onCreateUser函数示例:

Copy
Full screen
Small screen
static void EOS_CALL onCreateUser(const EOS_Connect_CreateUserCallbackInfo *Data) {
  if (Data->ResultCode == EOS_EResult::EOS_Success) {
    userId = Data->LocalUserId;
  }
}
/** Result code for the operation. EOS_Success is returned for a successful query, otherwise one of the error codes is returned. See eos_result.h */
EOS_EResult ResultCode;
/** Context that was passed into EOS_Connect_CreateUser */
void* ClientData;
/** Account ID of the local player created by this operation */
EOS_ProductUserId LocalUserId;

如果成功创建了Epic用户帐户并关联了外部提供商帐户:

  • Data对象中,ResultCode参数返回值EOS_EResult::EOS_Success (0)
  • Data对象中,LocalUserId参数返回帐户ID。请保存该信息以便后续与其他Epic服务交互时使用。

本文对您的有帮助吗?
谢谢!
我们还有其他可改进之处吗? 留言
非常抱歉
请说明为何本文没有帮助到您。 留言
感谢您的反馈!
我们会查看您的留言并运用它改进用户体验。
上次更新时间: 2024年7月29日

发现了错别字或其他内容错误? 请选择文本,然后按Ctrl+Enter。

报告问题
我们非常重视内容质量。您的反馈将帮助我们做得更好。
请留下邮箱以便我们后续跟进
感谢您的反馈!