Como usar o Epic Online Services com o Xsolla Login

Como funciona

O Epic Online Services (EOS) é um serviço multiplataforma que torna mais fácil e rápido para os desenvolvedores lançarem, operarem e escalarem jogos com sucesso.

Para começar a usar o Epic Online Services, você precisa configurar o Login e criar interfaces para cada serviço. O Epic Online Services suportam autenticação com um provedor OpenID externo. Quando autenticado dessa forma, cada usuário do provedor externo recebe um OpenID interno no sistema Epic.

Quem pode usar

Parceiros que já integraram o Launcher e o Xsolla Login.

Como obtê-lo

• Crie e configure um projeto no Epic Games Developer Portal.
• Vincule o SDK do EOS.
• Inicialize o SDK do EOS.
• Autentique um usuário.

Criação e configuração de um projeto

1. Crie um novo produto no Epic Developer Portal.

2. Vá para Product Settings.

3. Abra a seção Client Credentials e pressione New client:

4. Crie um novo cliente e preencha os parâmetros da seguinte forma:
   • Digite o nome do cliente no campo Client Name;
   • No campo Client Role, selecione Game Server. Isso dará ao aplicativo acesso à criação de uma sessão.

5. Na seção Identity Providers, selecione o provedor OpenID e pressione CONFIGURE.

6. Pressione NEW ENTRY na aba que aparece e preencha os campos da seguinte maneira:
   • No campo UserInfo API Endpoint, insira https://login.xsolla.com/api/users/me. Este URL é o método Xsolla Login para o qual a Epic enviará uma solicitação para acessar os dados do usuário. Como resposta, ele recebe um arquivo JSON com dados do usuário;
   • No Método HTTP, selecione GET;
   • No campo Name of the AccountId, digite id. Esse será o nome do campo com o ID de usuário exclusivo;
   • Para o campo Name of the DisplayName, digite external_id. Esse será o nome do campo com o ID do usuário que pode ser usado por recursos externos.

7. Adicione o provedor de identidade criado a uma Sandbox. Para fazer isso, vá para a seção Sandboxes e pressione IDENTITY PROVIDERS.

8. Especifique o provedor na seção OpenID da janela.

Para configurar o SDK do EOS, você precisa de vários parâmetros:

• ID do Produto:

• ID de Sandbox:

• ID de Implantação:

Você pode encontrar a lista de implantações em Sandboxes > Deployment.

• ID do Cliente:

• Segredo do cliente:

Vincular o SDK do EOS

1. Vá para a seção Dashboard do Epic Developer Portal e baixe o SDK.

2. Descompacte o arquivo e vincule a biblioteca ao seu projeto:
   • Usando o SDK do EOS no Windows
   • Usando o SDK do EOS no macOS

Inicializar o SDK do EOS

Inicialize o SDK do EOS para obter acesso aos seus recursos.

Aqui está um exemplo do código de inicialização do SDK do EOS:

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);

Após a inicialização, a interface da plataforma fica disponível. A interface da plataforma é um objeto que fornece acesso a outros componentes do SDK do EOS. Para criar uma interface de plataforma, você precisará de IDs obtidos após a criação de um projeto.

Crie a Interface de Plataforma chamando a função EOS_Platform_Create com uma estrutura EOS_Platform_Options.

Descrição da estrutura EOS_Platform_Options:

/** 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;

Ao criar a interface da plataforma, especifique os próximos parâmetros:

• O valor do parâmetro PlatformOptions.bIsServer deve ser igual à Client Role especificada ao criar um cliente;
• PlatformOptions.CacheDirectory is an app’s working directory;
• PlatformOptions.ProductId, PlatformOptions.SandboxId, PlatformOptions.DeploymentId, PlatformOptions.ClientCredentials.ClientId e PlatformOptions.ClientCredentials.ClientSecret são valores recebidos ao criar e configurar um projeto.

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);

Quando o SDK do EOS é inicializado, você pode usar o objeto platformInterface para autenticar um usuário.

Autenticação de usuários

Etapas de preparação

Solicitação de autenticação do usuário

EOS_HConnect connectInterface = EOS_Platform_GetConnectInterface(platformInterface);

onde platformInterface é a interface de plataforma recebida na etapa Inicializar o SDK do EOS.

Depois de obter o objeto connectInterface, chame o método EOS_Connect_Login e passe o parâmetro da seguinte maneira:

• connectInterface é a interface de conexão recebida na etapa anterior;
• A estrutura EOS_Connect_LoginOptions. Veja sua descrição abaixo;
• void *clientData são dados passados de volta ao executar a função de retorno de chamada CompletionDelegate;
• CompletionDelegate é a função de retorno de chamada que deve ser executada após a conclusão do processo de autenticação.

A estrutura EOS_Connect_LoginOptions, que é passada para o método, deve ser preenchida da seguinte forma:

EOS_Connect_LoginOptions loginOptions;
loginOptions.ApiVersion = EOS_CONNECT_LOGIN_API_LATEST;
loginOptions.UserLoginInfo = NULL;
loginOptions.Credentials = &connectCredentials;

onde connectCredentials é a estrutura EOS_Connect_Credentials que inclui um token de usuário. Preencha-o da seguinte forma:

EOS_Connect_Credentials connectCredentials;
connectCredentials.ApiVersion = EOS_CONNECT_CREDENTIALS_API_LATEST;
connectCredentials.Token = "jwt token";
connectCredentials.Type = EOS_EExternalCredentialType::EOS_ECT_OPENID_ACCESS_TOKEN;

Adicione esses dados ao código:

• connectCredentials.Token, um token JWT do usuário. O jogo recebeu isso do Launcher como argumentos de inicialização.
• connectCredentials.Type, o tipo de autenticação. O exemplo é dado para a autenticação com um provedor OpenID externo.

Depois de criar e preencher estruturas com opções, chame o método EOS_Connect_Login:

EOS_Connect_Login(
  connectHandle,
  &loginOptions,
  NULL,
  &onLoginConnect
);

A função estática onLoginConnect é chamada quando o processo de autenticação é concluído. Declare-a da seguinte forma:

static void EOS_CALL onLoginConnect(const EOS_Connect_LoginCallbackInfo *Data);

onde *Data é um ponteiro para a estrutura EOS_Connect_LoginCallbackInfo que contém dados sobre a tentativa de autenticação.

A descrição da estrutura:

/** 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;

Exemplo da função de retorno de chamada:

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;
  }
}

Ao autenticar, o sistema verifica se há uma conta da Epic vinculada a uma conta de provedor externo.

Se esse tipo de conta Epic existir:

• No objeto Data, o parâmetro ResultCode retornará o valor EOS_EResult::EOS_Success (0);
• No objeto Data, o parâmetro LocalUserId retorna o ID da conta. Salve essa informação para interações posteriores com outros serviços Epic.

Se não houver nenhuma conta Epic vinculada:

• no objeto Data, o parâmetro ResultCode retornará o valor OS_EResult::EOS_InvalidUser (3);
• O parâmetro Data->ContinuanceToken retorna dados sobre a tentativa de autenticação. Salve essa informação para criar um novo usuário Epic e vinculá-lo a uma conta de provedor externo.

Para criar um novo usuário Epic, chame o método EOS_Connect_CreateUser. Veja o exemplo de código abaixo, onde:

• connectHandle é o objeto connectInterface que você já usou;
• options é a estrutura EOS_Connect_CreateUserOptions que contém o continuanceToken que você recebeu na etapa anterior;
• NULL é o clientData recebido na etapa anterior junto com o método EOS_Connect_Login;
• onCreateUser é uma função de retorno de chamada estática que é chamada após a criação de uma conta junto com a função da etapa anterior.

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

Exemplo da função onCreateUser:

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;

Se uma conta de usuário da Epic foi criada com êxito e vinculada a uma conta de provedor externo:

• No objeto Data, o parâmetro ResultCode retorna o valor EOS_EResult::EOS_Success (0);
• No objeto Data, o parâmetro LocalUserId retorna o ID da conta. Salve essa informação para interações posteriores com outros serviços Epic.