Cómo utilizar Epic Online Services con Xsolla Login

Cómo funciona

Epic Online Services (EOS) sse compone de servicios multiplataforma que facilitan y agilizan a los desarrolladores el lanzamiento, la explotación y el redimensionamiento de juegos.

Para empezar a utilizar Epic Online Services, debe configurar Login y crear interfaces para cada servicio. Epic Online Services admite la autenticación con un proveedor OpenID externo. Cuando se autentica de esta forma, cada usuario del proveedor externo recibe un OpenID interno en el sistema de Epic.

¿Quién puede utilizarlo?

Socios que ya han integrado Launcher y Xsolla Login.

Cómo conseguirlo

• Cree y configure un proyecto en el portal del desarrollador de Epic Games.
• Vincule el SDK de EOS.
• Inicialice el SDK de EOS.
• Autentique a un usuario.

Crear y configurar un proyecto

1. Cree un nuevo Producto en Epic Developer Portal.

2. Vaya a Product Settings.

3. Abra la sección Client Credentials y pulse New client:

4. Cree un nuevo cliente y rellene los parámetros de la siguiente manera:
   • Escriba el nombre del cliente en el campo Client Name;
   • En el campo Client Role, seleccione Game Server. Esto dará acceso a la aplicación para crear una sesión.

5. En la sección Identity Provider, seleccione el proveedor OpenID y pulse CONFIGURE.

6. Pulse NEW ENTRY en la pestaña que aparece y rellene los campos como se indica a continuación:
   • En el campo UserInfo API Endpoint, inserte https://login.xsolla.com/api/users/me. Esta URL es el método de Xsolla Login al que Epic enviará una solicitud para acceder a los datos del usuario. Como respuesta, recibe un archivo JSON con los datos del usuario;
   • En el método HTTP , seleccione GET;
   • Para el campo Name of the AccountId, escriba id. Será el nombre del campo con el ID único de usuario;
   • Para el campo Name of the DisplayName, escriba external_id. Será el nombre del campo con el ID de usuario que pueden utilizar los recursos externos.

7. Añada el proveedor de identidad creado a un Aislador de proceso (Sandbox). Para ello, vaya a la sección Sandboxes y pulse IDENTITY PROVIDERS.

8. Especifique el proveedor en la sección OpenID de la ventana.

Para establecer el SDK de EOS, necesita una serie de parámetros:

• Product ID:

• ID del aislador de proceso (sandbox):

• ID de implementación:

Encontrará la lista de implementaciones en Sandboxes > Deployment.

• ID de cliente:

• Secreto de cliente:

Vincular el SDK de EOS

1. Vaya a la sección Dashboard del Epic Developer Portal y descargue el SDK.

2. Descomprima el archivo y vincule la biblioteca a su proyecto:
   • Uso del SDK de EOS en Windows
   • Uso del SDK de EOS en macOS

Inicializar el SDK de EOS

Inicialice el SDK de EOS para acceder a sus funciones.

A continuación se muestra un ejemplo del código de inicialización del SDK de 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);

Tras la inicialización, la interfaz de plataforma pasa a estar disponible. La interfaz de plataforma es un objeto que proporciona acceso a otros componentes del SDK de EOS. Para crear una interfaz de plataforma, necesitarás los ID que obtuviste tras crear un proyecto.

Cree la interfaz de plataforma llamando a la función EOS_Platform_Create con una estructura EOS_Platform_Options.

Descripción de la estructura 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;

Al crear la interfaz de plataforma, especifique los siguientes parámetros:

• El valor del parámetro PlatformOptions.bIsServer debe ser igual al de Client Role que especificó al crear un cliente;
• PlatformOptions.CacheDirectory es el directorio de trabajo de una aplicación;
• PlatformOptions.ProductId, PlatformOptions.SandboxId, PlatformOptions.DeploymentId, PlatformOptions.ClientCredentials.ClientId y PlatformOptions.ClientCredentials.ClientSecret son valores que recibió al crear y configurar un proyecto.

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

Cuando se inicializa el SDK de EOS, puede utilizar el objeto platformInterface para autenticar a un usuario.

Autenticar un usuario

Pasos de preparación

Solicitud de autenticación de usuario

EOS_HConnect connectInterface = EOS_Platform_GetConnectInterface(platformInterface);

en el cual platformInterface es la interfaz de plataforma recibida en el paso Initialize the EOS SDK.

Tras obtener el objeto connectInterface, llame al método EOS_Connect_Login y transmítale los siguientes parámetros:

• connectInterface es la interfaz de conexión recibida en el paso anterior;
• la estructura EOS_Connect_LoginOptions. Consulte la descripción que aparece a continuación;
• void *clientData son los datos que se devuelven al ejecutar la función de devolución de llamada CompletionDelegate;
• CompletionDelegate es la función de devolución de llamada que debe ejecutarse tras finalizar el proceso de autenticación.

La estructura EOS_Connect_LoginOptions, que se transmite al método, debe rellenarse como se indica a continuación:

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

donde connectCredentials es la estructura EOS_Connect_Credentials que incluye un token de usuario. Rellénela de la siguiente manera:

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

Agregue estos datos al código:

• connectCredentials.Token, un token JWT del usuario. El juego lo recibe de Launcher como argumentos de lanzamiento.
• connectCredentials.Type, el tipo de autenticación. El ejemplo se ofrece para la autenticación con un proveedor de OpenID externo.

Después de crear y rellenar las estructuras con opciones, llame al método EOS_Connect_Login:

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

La función estática onLoginConnect se llama cuando finaliza el proceso de autenticación. Declárela como se indica a continuación:

static void EOS_CALL onLoginConnect(const EOS_Connect_LoginCallbackInfo *Data);

donde *Data es un puntero que señala hacia la estructura EOS_Connect_LoginCallbackInfo que contiene datos sobre el intento de autenticación.

La descripción de la estructura:

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

Ejemplo de la función de devolución de llamada:

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

Al autenticarse, el sistema comprueba si existe una cuenta de Epic vinculada a una cuenta del proveedor externo.

Si existe este tipo de cuenta de Epic:

• En el objeto Data, el parámetro ResultCode devuelve el valor EOS_EResult::EOS_Success (0);
• En el objeto Data, el parámetro LocalUserId devuelve el ID de la cuenta. Guárdelo para futuras interacciones con otros servicios de Epic.

Si no hay ninguna cuenta de Epic vinculada:

• En el objeto Data, el parámetro ResultCode devuelve el valor OS_EResult::EOS_InvalidUser (3);
• El parámetro Data->ContinuanceToken devuelve datos sobre el intento de autenticación. Guarde esto para crear un nuevo usuario de Epic y vincularlo con una cuenta del proveedor externo.

Para crear un nuevo usuario de Epic, llame al método EOS_Connect_CreateUser. Vea el ejemplo de código a continuación, en el cual

• connectHandle es el objeto connectInterface que ya utilizó;
• options es la estructura EOS_Connect_CreateUserOptions que contiene el continuanceToken que recibió en el paso anterior;
• NULL es el clientData recibido en el paso anterior junto con el método EOS_Connect_Login;
• onCreateUser es una función de devolución de llamada estática que se invoca después de crear una cuenta junto con la función del paso anterior.

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

Ejemplo de la función 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;

Si se creó correctamente una cuenta de usuario de Epic y se vinculó a una cuenta del proveedor externo:

• En el objeto Data, el parámetro ResultCode devuelve el valor EOS_EResult::EOS_Success (0);
• En el objeto Data, el parámetro LocalUserId devuelve el ID de la cuenta. Guárdelo para futuras interacciones con otros servicios de Epic.