Plattformübergreifendes Konto

So funktioniert's

Begriffserläuterung

Sie haben im Kundenportal Zugriff auf folgende Login-Projekttypen:

  1. Das Standard-Login-Projekt dient der Speicherung von Hauptkonten.
  2. Das Schatten-Login-Projekt dient der Speicherung von Plattformkonten.

Ein Hauptkonto ist ein in einem Standard-Login-Projekt erstellter Kontotyp und wird mit Plattformkonten verknüpft. Das Hauptkonto wird verwendet, um Spieler auf verschiedenen Plattformen zu identifizieren.

Ein Plattformkonto ist ein in einem Schatten-Login-Projekt erstellter Kontotyp und wird mit einer bestimmten Publishing-Plattform verknüpft. Das Plattformkonto lässt sich mit keinem weiteren Plattformkonto verknüpfen. Zudem können Sie die Verknüpfung zwischen den Konten und einem Hauptkonto nicht aufheben.

Eine Publishing-Plattform ist eine Plattform zur Distribution von Spielen (z. B. Steam, PlayStation, Xbox usw.).

Ein plattformübergreifendes Konto ist ein Konto mit Haupt- und Plattformkontoverknüpfung.

Für jedes Benutzerkonto mit Spielen auf einer bestimmten Plattform sollte ein entsprechendes Plattformkonto in einem Schatten-Login-Projekt existieren. Wenn ein Benutzer beispielsweise jeweils ein Spielkonto auf der Xbox- und der PlayStation-Plattform besitzt, sollten die Plattformkonten des Schatten-Login-Projekts mit den entsprechenden Xbox- bzw. PlayStation-Plattformkonto verknüpft sein.

Nutzung von plattformübergreifenden Konten

Das plattformübergreifende Konto ermöglicht Folgendes:

Bei miteinander verknüpften Haupt- und Plattformkonto:

  1. Benutzer authentifiziert sich auf einer Plattform.
  2. Der Xsolla-Login-Server sendet ein Hauptkontotoken an den Benutzer.
  3. Der Xsolla-Login-Server authentifiziert den Benutzer des Hauptkontos.

Bei Nutzung des plattformübergreifenden Kontos entspricht die Benutzer-ID in einem Token der ID des Hauptkontos. Die Benutzer-ID finden Sie unter JWT > sub-Anspruch.

Ablauf beim Verknüpfen von Konten

Wenn der Benutzer über ein Hauptkonto verfügt, kann er es bei der Authentifizierung auf einer Plattform mit einem Plattformkonto verknüpfen. Der Ablauf sieht wie folgt aus:

  1. Der Spieler startet das Spiel auf der Konsolenspieleplattform zum ersten Mal.
  2. Im Spiel wird eine Nachricht angezeigt. Darin wird angeboten, das Plattformkonto mit dem Hauptkonto zu verknüpfen.
  3. Der Benutzer startet die Anwendung und authentifiziert sich im Hauptkonto.
  4. Die Anwendung sendet die Anfrage Create Code for Linking Accounts an den Xsolla-Login-Server.
  5. In der Anwendung wird ein Code für das Verknüpfen der Konten angezeigt.
  6. Der Benutzer wechselt zur Konsolenversion des Spiels und gibt den Code ein.
  7. Der Spielserver sendet die Anfrage Link Accounts by Code an den Xsolla-Login-Server.
  8. Die Spielkonsole zeigt eine Bestätigungsnachricht an.

Für wen ist es

Partner, die Login bereits integriert haben und ein Konto bei einer Publishing-Plattform besitzen.

Wie komme ich dazu

Für die Integration eines plattformübergreifendes Konto benötigen Sie folgende Parameter aus dem Kundenportal:

  • main_project_id – ID eines Standard-Login-Projekts im UUID-Format. Zum Beispiel: f6c5011a-715e-4e5e-b7b1-a4812d85b8c8.
  • shadow_project_id – ID eines Schatten-Login-Projekts im UUID-Format. Diese Projekt wird als Schatten-Login-Projekt verwendet. Erstellen Sie ein Schatten-Login-Projekt, und geben Sie die zugehörige publisher_project_id in den Login-Projekteinstellungen an. Die shadow_project_id entspricht der ID des erstellten Projekts.
  • publisher_project_id – ID eines Projekts. Der Parameter wird unter Projekteinstellungen > Allgemeine Einstellungen > Projekt-ID angezeigt.

Senden Sie die Parameter shadow_project_id und publisher_project_id an Ihren Account Manager, um die folgenden OAuth 2.0-Client-Parameter abzurufen:

  • client_id – OAuth 2.0-Client-ID
  • client_secret – geheimer Schlüssel des OAuth 2.0-Client
Sie können die obigen Parameter nutzen, um einen Servertoken abzurufen.

Der Algorithmus für die Integration eines plattformübergreifenden Kontos sieht wie folgt aus:

  1. Benutzerauthentifizierung implementieren für:
    1. Hauptkonto
    2. Plattformkonto
  2. Konten verknüpfen:
    1. Code für das Verknüpfen abrufen
    2. Konten verknüpfen

Authentifizierung von Benutzern im Hauptkonto

Das Hauptkonto wird mit einer angegebenen main_project_id in einem Login-Projekt erstellt. Sie können sowohl das Login-Widget als auch die Login API zur Registrierung und Authentifizierung nutzen.

Authentifizierung von Benutzern im Plattformkonto

Wählen Sie zur Benutzerregistrierung und -authentifizierung über eine Plattform die Methode und folgen Sie den Anweisungen. Diese Methoden lassen sich kombinieren. Zum Beispiel können Sie die stille Authentifizierung für die Xbox-Plattform und die Authentifizierung über eine custom ID für eine andere Plattform verwenden.

Authentifizierung über custom ID

Nutzen Sie die Methode Auth by Custom ID auf dem Spielserver, um ein Plattformkonto zu erstellen. Übermitteln Sie die folgenden Daten an diese Methode:

  • den Parameter publisher_project_id oder shadow_project_id (andernfalls antwortet der Xsolla-Login-Server mit einem Fehler)
  • einen Servertoken
  • Benutzerdaten des Plattformkontos im Parameter social_profile

Bei Nutzung dieser Authentifizierungsmethode können Sie die Liste der Freunde des Benutzers von verschiedenen Plattformen nicht abrufen. Die Liste der für die Authentifizierung verfügbaren Plattformen ist nicht beschränkt.

Authentifizierungsablauf:

  1. Der Spiel-Client sendet die Authentifizierungsanfrage an einen Spielserver, wenn der Benutzer das Spiel startet.
  2. Der Spielserver generiert oder verwendet eine bereits vorhandene custom ID.
  3. Der Spielserver sendet die Anfrage Auth by Custom ID an den Xsolla-Login-Server unter Angabe der Plattform und der darauf befindlichen Benutzerkennung (Parameter: platform und user_id). Wenn sich der Benutzer mit einer übermittelten custom ID nicht finden lässt, wird ein neuer Benutzer angelegt.
  4. Der Xsolla-Login-Server sendet ein Token an den Spieleserver.

Anfragebeispiel:

POST https://login.xsolla.com/api/users/login/server_custom_id?publisher_project_id=<publisher_project_id> HTTP/1.1

Host:
login.xsolla.com

Headers:
X-Server-Authorization: <server_token>
Content-Type: application/json

Body:
{
  "server_custom_id": "secret_value",
  "social_profile": {
    "platform": "xbox",
    "user_id": "123"
  }
}

Antwortbeispiel:

{
  "token": "<platform_user_token>"
}

Stille Authentifizierung

Befolgen Sie zum Einrichten die Anleitung. Nutzen Sie die Methoden der stillen Authentifizierung auf dem Spielserver, um ein Plattformkonto zu erstellen.

Bei Nutzung der Methoden für die stille Authentifizierung können Sie die Liste der Freunde des Benutzers von verschiedenen Plattformen abrufen. Die Liste der für die stille Authentifizierung verfügbaren Plattformen finden Sie in der Anleitung.

Abrufen des Verknüpfungscodes

So rufen Sie einen Verknüpfungscode ab:

  1. Nutzen Sie die Methode Create Code for Linking Accounts. Übermitteln Sie den bei der Authentifizierung im Hauptkonto erhaltenen Benutzertoken an diese Methode.
  2. Zeigen Sie dem Benutzer den empfangene Code an.

Anfragebeispiel:

POST https://login.xsolla.com/api/users/account/code HTTP/1.1

Host:
login.xsolla.com

Headers:
Authorization: Bearer <main_user_token>

Antwortbeispiel:

{
  "code": "123456"
}

Verknüpfen von Konten

Nutzen Sie die Methode Link Accounts by Code, um ein Plattformkonto mit einem Hauptkonto zu verknüpfen. Übermitteln Sie den Parameter code samt dem vom Benutzer auf der Konsolenplattform eingegebenen Verknüpfungscode-Wert an diese Methode.

Anfragebeispiel:

POST https://login.xsolla.com/api/users/account/link HTTP/1.1

Host:
login.xsolla.com

Headers:
X-Server-Authorization: <server_token>
Content-Type: application/json

Body:
{
  "code": "123456",
  "platform": "xbox",
  "user_id": "123",
  "publisher_project_id": 44056
}

Antwortbeispiel:

HTTP/1.1 204 No Content