Artikelkatalog personalisieren

Die Themen des Tutorials im Überblick:

• Katalog mithilfe von selbst erstellten Attributen personalisieren (für Partner, die Nutzer mit dem Pay-Station-Zugriffstoken autorisieren)
• Attributprüfregeln im JSON-Schema festlegen und aufseiten von Xsolla dem Nutzer Attribute zuweisen (für Partner, die Nutzer mit Xsolla Login autorisieren)
• Kataloganzeigeregel erstellen
• Artikelkatalog für einen Nutzer mit unterschiedlichen Attributwerten abrufen

Voraussetzungen

Bevor Sie loslegen, müssen Sie:

• einen zu personalisierenden Katalog mit Ingame-Items oder Spielschlüsseln erstellt haben,
• den Abschnitt Benutzerattribute gelesen haben (für Partner, die Xsolla Login verwenden, um Nutzer zu autorisieren),
• in den Einstellungen Ihres Login-Projekts (unter Nutzerdatenbank > Nutzer) Nutzer hinzugefügt und ihnen Attribute zugewiesen haben (für Partner, die Nutzer per Xsolla Login autorisieren).

Personalisierung bei Benutzerautorisierung über Pay-Station-Zugriffstoken

Wenn Sie Nutzer anhand des Pay-Station-Zugriffstokens autorisieren, können Sie die Attribute beim Abruf des Tokens übermitteln. Gehen Sie in diesem Fall wie folgt vor:

1. Erstellen Sie Attribute in Ihrem System.
2. Weisen Sie in Ihrem System den Nutzern die Attribute zu.
3. Implementieren Sie eine Logik, gemäß der Attributwerte aktualisiert werden, falls sich diese für einen Nutzer im Spiel ändern.
4. Legen Sie Kataloganzeigeregeln unter Einbeziehung der erstellten Attribute fest.
5. Übermitteln Sie die Attribute beim Abruf des Pay-Station-Zugriffstokens.
6. Nutzen Sie den erhaltenen Token in den Methoden für die Anfrage des Artikelkatalogs.

Personalisierung bei Benutzerautorisierung über Xsolla Login

Wenn Sie Nutzer über Xsolla Login autorisieren, müssen Sie:

1. ein JSON-Schema für Benutzerattribute aufseiten von Xsolla erstellen und darin die Attribute festlegen (optional).

2. Weisen Sie Nutzern Attribute zu, und aktualisieren Sie die Werte mithilfe der Login API.
3. Legen Sie Kataloganzeigeregeln unter Einbeziehung der erstellten Attribute fest.
4. Implementieren Sie den Abruf eines Benutzer-JWT. Eine Liste der Methoden, mit denen sich ein JWT abrufen lässt, finden Sie in diesem Beispiel.
5. Verwenden Sie den erhaltenen Token in den Methoden für die Anfrage des Artikelkatalogs.

Es gibt mehrere Möglichkeiten, einem Nutzer Attribute zuzuweisen:

• per Attributaktualisierungsmethode:
  • Attribute des Benutzers auf dem Server aktualisieren
  • Schreibgeschützte Attribute des Benutzers auf dem Server aktualisieren

1. Verwenden Sie die obigen Methoden, um einem Nutzer Attribute zuzuweisen und Attributwerte zu aktualisieren. Um den Katalog zu personalisieren, ist es notwendig, die Attributwerte zu aktualisieren: Aktualisieren Sie Attributwerte in Xsolla, wenn sich diese für den Nutzer im Spiel ändern.

1. Beispiel: Ein Nutzer erreicht ein neues Level, schließt eine Quest ab oder tätigt einen Kauf.

1. Sie können die Werte sowohl eines einzelnen Attributs als auch mehrerer Attribute gleichzeitig aktualisieren. Eine Ausnahme bilden Attribute, die im JSON-Schema als "Zwingend erforderlich" gekennzeichnet sind – die für die Attributaktualisierung zuständigen API-Methoden können Sie nur dann aufrufen, wenn Sie die Werte der zwingend erforderlichen Attribute angeben.

• Wenn Sie die Methode Über selbst definierte ID authentifizieren nutzen, können Sie die Attributwerte direkt bei der Benutzerautorisierung übermitteln, indem Sie ein Array mit den aktuellen Werten der Benutzerattribute übergeben.

Beispielhafte Einrichtung der Personalisierung

In dem folgenden Beispiel wird gezeigt, wie Sie den Katalog personalisieren: Der Artikel “Medium Crystal Set” wird nur Nutzern angezeigt, die das Spiel “MyTestGame” gekauft haben.

Attributschema erstellen

• Attribut namens “game” vom Typ “string” – Name des vom Nutzer erworbenen Spiels. Das Attribut “game” ist als zwingend erforderlich gekennzeichnet. Sie können also Methoden für die Attributaktualisierung nur dann nutzen, wenn Sie das Attribut “game” übermitteln.

• Attribut namens “purchase_number” vom Typ “integer” – Anzahl der vom Nutzer erworbenen Exemplare.

{
	"$schema": "https://json-schema.org/draft/2020-12/schema",
	"title": "Example",
	"description": "JSON Schema description.",
	"properties": {
		"game": {
			"description": "Name of the game played by a user.",
			"type": "string"
		},
		"purchase_number": {
			"description": "The number of purchases the user made.",
			"type": "integer"
		}
	},
	"additionalProperties": false,
	"required": [
		"game"
	],
	"type": "object"
}

Einem Nutzer Attribute zuweisen

Nutzen Sie die Methode Schreibgeschützte Attribute des Benutzers auf dem Server aktualisieren, um Nutzern aus der Nutzerdatenbank Attribute zuzuweisen.

In der Methode Schreibgeschützte Attribute des Benutzers auf dem Server aktualisieren müssen Sie Folgendes angeben:

• Servertoken
• Benutzerattributwerte
• user_id – die im Kundenportal in den Einstellungen Ihres Login-Projekts (Nutzerdatenbank > Nutzer) angegebene Nutzerkennung.
• publisher_id – Händler-ID. Diese finden Sie:
  • unter Firmeneinstellungen > Firma
  • in der URL in der Adresszeile des Browsers auf einer beliebigen Seite im Kundenportal. Die URL weist das folgende Format auf: https:​//publisher.xsolla.com/<merchant ID>/<Publisher Account section>.
• publisher_project_id – Projekt-ID. Diese wird im Kundenportal neben dem Projektnamen angezeigt.

Vorab müssen Sie den Servertoken mithilfe der Methode JWT generieren abrufen.

Fahren Sie anschließend mit der Methode Schreibgeschützte Attribute des Benutzers auf dem Server aktualisieren fort.

Der Anfragerumpf mit dem attributes-Array sieht wie folgt aus:

{
  "attributes": [
    {
      "key": "game",
      "permission": "private",
      "value": "MyTestGame"
    },
 {   
     "key": "purchase_number",
      "permission": "private",
      "value": "30"
    }

  ],
  "publisher_id": 000000,
  "publisher_project_id": 000000
}

Die Anfrage weist einem attributlosen Nutzer Attribute mit den festgelegten Werten zu:

Kataloganzeigeregel erstellen

Legen Sie eine Regel fest, nach der das Item “Medium Crystal Set” nur Nutzern angezeigt wird, die MyTestGame gekauft haben.

So geht’s:

1. Navigieren Sie im Kundenportal zu Online-Shop > Katalogverwaltung > Kataloganzeigeregeln.
2. Klicken Sie auf Regel erstellen, und füllen Sie die Pflichtfelder aus:
   1. Attributschlüssel im Feld Benutzerattribut – game
   2. Typ – string
   3. Vergleichsoperator – equal to
   4. Wert – MyTestGame

3. Legen Sie fest, welcher Artikel angezeigt werden soll, wenn die Bedingung erfüllt ist. Im folgenden Beispiel wird der Artikel "Medium Crystal Set" Nutzern angezeigt, die MyTestGame besitzen.

4. Überprüfen und aktivieren Sie die Regel, und klicken Sie danach auf "Speichern und beenden".

Token abrufen

Xsolla-Login-JWT abrufen

• Über Benutzername und Passwort authentifizieren
• Über soziales Netzwerk authentifizieren
• Passwortlos über E-Mail authentifizieren
• Passwortlos über Telefonnummer authentifizieren
• Über Geräte-ID authentifizieren
• Über selbst definierte ID authentifizieren
• weitere Methoden für den Abruf des Benutzertokens über die Methodengruppe JWT oder OAuth 2.0

Pay-Station-Zugriffstoken abrufen

Rufen Sie den Pay-Station-Zugriffstoken mitsamt den erforderlichen Attributen ab. Dazu müssen Sie “game”: “MyTestGame” im attributes-Objekt in der Methode Token erstellen übermitteln.

Anfragerumpf (Beispiel):

{
  "settings": {
    "currency": "USD",
    "language": "en",
    "project_id": 000001,
    "ui": {
      "size": "medium"
    }
  },
  "user": {
    "email": {
      "value": "email@example.com"
    },
    "id": {
      "value": "user_2"
    },
    "name": {
      "value": "John Smith"
    },
    "attributes": {
      "game": "MyTestGame"
    }
  }
}

Artikelkatalog abrufen

Artikelkatalog mit Xsolla-Login-JWT abrufen

Rufen Sie den Katalog unter Angabe des Tokens des Nutzers ab, dem Sie das Attribut game mitsamt dem Wert MyTestGame zugewiesen haben. Dazu geben Sie in der Methode Liste virtueller Gegenstände abrufen Folgendes an:

• den erhaltenen Benutzer-JWT im Autorisierungs-Header
• die Projekt-ID aus dem Kundenportal als Pfadparameter

Die Antwort enthält drei Artikel:

• Empire Key
• Small Crystal Pack
• Medium Crystal Set, für das die Personalisierungsregel konfiguriert ist

"attributes": [
{
    "attr_type": "server",
    "key": "game",
    "permission": "private",
    "value": "OtherGame",
    "read_only": true
 },
{
    "attr_type": "server",
    "key": "purchase_number",
    "permission": "private",
    "value": "30",
    "read_only": true
  }
]

Unter Angabe des erhaltenen Tokens antwortet die Methode Liste virtueller Gegenstände abrufen mit zwei Artikeln: Empire Key und Small Crystal Pack. Das Medium Crystal Set, für das eine Personalisierungsregel festgelegt ist, fehlt in der Antwort.

Übermitteln Sie nun zum Vergleich das Attribut game mit dem Wert MyTestGame.

Bei Nutzern, denen das Spiel MyTestGame gehört, sieht das attributes-Array in der Methode Über selbst definierte ID authentifizieren wie folgt aus:

"attributes": [
{
    "attr_type": "server",
    "key": "game",
    "permission": "private",
    "value": "MyTestGame",
    "read_only": true
 },
{
    "attr_type": "server",
    "key": "purchase_number",
    "permission": "private",
    "value": "30",
    "read_only": true
  }
]

Geben Sie den erhaltenen Token an, wenn Sie den Artikelkatalog mit der Methode Liste virtueller Gegenstände abrufen anfragen.

Folglich ist das Medium Crystal Set in der Antwort enthalten:

Artikelkatalog mit Pay-Station-Zugriffstoken abrufen

Um den personalisierten Artikelkatalog abzurufen, müssen Sie Folgendes in der Methode Liste virtueller Gegenstände abrufen angeben:

• den erhaltenen Pay-Station-Zugriffstoken im Autorisierungs-Header
• die Projekt-ID aus dem Kundenportal als Pfadparameter

Die Antwort enthält drei Artikel:

• Empire Key
• Small Crystal Pack
• Medium Crystal Set, für das die Personalisierungsregel konfiguriert ist

Beim Abruf des Artikelkatalogs können Sie prüfen, ob dem Nutzer das Attribut game mitsamt dem Wert MyTestGame zugewiesen ist.

Löschen Sie nach Erhalt des Pay-Station-Zugriffstokens das attributes-Objekt, und fragen Sie den Artikelkatalog mithilfe der Methode Liste virtueller Gegenstände abrufen erneut an. Nun fehlt das Medium Crystal Set in der Antwort: