Лаунчер / Как использовать Epic Online Services с Авторизацией Иксолла

Как использовать Epic Online Services с Авторизацией Иксолла

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

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

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

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

Для партнеров, у которых уже подключены продукты Лаунчер и Авторизация Иксолла.

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

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

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

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

  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 — метод Авторизации Иксолла, на который Epic будет отправлять запрос для получения данных о пользователе. В ответ на запрос приходит JSON с параметрами пользователя;
    • в поле HTTP Method укажите GET;
    • в поле Name of the AccountId field укажите id — название поля с уникальным идентификатором пользователя;
    • в поле Name of the DisplayName field укажите external_id — название поля с идентификатором пользователя, который может использоваться внешними ресурсами.

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

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

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

  • Product ID:

  • Sandbox ID:

  • Deployment ID:

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

  • Client ID:

  • Client secret:

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

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

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

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

Описание структуры 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.ProductId, PlatformOptions.SandboxId, PlatformOptions.DeploymentId, PlatformOptions.ClientCredentials.ClientId, и PlatformOptions.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 для авторизации пользователя.

Авторизация пользователя

После инициализации SDK и создания объекта интерфейса платформы сделайте подготовительные работы и выполните запрос для авторизации пользователя.

Подготовка к авторизации

Перед тем, как выполнять методы для авторизации, настройте вызов метода EOS_Platform_Tick по таймеру. В качестве аргумента в метод необходимо передавать объект platformInterface, полученный ранее. Это обеспечит выполнение callback-функций, которые передаются в различные методы, включая методы авторизации.

Запрос для авторизации пользователя

Авторизация через внешнего провайдера осуществляется с помощью объекта connectInterface. Для получения объекта выполните следующий код:

Copy
Full screen
Small screen
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 должна быть заполнена следующим образом:

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

где connectCredentials — структура типа EOS_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;

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

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

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

  • в объекте 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-функция, которая вызывается после создания аккаунта, по аналогии с функцией из предыдущего шага.

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.

Была ли статья полезна?
Спасибо!
Что может сделать страницу еще лучше? Сообщение
Жаль, что так произошло
Расскажите, почему статья не была полезна. Сообщение
Спасибо за обратную связь!
Ваши мысли и идеи помогут нам улучшить ваш пользовательский опыт.
Оценить страницу
Оценить страницу
Что может сделать страницу еще лучше?

В другой раз

Спасибо за обратную связь!
Последнее обновление: 25 июня 2021

Нашли опечатку или ошибку в тексте? Выделите ее и нажмите Ctrl+Enter.

Сообщите о проблеме
Мы постоянно улучшаем качество нашей документации. Ваш отзыв поможет нам в этом.
Укажите email-адрес, чтобы мы могли связаться с вами
Спасибо за обратную связь!