Comment utiliser les Epic Online Services avec Xsolla Login

Comment ça marche

Les Epic Online Services (EOS) sont des services multiplateformes qui permettent aux développeurs de lancer, faire fonctionner et améliorer facilement et rapidement des jeux.

Pour commencer à utiliser les Epic Online Services, vous devez configurer Login et créer des interfaces pour chaque service. Les Epic Online Services prennent en charge l’authentification avec un fournisseur OpenID externe. Lorsqu’un utilisateur de fournisseur externe est authentifié de cette manière, il reçoit un OpenID interne dans le système Epic.

Qui peut l'utiliser

Les partenaires qui ont déjà intégré Launcher et Xsolla Login.

Comment configurer

• Créez et configurez un projet dans le portail du développeur Epic Games.
• Liez le SDK EOS.
• Initialisez le SDK EOS.
• Authentifiez l'utilisateur.

Créer et configurer un projet

1. Créez un nouveau produit dans le portail du développeur Epic.

2. Accédez à Product Settings.

3. Ouvrez la section Client Credentials et appuyez sur New client :

4. Créez un nouveau client et remplissez les paramètres comme suit :
   • Saisissez le nom du client dans le champ Client Name ;
   • Dans le champ Client Role, sélectionnez Game Server. Cela permettra à l'application de créer une session.

5. Dans la section Identity Providers, sélectionnez le fournisseur OpenID et appuyez sur CONFIGURE.

6. Appuyez sur NEW ENTRY dans l'onglet qui apparaît et remplissez les champs comme suit :
   • Dans le champ UserInfo API Endpoint, insérez https://login.xsolla.com/api/users/me. Cette URL est la méthode de connexion Xsolla à laquelle Epic enverra une demande d'accès aux données utilisateur. En réponse, il reçoit un fichier JSON contenant les données utilisateur ;
   • Dans le champ HTTP Method, sélectionnez GET ;
   • Pour le champ Name of the AccountId, saisissez id. Il s'agit du nom du champ contenant l'ID unique de l'utilisateur ;
   • Pour le champ Name of the DisplayName, saisissez external_id. Il s'agit du nom du champ contenant l'ID utilisateur qui peut être utilisé par des ressources externes.

7. Ajoutez le fournisseur d'identité créé à un bac à sable. Pour ce faire, allez dans la section Sandboxes et cliquez sur IDENTITY PROVIDERS.

8. Spécifiez le fournisseur dans la section OpenID de la fenêtre.

Pour configurer le SDK EOS, vous avez besoin d’un certain nombre de paramètres :

• Product ID :

• Sandbox ID :

• Deployment ID :

La liste des déploiements se trouve dans Sandboxes > Deployment.

• Client ID :

• Client secret:

Lier le SDK EOS

1. Accédez à la section Dashboard du portail du développeur Epic et téléchargez le SDK.

2. Décompressez l'archive et liez la bibliothèque à votre projet :
   • En utilisant le SDK EOS sous Windows ;
   • En utilisant le SDK EOS sous macOS

Initialiser le SDK EOS

Initialisez le SDK EOS pour accéder à ses fonctionnalités.

Voici un exemple de code d’initialisation du SDK 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);

Après l’initialisation, l’interface de la plateforme devient disponible. L’interface de plateforme est un objet qui permet d’accéder à d’autres composants du SDK EOS. Pour créer une interface de plateforme, vous aurez besoin des identifiants que vous avez obtenus lors de la création du projet.

Créez l’interface de la plateforme en appelant la fonction EOS_Platform_Create avec une structure EOS_Platform_Options.

Description de la structure 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;

Lors de la création de l’interface de la plateforme, spécifiez les paramètres suivants :

• La valeur du paramètre PlatformOptions.bIsServer doit être égale à Client Role que vous avez spécifié lors de la création du client ;
• PlatformOptions.CacheDirectory est le répertoire de travail de l’application ;
• PlatformOptions.ProductId, PlatformOptions.SandboxId, PlatformOptions.DeploymentId, PlatformOptions.ClientCredentials.ClientId et PlatformOptions.ClientCredentials.ClientSecret sont des valeurs que vous avez reçues lors de la création et de la configuration du projet.

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

Une fois le SDK EOS initialisé, utilisez l’objet platformInterface pour authentifier l’utilisateur.

Authentifier l'utilisateur

Étapes de préparation

Requête d'authentification utilisateur

EOS_HConnect connectInterface = EOS_Platform_GetConnectInterface(platformInterface);

où platformInterface est l’interface de plateforme reçue lors de l’étape Initialisez le SDK EOS.

Après avoir obtenu l’objet connectInterface, appelez la méthode EOS_Connect_Login et passez les paramètres suivants :

• connectInterface est l’interface de connexion reçue à l’étape précédente ;
• La structure EOS_Connect_LoginOptions. Voir sa description ci-dessous ;
• void *clientData est la donnée renvoyée lors de l’exécution de la fonction de rappel CompletionDelegate ;
• CompletionDelegate est la fonction de rappel qui doit être exécutée après la fin du processus d’authentification.

La structure EOS_Connect_LoginOptions, qui est passée à la méthode, doit être remplie comme suit :

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

où connectCredentials est la structure EOS_Connect_Credentials qui comprend un jeton utilisateur. Remplissez-la comme suit :

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

Ajoutez ces données au code :

• connectCredentials.Token — jeton JWT utilisateur. Le jeu l’a reçu du Launcher comme argument de lancement.
• connectCredentials.Type — type d’authentification. L’exemple est donné pour l’authentification avec un fournisseur OpenID externe.

Après avoir créé et rempli les structures avec des options, appelez la méthode EOS_Connect_Login:

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

La fonction statique onLoginConnect est appelée lorsque le processus d’authentification est terminé. Déclarez-la comme suit :

static void EOS_CALL onLoginConnect(const EOS_Connect_LoginCallbackInfo *Data);

où *Data est un pointeur sur la structure EOS_Connect_LoginCallbackInfo qui contient des données sur la tentative d’authentification.

Description de la structure :

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

Exemple de fonction de rappel :

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

Lors de l’authentification, le système vérifie s’il existe un compte Epic lié au compte de fournisseur externe.

Si ce type de compte Epic existe :

• Dans l’objet Data, le paramètre ResultCode renvoie la valeur EOS_EResult::EOS_Success (0) ;
• Dans l’objet Data, le paramètre LocalUserId renvoie l’identifiant du compte. Conservez ce paramètre pour une interaction ultérieure avec d’autres services Epic.

S’il n’y a pas de compte Epic lié :

• Dans l’objet Data, le paramètre ResultCode renvoie la valeur OS_EResult::EOS_InvalidUser (3) ;
• Le paramètre Data->ContinuanceToken renvoie des données sur la tentative d’authentification. Enregistrez ces données pour créer un nouvel utilisateur Epic et le lier à un compte de fournisseur externe.

Pour créer un nouvel utilisateur Epic, appelez la méthode EOS_Connect_CreateUser. Voir l’exemple de code ci-dessous, où :

• connectHandle est l’objet connectInterface que vous avez déjà utilisé ;
• options est la structure EOS_Connect_CreateUserOptions qui contient le continuanceToken que vous avez reçu à l’étape précédente ;
• NULL est le clientData reçu à l’étape précédente avec la méthode EOS_Connect_Login ;
• onCreateUser est une fonction de rappel statique qui est appelée après la création d’un compte avec la fonction de l’étape précédente.

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

Exemple de la fonction 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 un compte d’utilisateur Epic a été créé avec succès et lié à un compte de fournisseur externe :

• Dans l’objet Data, le paramètre ResultCode renvoie la valeur EOS_EResult::EOS_Success (0) ;
• Dans l’objet Data, le paramètre LocalUserId renvoie l’ID du compte. Conservez ce paramètre pour une interaction ultérieure avec d’autres services Epic.