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:
- Erstellen Sie Attribute in Ihrem System.
- Weisen Sie in Ihrem System den Nutzern die Attribute zu.
- Implementieren Sie eine Logik, gemäß der Attributwerte aktualisiert werden, falls sich diese für einen Nutzer im Spiel ändern.
- Legen Sie Kataloganzeigeregeln unter Einbeziehung der erstellten Attribute fest.
- Übermitteln Sie die Attribute beim Abruf des Pay-Station-Zugriffstokens.
- 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:
- ein JSON-Schema für Benutzerattribute aufseiten von Xsolla erstellen und darin die Attribute festlegen (optional).
- ein JSON-Schema für Benutzerattribute erstellen und nur die in diesem JSON-Schema angegebenen Attribute übermitteln. Geben Sie dazu im JSON-Schema im Objekt
additionalProperties
den Wertfalse
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 Objekt
additionalProperties
den Werttrue
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.
properties
-Objekts anzugeben, damit die Attributschlüssel und ‑werte automatisch geprüft werden.- Weisen Sie Nutzern Attribute zu, und aktualisieren Sie die Werte mithilfe der Login API.
- Legen Sie Kataloganzeigeregeln unter Einbeziehung der erstellten Attribute fest.
- Implementieren Sie den Abruf eines Benutzer-JWT. Eine Liste der Methoden, mit denen sich ein JWT abrufen lässt, finden Sie in diesem Beispiel.
- 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:
- 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.
- Beispiel: Ein Nutzer erreicht ein neues Level, schließt eine Quest ab oder tätigt einen Kauf.
- 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.
- Für die Arbeit mit Benutzerattributen empfehlen wir die Methode Schreibgeschützte Attribute des Benutzers auf dem Server aktualisieren. Diese Methode ermöglicht es, Attribute zu erstellen, deren Werte vom Nutzer nicht geändert werden können.
- Wenn sich Nutzer im Webshop über ihre ID authentifizieren, können Sie während der Benutzerautorisierung die aktuellen Attributwerte in einem Webhook übermitteln.
- 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.
“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.
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.
- json
{
"$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.
Die Parameternamen in den API-Methoden können je nach Produkt variieren:
- project_id – ID des Kundenportal-Projekts bei Nutzung der IGS&BB API.
- publisher_project_id – ID des Kundenportal-Projekts bei Nutzung der Login API.
- projectId — ID des Login-Projekts im Kundenportal bei Nutzung der Login API.
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
- json
{
"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:
- Navigieren Sie im Kundenportal zu Online-Shop > Katalogverwaltung > Kataloganzeigeregeln.
- Klicken Sie auf Regel erstellen, und füllen Sie die Pflichtfelder aus:
- Attributschlüssel im Feld Benutzerattribut –
game
- Typ –
string
- Vergleichsoperator –
equal to
- Wert –
MyTestGame
- Attributschlüssel im Feld Benutzerattribut –
![](https://cdn.xsolla.net/developers/v-20240906-v01/images/guides/in-game-store/tutorials/rule_creation.png)
- 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.
![](https://cdn.xsolla.net/developers/v-20240906-v01/images/guides/in-game-store/tutorials/rule_item.png)
- Ü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 Attributgame
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:
- Ü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
Anfragerumpf (Beispiel):
- json
{
"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:
- 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
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.
game
mitsamt dem Wert OtherGame
an das - json
"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
- json
"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
War dieser Artikel hilfreich?
Diese Seite bewerten
Jetzt nicht
Vielen Dank für Ihr Feedback!
Haben Sie einen Tippfehler oder einen anderen Textfehler gefunden? Wählen Sie den Text aus und drücken Sie Strg+Eingabe.