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
Hinweis
Wie man eine Werbeaktion personalisiert, wird in diesem Tutorial nicht behandelt. Werbeaktionen lassen sich auf dieselbe Weise personalisieren wie der Artikelkatalog, vorausgesetzt Nutzer werden per Xsolla Login autorisiert.

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

Hinweis
Sie können:
  • ein JSON-Schema für Benutzerattribute erstellen und nur die in diesem JSON-Schema angegebenen Attribute übermitteln. Geben Sie dazu im JSON-Schema im Feld additionalProperties den Wert false an. Die angegebenen Attribute werden automatisch geprüft.
  • ein JSON-Schema für Benutzerattribute erstellen und sowohl die im JSON-Schema angegebenen Attribute als auch zusätzliche, nicht im JSON-Schema erwähnte Attribute übermitteln. Geben Sie dazu im JSON-Schema im Feld additionalProperties den Wert true an. Die im JSON-Schema angegebenen Attribute werden automatisch geprüft.
  • darauf verzichten, ein JSON-Schema für Benutzerattribute zu erstellen. In diesem Fall können Sie beliebige Attribute übermitteln, die Attribute werden allerdings nicht geprüft.
Für die Artikelkatalogpersonalisierung empfehlen wir, die Attribute und deren Typen im JSON-Schema innerhalb des properties-Objekts anzugeben, damit die Attributschlüssel und ‑werte automatisch geprüft werden.

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

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

  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.
Hinweis
  • 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.
Hinweis
Wir empfehlen, schreibgeschützte Serverattribute zu erstellen. Übermitteln Sie dazu die Parameterwerte “attr_type”: “server” und “read_only”: “true”.

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.

Hinweis
Die Bezeichnungen “Medium Crystal Set” und “MyTestGame” sind frei gewählt. Sie können den Katalog selbstverständlich mithilfe der Artikel und Attribute in Ihrem Projekt personalisieren.
Ferner werden Optionen für die Attributerstellung aufseiten von Xsolla (Benutzerautorisierung über Xsolla Login) und aufseiten des Partners (Benutzerautorisierung über Pay-Station-Zugriffstoken betrachtet. Bei der Option Pay-Station-Zugriffstoken können Sie direkt dazu übergehen, die Kataloganzeigeregel zu erstellen.

Attributschema erstellen

Erstellen Sie ein JSON-Schema mitsamt Attributen, die den Spielnamen und die Anzahl der gekauften Exemplare widerspiegeln. Geben Sie dazu in dem Schema Folgendes an:
  • 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 (Beispiel):
Copy
Full screen
Small screen

{
	"$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.
Hinweis

Die Parameternamen in den API-Methoden können je nach Produkt variieren:

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:

Copy
Full screen
Small screen
{
  "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
  1. 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.
  1. Überprüfen und aktivieren Sie die Regel, und klicken Sie danach auf "Speichern und beenden".

Token abrufen

Xsolla-Login-JWT abrufen

Rufen Sie ein Token für den Nutzer ab, dem Sie das Attribut game mitsamt dem Wert MyTestGame zugewiesen haben.
Sie können den Xsolla-Login-JWT nach erfolgreicher Benutzerautorisierung client- oder serverseitig ohne Zutun des Nutzers abrufen. Verwenden Sie dazu eine der folgenden Xsolla-Login-Autorisierungsmethoden:

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

Copy
Full screen
Small screen

{
  "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

Der Abruf des Artikelkatalogs erfolgt mit der Methode Liste virtueller Gegenstände abrufen. Für die Autorisierung müssen Sie entweder den Xsolla-Login-Benutzer-JWT oder den Pay-Station-Zugriffstoken angeben.

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:

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 der in der Antwort angegebene Attributwert mit dem in der Regel angegebenen übereinstimmt. Zum Testen können Sie die Attribute direkt übermitteln, indem Sie den Token mit der Methode Über selbst definierte ID authentifizieren abrufen.
Hinweis
Diese Methode funktioniert nur bei Nutzern, die mit der Methode Über selbst definierte ID authentifizieren autorisiert wurden.
Rufen Sie den Benutzer-JWT mithilfe der Methode Über selbst definierte ID authentifizieren ab, und übermitteln Sie das Attribut game mitsamt dem Wert OtherGame an das attributes-Array:
Copy
Full screen
Small screen
"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:

Copy
Full screen
Small screen

"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:

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:

War dieser Artikel hilfreich?
Vielen Dank!
Gibt es etwas, das wir verbessern können? Nachricht
Das tut uns leid
Bitte erläutern Sie, weshalb dieser Artikel nicht hilfreich ist. Nachricht
Vielen Dank für Ihr Feedback!
Wir werden Ihr Feedback aufgreifen und dazu nutzen, Ihr Erlebnis verbessern.
Diese Seite bewerten
Diese Seite bewerten
Gibt es etwas, das wir verbessern können?

Jetzt nicht

Vielen Dank für Ihr Feedback!
Letztmalig aktualisiert: 17. April 2024

Haben Sie einen Tippfehler oder einen anderen Textfehler gefunden? Wählen Sie den Text aus und drücken Sie Strg+Eingabe.

Problem melden
Wir überprüfen unsere Inhalte ständig. Ihr Feedback hilft uns, sie zu verbessern.
Geben Sie eine E-Mail-Adresse an, damit wir Sie erreichen können
Vielen Dank für Ihr Feedback!