So nutzen Sie den Epic Online Services in Xsolla Login

So funktioniert's

Epic Online Services (EOS) sind plattformübergreifende Dienste, mit denen Entwickler Spiele einfacher und schneller veröffentlichen, betreiben und skalieren können.

Sie müssen Login einrichten und für jeden Dienst Schnittstellen erstellen, um die Epic Online Services verwenden zu können. Epic Online Services unterstützen die Authentifizierung mit einem externen OpenID-Anbieter. Bei dieser Authentifizierung erhält jeder Benutzer des externen Anbieters eine interne OpenID im Epic-System.

Für wen ist es

Partner, die bereits das Launcher und Xsolla Login integriert haben.

Wie komme ich dazu

• Erstellen Sie ein Projekt im Epic Games Developer Portal und richten Sie es ein.
• Verknüpfen Sie das EOS SDK.
• Initialisieren Sie das EOS SDK.
• Authentifizieren Sie einen Benutzer.

Projekt erstellen und einrichten

1. Erstellen Sie ein neues Projekt im Epic Developer Portal.

2. Navigieren Sie zu Product Settings.

3. Scrollen Sie zum Abschnitt Client Credentials, und klicken Sie auf New client:

4. Erstellen Sie einen neuen Client, und vervollständigen Sie die Parameter wie folgt:
   • Geben Sie den Namen des Clients im Feld Client Name ein;
   • Wählen Sie im Feld Client Role die Option Game Server aus. Dadurch kann die Anwendung Sitzungen erstellen.

5. Klicken Sie im Abschnitt Identity Providers neben dem Anbieter OpenID auf CONFIGURE.

6. Klicken Sie im daraufhin angezeigten Reiter auf NEW ENTRY, und füllen Sie die Felder wie folgt aus:
   • Fügen Sie im Feld UserInfo API Endpoint die Bezeichnung https://login.xsolla.com/api/users/me ein. Bei dieser URL handelt es sich um die Xsolla Login-Methode, an die Epic eine Anfrage für den Zugriff auf Benutzerdaten senden wird. Als Antwort erhalten Sie eine JSON-Datei mit den Benutzerdaten;
   • Wählen Sie im Feld HTTP Method die Option GET aus;
   • Im Feld Name of the AccountId geben Sie bitte id ein. Dabei handelt es sich um den Namen des Felds mit der individuellen Benutzer-ID;
   • Im Feld Name of the DisplayName field geben Sie bitte external_id ein. Dabei handelt es sich um den Namen des Feldes mit der Benutzer-ID, die von externen Ressourcen verwendet werden darf.

7. Fügen Sie den erstellten Identitätsanbieter einer Testumgebung hinzu. Scrollen Sie dazu zum Abschnitt Sandboxes, und klicken Sie auf IDENTITY PROVIDERS.

8. Legen Sie den Anbieter im Abschnitt OpenID fest.

Zum Einrichten des EOS SDK benötigen Sie eine Reihe von Parametern:

• Product ID:

• Sandbox ID:

• Deployment ID:

Die Liste der Bereitstellungen finden Sie unter Sandboxes > Deployment.

• Client ID:

• Client secret key:

EOS SDK verknüpfen

1. Wechseln Sie ins Dashboard des Epic Developer Portal, und laden Sie das SDK herunter.

2. Entpacken Sie das Archiv, und verknüpfen Sie die Bibliothek mit Ihrem Projekt:
   • Nutzung des EOS SDK unter Windows
   • Nutzung des EOS SDK unter macOS

EOS SDK initialisieren

Initialisieren Sie das EOS SDK, um Zugriff auf dessen Features zu erhalten.

Beispielhafter Initialisierungscode des 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);

Nach der Initialisierung ist die Plattformschnittstelle verfügbar. Die Plattformschnittstelle ist ein Objekt, das den Zugriff auf andere EOS SDK-Komponenten ermöglicht. Für das Erstellen einer Plattformschnittstelle benötigen Sie jene IDs, die Sie nach dem Erstellen eines Projekts erhalten haben.

Erstellen Sie die Plattformschnittstelle durch Aufruf der Funktion EOS_Platform_Create mit einer EOS_Platform_Options-Struktur.

EOS_Platform_Options-Strukturbeschreibung:

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

Geben Sie beim Erstellen der Plattformschnittstelle die folgenden Parameter an:

• Der Wert des Parameters PlatformOptions.bIsServer muss mit der von Ihnen beim Erstellen eines Clients angegebenen Client Role übereinstimmen;
• PlatformOptions.CacheDirectory ist das Arbeitsverzeichnis einer App;
• PlatformOptions.ProductId, PlatformOptions.SandboxId, PlatformOptions.DeploymentId, PlatformOptions.ClientCredentials.ClientId und PlatformOptions.ClientCredentials.ClientSecret sind Werte, die Sie beim Erstellen und Einrichten eines Projekts erhalten haben.

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

Nach Initialisierung des EOS SDK können Sie mithilfe des Objekts platformInterface Benutzer authentifizieren.

Benutzer authentifizieren

Schritte zur Vorbereitung

Benutzerauthentifizierungsanfrage

EOS_HConnect connectInterface = EOS_Platform_GetConnectInterface(platformInterface);

wobei platformInterface jene Plattformschnittstelle darstellt, die im Schritt EOS SDK initialisieren empfangen wurde.

Rufen Sie nach dem Abrufen des connectInterface-Objekts die Methode EOS_Connect_Login auf, und übermitteln Sie den Parameter wie folgt:

• connectInterface ist die im vorherigen Schritt erhaltene verknüpfte Schnittstelle;
• Die EOS_Connect_LoginOptions-Struktur. Siehe folgende Beschreibung;
• void *clientData sind Daten, die beim Aufruf der Rückruffunktion CompletionDelegate zurückgegeben werden;
• CompletionDelegate ist die Rückruffunktion, welche nach Abschluss des Authentifizierungsvorgangs ausgeführt werden muss.

Die an die Methode übermittelte EOS_Connect_LoginOptions-Struktur muss wie folgt ausgefüllt werden:

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

wobei connectCredentials der EOS_Connect_Credentials-Struktur entspricht, die einen Benutzertoken enthält. Füllen Sie diese wie folgt aus:

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

Fügen Sie dem Code folgende Daten hinzu:

• connectCredentials.Token, ein Benutzer-JWT. Das Spiel erhält diesen Token vom Launcher als Startargumente.
• connectCredentials.Type, der Authentifizierungstyp. Das vorliegende Beispiel bezieht sich auf die Authentifizierung bei einem externen OpenID-Anbieter.

Nachdem Sie Strukturen erstellt und mit Optionen vervollständigt haben, rufen Sie die Methode EOS_Connect_Login auf:

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

Die statische Funktion onLoginConnect wird nach Abschluss des Authentifizierungsprozesses aufgerufen. Deklarieren sie die Funktion wie folgt:

static void EOS_CALL onLoginConnect(const EOS_Connect_LoginCallbackInfo *Data);

wobei *Data einem Verweis zur EOS_Connect_LoginCallbackInfo-Struktur entspricht, die Daten über den Authentifizierungsversuch enthält.

Beschreibung der Struktur:

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

Beispielhafte Rückruffunktion:

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

Bei der Authentifizierung prüft das System, ob ein Epic-Konto existiert, das mit einem Konto eines externen Anbieters verknüpft ist.

Bei vorhandenem Epic-Konto:

• gibt der Parameter ResultCode im Objekt Data den Wert EOS_EResult::EOS_Success (0) zurück;
• gibt der Parameter LocalUserId im Objekt Data die Konto-ID zurück. Speichern Sie diese für die weitere Interaktion mit anderen Epic Services.

Wenn kein Epic-Konto verknüpft ist:

• gibt der Parameter ResultCode im Objekt Data den Wert OS_EResult::EOS_InvalidUser (3) zurück;
• gibt der Parameter Data->ContinuanceToken Daten über die Authentifizierungsversuche zurück. Speichern Sie diese, um einen neuen Epic-Benutzer zu erstellen, und verknüpfen Sie diesen mit dem Konto eines externen Anbieters.

Rufen Sie die Methode EOS_Connect_CreateUser auf, um einen neuen Epic-Benutzer anzulegen. Siehe folgendes Codebeispiel, wobei:

• connectHandle dem connectInterface-Objekt entspricht, das Sie bereits verwendet haben;
• options der EOS_Connect_CreateUserOptions-Struktur entspricht, die den im vorherigen Schritt erhaltenen continuanceToken enthält;
• NULL der clientData entspricht, die Sie im vorherigen Schritt zusammen mit der Methode EOS_Connect_Login erhalten haben;
• onCreateUser eine statische Rückruffunktion darstellt, die nach dem Anlegen eines Kontos gemeinsam mit der Funktion aus dem vorherigen Schritt aufgerufen wird.

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

Beispielhafte onCreateUser-Funktion:

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;

Wenn ein Epic-Benutzerkonto erfolgreich erstellt und mit einem Konto eines externen Anbieters verknüpft wurde:

• gibt der Parameter ResultCode im Objekt Data den Wert EOS_EResult::EOS_Success (0) zurück;
• gibt der Parameter LocalUserId im Objekt Data die Konto-ID zurück. Speichern Sie diese für die weitere Interaktion mit anderen Epic Services.