Как использовать Epic Online Services с Xsolla Login

Как это работает

Epic Online Services — это межплатформенные службы, которые упрощают и ускоряют запуск, поддержку и масштабирование игр.

Для работы с Epic Online Services необходимо настроить авторизацию и создать интерфейс для каждого сервиса. Epic Online Services поддерживает авторизацию через внешнего провайдера OpenID. При такой авторизации каждому пользователю внешнего провайдера присваивается внутренний ID в системе Epic.

Для кого подходит

Для партнеров, у которых уже подключены продукты Launcher и Xsolla Login.

Как настроить

• Создайте и настройте проект в портале разработчика Epic Online Services.
• Подключите EOS SDK.
• Инициализируйте EOS SDK.
• Выполните авторизацию пользователя.

Создание и настройка проекта 

1. Создайте новый продукт на портале разработчика Epic.

2. Откройте настройки продукта.

3. Откройте раздел Client Credentials, нажмите New client:

4. Заполните параметры создания клиента следующим образом: 
   • в поле Client Name укажите имя клиента;
   • в поле Client Role выберите Game Server, чтобы приложение получило права для создания сессии.

5. В разделе Identity Providers выберите провайдер OpenID и нажмите CONFIGURE.

6. В появившейся панели нажмите NEW ENTRY и заполните следующие поля:
   • в поле UserInfo API Endpoint укажите https://login.xsolla.com/api/users/me — метод Xsolla Login, на который Epic будет отправлять запрос для получения данных о пользователе. В ответ на запрос приходит JSON с параметрами пользователя;
   • в поле HTTP Method укажите GET;
   • в поле Name of the AccountId field укажите id — название поля с уникальным ID пользователя;
   • в поле Name of the DisplayName field укажите external_id — название поля с ID пользователя, который может использоваться внешними ресурсами.

7. Привяжите нового провайдера к тестовой среде. В разделе Sandboxes нажмите IDENTITY PROVIDERS. 

8. В разделе OpenID открывшейся панели укажите провайдера.

Для дальнейшей настройки EOS SDK вам понадобятся следующие параметры:

• Product ID:

• Sandbox ID:

• Deployment ID:

Список сборок (deployments) находится в разделе Sandboxes > Deployment. 

• Client ID:

• Client secret:

Подключение EOS SDK

1. Загрузите SDK на странице Dashboard портала разработчика Epic. 

2. Распакуйте архив и подключите библиотеку к своему проекту:
   • Инструкция по подключению EOS SDK на платформе Windows
   • Инструкция по подключению EOS SDK на платформе macOS

Инициализация EOS SDK

Инициализируйте EOS SDK для получения доступа к его функциональности.

Пример кода инициализации EOS SDK:

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

После инициализации становится доступен интерфейс платформы platform interface — объект, который обеспечивает доступ к другим компонентам EOS SDK. Для создания объекта интерфейса платформы вам понадобятся ID, полученные при создании проекта.

Для создания интерфейса платформы используется метод EOS_Platform_Create, который в качестве аргумента принимает структуру типа EOS_Platform_Options.

Описание структуры 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;

При создании интерфейса платформы укажите следующие параметры:

• PlatformOptions.bIsServer — значение этого параметра должно совпадать с Client Role, указанным при создании клиента;
• PlatformOptions.CacheDirectory — как правило, рабочая директория приложения;
• PlatformOptions.ProductId, PlatformOptions.SandboxId, PlatformOptions.DeploymentId, PlatformOptions.ClientCredentials.ClientId, и PlatformOptions.ClientCredentials.ClientSecret — значения, полученные при создании и настройке проекта.

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_HConnect connectInterface = EOS_Platform_GetConnectInterface(platformInterface);

где platformInterface — интерфейс платформы, полученный в разделе Инициализация EOS SDK.

После получения объекта connectInterface вызовите метод EOS_Connect_Login, передав в него следующие параметры:

• connectInterface — Сonnect Interface, полученный на предыдущем шаге;
• структуру EOS_Connect_LoginOptions (описание структуры приведено ниже);
• void *clientData — данные, возвращаемые при выполнении callback-функции CompletionDelegate;
• CompletionDelegate — callback-функция, которую необходимо выполнить после окончания процесса авторизации.

Передаваемая в метод структура типа EOS_Connect_LoginOptions должна быть заполнена следующим образом:

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

где connectCredentials — структура типа EOS_Connect_Credentials, которая содержит в себе токен пользователя. Заполните ее следующим образом:

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:

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

Статическая функция onLoginConnect вызывается после завершения процесса авторизации пользователя и объявляется следующим образом:

static void EOS_CALL onLoginConnect(const EOS_Connect_LoginCallbackInfo *Data);

где *Data — указатель на структуру типа EOS_Connect_LoginCallbackInfo, содержащую данные о попытке авторизации.

Описание структуры:

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

Пример callback-функции:

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, к которому привязан аккаунт внешнего провайдера.

Если такой аккаунт существует:

• в объекте 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 — структура типа EOS_Connect_CreateUserOptions, которая содержит continuanceToken, полученный на предыдущем шаге;
• NULL — данные clientData, полученные по аналогии с методом EOS_Connect_Login из предыдущего шага;
• onCreateUser — статическая callback-функция, которая вызывается после создания аккаунта, по аналогии с функцией из предыдущего шага.

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

Пример функции 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;

При успешном создании аккаунта Epic и его привязке к аккаунту внешнего провайдера:

• в объекте Data параметр ResultCode возвращается равным EOS_EResult::EOS_Success (0);
• в объекте Data в значении параметра LocalUserId возвращается ID аккаунта. Сохраните его для дальнейшей работы с другими сервисами Epic.