Begrenzung der Elementanzahl auf der Seite.
- Belohnungskette erstellen
Liste der Wertpunkte abrufen
Wertpunkt erstellen
Wertpunkt abrufen
Wertpunkt aktualisieren
Wertpunkte löschen
Liste der Artikel mit Wertpunkten abrufen
Wertpunkte für Artikel festlegen
Wertpunkte für Artikel teilweise aktualisieren
Wertpunkte von Artikeln löschen
Liste der Belohnungsketten abrufen
Belohnungskette abrufen
Belohnungskette aktualisieren
Belohnungskette löschen
Belohnungskette aktivieren/deaktivieren
Belohnungskette zurücksetzen
Belohnungskette erstellen
LiveOps-API (2.0.0)
- Version: 2.0.0
- Server:
https://store.xsolla.com/api - Kontaktieren Sie uns per E-Mail
- Kontakt-URL: https://xsolla.com/
- Erforderliche TLS-Version: 1.2
LiveOps ist ein Toolkit, mit dem sich die Spielerbindung durch Werbeaktionen und personalisierte Angebote steigern lässt.
Mit der API lassen sich die folgenden Funktionen steuern:
- Werbeaktionen – Erstellen und Verwalten von Gutscheinen, Promocodes, Rabatten und Bonuskampagnen.
- Personalisierung – Festlegen von Bedingungen für die Anzeige des Artikelkatalogs und die Inanspruchnahme von Werbeaktionen für bestimmte autorisierte Nutzer.
- Werbeaktionslimits – Festlegen, wie oft eine Werbeaktion von einem Nutzer in Anspruch genommen werden darf und wann diese Limits zurückgesetzt werden.
- Belohnungsketten und Wertpunkte — Konfigurieren von Belohnungsketten, wobei das Durchlaufen dieser Ketten an das Sammeln von Wertpunkten gekoppelt ist.
- Tägliche Ketten – Einrichten von wiederkehrenden täglichen Belohnungen, um Nutzer zu motivieren, sich regelmäßig anzumelden.
- Angebotsketten – Erstellen von aufeinanderfolgenden Kaufangeboten mit gestaffelten Preisen und kostenlosen Belohnungen.
- Upselling – Verkaufsmethode, bei der dem Nutzer ein Artikel mit zusätzlichem Mehrwert zum Kauf angeboten wird.
Die API ist in die folgenden Gruppen unterteilt:
Admin – Aufrufe zum Erstellen, Aktualisieren, Aktivieren und Löschen von Kampagnen und Kettenkonfigurationen. Die Authentifizierung erfolgt über Basisauthentifizierung mit Ihren Händler- oder Projektanmeldedaten.Client – Aufrufe zum Abrufen verfügbarer Werbeaktionen, zum Abrufen aktiver Ketten, zum Einlösen von Codes und zum Beanspruchen von Belohnungen im Namen authentifizierter Endnutzer. Die Authentifizierung erfolgt über den Benutzer-JWT.
API-Aufrufe erfordern eine Authentifizierung entweder im Namen eines Nutzers oder im Namen eines Projekts. Das verwendete Authentifizierungsschema ist im Abschnitt Sicherheit – in der Beschreibung des jeweiligen Aufrufs – angegeben.
Die Authentifizierung mit Benutzer-JWT kommt zum Einsatz, wenn eine Anfrage von einem Browser, einer App oder einem Spiel gesendet wird. Standardmäßig wird das Schema XsollaLoginUserJWT angewendet. Weitere Informationen zum Erstellen eines Tokens finden Sie in der Dokumentation zur Xsolla-Login-API.
Der Token wird im Authorization-Header im folgenden Format übermittelt: Authorization: Bearer <user_JWT>, wobei <user_JWT> der Benutzertoken ist. Der Token dient dazu, den Nutzer zu identifizieren und ihm Zugriff auf personalisierte Daten zu ermöglichen.
Alternativ können Sie einen Token zum Öffnen des Zahlungsportals verwenden.
Die HTTP-Basisauthentifizierung wird für Server-zu-Server-Interaktionen verwendet, wenn ein API-Aufruf direkt von Ihrem Server und nicht von einem Browser oder einer App gesendet wird. Typischerweise wird die HTTP-Basisauthentifizierung gemeinsam mit einem API-Schlüssel verwendet.
Hinweis
Der API-Schlüssel ist vertraulich und darf nicht in Client-Anwendungen gespeichert oder verwendet werden.
Der API-Schlüssel ist vertraulich und darf nicht in Client-Anwendungen gespeichert oder verwendet werden.
Bei der serverseitigen Basisauthentifizierung müssen alle API-Anfragen den folgenden Header enthalten:
- für
basicAuth–Authorization: Basic <your_authorization_basic_key>, wobeiyour_authorization_basic_keydas gemäß Base64-Verfahren kodierteproject_id:api_key-Paar ist - für
basicMerchantAuth–Authorization: Basic <your_authorization_basic_key>, wobeiyour_authorization_basic_keydas gemäß Base64-Verfahren kodiertemerchant_id:api_keyPaar ist
Die Parameterwerte finden Sie im Kundenportal an folgenden Orten:
merchant_idwird angezeigt:- unter Firmeneinstellungen > Firma.
- in der URL in der Adressleiste des Browsers auf einer beliebigen Seite im Kundenportal. Die URL hat das folgende Format:
https://publisher.xsolla.com/<merchant_id>.
project_idwird angezeigt:- neben dem Projektnamen im Kundenportal.
- in der URL in der Adressleiste des Browsers, wenn Sie im Kundenportal ein Projekt geöffnet haben. Die URL hat das folgende Format:
https://publisher.xsolla.com/<merchant_id>/projects/<project_id>.
api_keywird im Kundenportal nur einmal angezeigt, nämlich dann, wenn er erstellt wird. Sie sind selbst dafür verantwortlich, den Schlüssel in Ihrem System zu speichern. Einen API-Schlüssel können Sie an den folgenden Orten erstellen:
Hinweis
Falls bei einem erforderlichen API-Aufruf der Pfadparameter
Falls bei einem erforderlichen API-Aufruf der Pfadparameter
project_id fehlt, müssen Sie einen API-Schlüssel verwenden, der für alle Projekte der Firma gültig ist.Weitere Informationen zur Arbeit mit API-Schlüsseln finden Sie in den API-Referenzen.
Das Authentifizierungsschema AuthForCart wird für Warenkorbkäufe verwendet und unterstützt zwei Modi:
Authentifizierung mit einem Benutzer-JWT. Der Token wird im
Authorization-Header im folgenden Format übermittelt:Authorization: Bearer <user_JWT>, wobei<user_JWT>der Benutzertoken ist. Der Token dient dazu, den Nutzer zu identifizieren und ihm Zugriff auf personalisierte Daten zu ermöglichen. Alternativ können Sie einen Token zum Öffnen des Zahlungsportals verwenden.Vereinfachter Modus ohne Autorisierungs-Header. Dieser Modus ist nur für nicht autorisierte Nutzer vorgesehen und kann lediglich für den Verkauf von Spielschlüsseln genutzt werden. Anstelle eines Tokens muss die Anfrage die folgenden Header enthalten:
x-unauthorized-idsamt Anfrage-IDx-usersamt der E-Mail-Adresse des Nutzers, kodiert in Base64
Alle Artikeltypen (virtuelle Gegenstände, Bundles, virtuelle Währung und Schlüssel) haben eine ähnliche Datenstruktur. Kenntnisse über die Grundstruktur vereinfachen die Arbeit mit der API und erleichtern das Navigieren in der Dokumentation.
Hinweis
Einige Aufrufe können zusätzliche Felder enthalten, doch diese ändern nichts an der Grundstruktur.
Einige Aufrufe können zusätzliche Felder enthalten, doch diese ändern nichts an der Grundstruktur.
Identifikation
merchant_id– Firmen-ID im Kundenportalproject_id– Projekt-ID im Kundenportalsku– Artikel-SKU, einzigartig innerhalb des Projekts
Shop-Anzeige
name– Artikelnamedescription– Artikelbeschreibungimage_url– Bild-URLis_enabled– Artikelverfügbarkeitis_show_in_store– ob der Artikel im Katalog angezeigt wird
Weitere Informationen zur Verwaltung der Artikelverfügbarkeit im Katalog finden Sie in der Dokumentation.
Organisation
type– Artikeltyp, zum Beispiel ein virtueller Gegenstand (virtual_item) oder Bundle (bundle)groups– Gruppen, zu denen der Artikel gehörtorder– Anzeigereihenfolge im Katalog
Verkaufsbedingungen
prices– Preise in echter oder virtueller Währunglimits– Kauflimitsperiods– Verfügbarkeitszeiträumeregions– regionale Beschränkungen
Grundstruktur einer Entität (Beispiel):
{
"attributes": [],
"bundle_type": "virtual_currency_package",
"content": [
{
"description": {
"en": "Main in-game currency"
},
"image_url": "https://.../image.png",
"name": {
"en": "Crystals",
"de": "Kristalle"
},
"quantity": 500,
"sku": "com.xsolla.crystal_2",
"type": "virtual_currency"
}
],
"description": {
"en": "Crystals x500"
},
"groups": [],
"image_url": "https://.../image.png",
"is_enabled": true,
"is_free": false,
"is_show_in_store": true,
"limits": {
"per_item": null,
"per_user": null,
"recurrent_schedule": null
},
"long_description": null,
"media_list": [],
"name": {
"en": "Medium crystal pack"
},
"order": 1,
"periods": [
{
"date_from": null,
"date_until": "2020-08-11T20:00:00+03:00"
}
],
"prices": [
{
"amount": 20,
"country_iso": "US",
"currency": "USD",
"is_default": true,
"is_enabled": true
}
],
"regions": [],
"sku": "com.xsolla.crystal_pack_2",
"type": "bundle",
"vc_prices": []
}Über die Xsolla-API lässt sich die Logik für einen Ingame-Shop implementieren, darunter das Abrufen des Artikelkatalogs, die Verwaltung des Warenkorbs, das Anlegen von Bestellungen und die Verfolgung des Bestellstatus. Je nach Integrationsszenario sind die API-Aufrufe in die Unterbereiche Verwaltung und Katalog unterteilt, die unterschiedliche Authentifizierungsschemen verwenden.
Das folgende Beispiel zeigt den grundlegenden Ablauf für die Einrichtung und den Betrieb eines Shops, von der Artikelerstellung bis zum Kauf.
Erstellen Sie für Ihren Shop einen Katalog mit Artikeln wie etwa virtuellen Gegenständen, Bundles oder virtueller Währung.
API-Aufrufe (Beispiele):
Konfigurieren Sie Tools für die Nutzergewinnung und Monetarisierung, wie etwa Rabatte, Boni, tägliche Belohnungen oder Angebotsketten.
API-Aufrufe (Beispiele):
Konfigurieren Sie, wie Artikel in Ihrer Anwendung angezeigt werden sollen.
Hinweis
Verwenden Sie keine API-Aufrufe aus dem Unterabschnitt "Verwaltung", um einen Nutzerkatalog zu erstellen. Diese API-Aufrufe unterliegen Ratenbegrenzungen und sind nicht für Nutzer-Traffic vorgesehen.
Verwenden Sie keine API-Aufrufe aus dem Unterabschnitt "Verwaltung", um einen Nutzerkatalog zu erstellen. Diese API-Aufrufe unterliegen Ratenbegrenzungen und sind nicht für Nutzer-Traffic vorgesehen.
API-Aufrufe (Beispiele):
Hinweis
Standardmäßig geben katalogbezogene API-Aufrufe Artikel zurück, die zum Zeitpunkt der Anfrage im Shop verfügbar sind. Um Artikel abzurufen, die noch nicht verfügbar oder nicht mehr verfügbar sind, müssen Sie den Parameter
Standardmäßig geben katalogbezogene API-Aufrufe Artikel zurück, die zum Zeitpunkt der Anfrage im Shop verfügbar sind. Um Artikel abzurufen, die noch nicht verfügbar oder nicht mehr verfügbar sind, müssen Sie den Parameter
"show_inactive_time_limited_items": 1 in der Kataloganfrage ergänzen.
Artikel können Sie mit den folgenden Methoden verkaufen:
- Schnellkauf – Verkauf einer einzelnen SKU in beliebiger Menge.
- Warenkorbkauf – der Nutzer kann im Rahmen einer Bestellung Artikel in den Warenkorb legen, Artikel aus dem Warenkorb entfernen und die Menge jedes einzelnen Artikels ändern.
Wird ein Artikel mit virtueller Währung anstelle von echtem Geld gekauft, müssen Sie den API-Aufruf Bestellung mit einem angegebenen, in virtueller Währung gekauften Artikel anlegen verwenden. Das Zahlungsportal muss nicht aufgerufen werden, da die Zahlungsabwicklung bei Ausführung des API-Aufrufs erfolgt.
Beim Kauf eines kostenlosen Artikels müssen Sie den API-Aufruf Bestellung mit angegebenem kostenlosen Artikel anlegen oder den API-Aufruf Bestellung mit einem kostenlosen Warenkorb anlegen verwenden. as Zahlungsportal muss nicht aufgerufen werden – der Bestellung wird sofort der Status done zugewiesen.
Verwenden Sie den clientseitigen API-Aufruf, um eine Bestellung mit einem angegebenen Artikel anzulegen. Der Aufruf gibt einen Token zurück, mit dem sich das Zahlungsportal öffnen lässt.
Hinweis
Rabattinformationen sind für den Nutzer nur im Zahlungsportal verfügbar. Promocodes werden nicht unterstützt.
Rabattinformationen sind für den Nutzer nur im Zahlungsportal verfügbar. Promocodes werden nicht unterstützt.
Die Einrichtung des Warenkorbs und der Kaufvorgang können sowohl client- als auch serverseitg erfolgen.
Warenkorb clientseitig einrichten und Artikel kaufen
Implementieren Sie die Logik für das Hinzufügen und Entfernen von Artikeln selbst. Bevor Sie die API zum Einrichten eines Warenkorbs aufrufen, liegen Ihnen keine Informationen darüber vor, welche Werbeaktionen auf den Kauf angewendet werden. Die Gesamtkosten und die Details der hinzugefügten Bonusartikel sind Ihnen also unbekannt.
Implementieren Sie die folgende Warenkorblogik:
- Verwenden Sie den API-Aufruf Artikel in den Warenkorb legen, nachdem der Spieler einen Warenkorb zusammengestellt hat. Der Aufruf gibt die aktuellen Informationen zu den ausgewählten Artikeln zurück (Preise mit und ohne Rabatt, Bonusartikel).
- Aktualisieren Sie den Warenkorbinhalt basierend auf den Aktionen des Nutzers:
- Verwenden Sie den API-Aufruf Warenkorbartikel anhand von Warenkorb-ID aktualisieren, um einen Artikel in den Warenkorb zu legen oder die Artikelmenge zu ändern.
- Verwenden Sie den API-Aufruf Warenkorbartikel anhand von Warenkorb-ID löschen, um einen Artikel zu entfernen.
Hinweis
Mit dem API-Aufruf "Warenkorb des aktuellen Benutzers abrufen" können Sie den aktuellen Status des Warenkorbs abrufen.
Mit dem API-Aufruf "Warenkorb des aktuellen Benutzers abrufen" können Sie den aktuellen Status des Warenkorbs abrufen.
- Verwenden Sie den API-Aufruf Bestellung mit allen Artikeln aus dem aktuellen Warenkorb anlegen. Der Aufruf gibt die Bestell-ID und den Zahlungstoken zurück. Der neu angelegten Bestellung wird standardmäßig der Status
newzugewiesen.
Warenkorb serverseitig einrichten und Artikel kaufen
Diese Einrichtungsoption kann länger dauern, da jede Änderung am Warenkorb durch API-Aufrufe vorgenommen werden muss.
Implementieren Sie die folgende Warenkorblogik:
- Verwenden Sie den API-Aufruf Artikel in den Warenkorb legen, nachdem der Spieler einen Warenkorb zusammengestellt hat. Der Aufruf gibt die aktuellen Informationen zu den ausgewählten Artikeln zurück (Preise mit und ohne Rabatt, Bonusartikel).
- Verwenden Sie den API-Aufruf Bestellung mit allen Artikeln aus dem aktuellen Warenkorb anlegen. Der Aufruf gibt die Bestell-ID und den Zahlungstoken zurück. Der neu angelegten Bestellung wird standardmäßig der Status
newzugewiesen.
Verwenden Sie den zurückgegebenen Token, um das Zahlungsportal in einem neuen Fenster zu öffnen. Weitere Möglichkeiten, das Zahlungsportal zu öffnen, sind in der Dokumentation beschrieben.
| Aktion | Endpunkt |
|---|---|
| In der Produktionsumgebung öffnen. | https://secure.xsolla.com/paystation4/?token={token} |
| In der Testumgebung öffnen. | https://sandbox-secure.xsolla.com/paystation4/?token={token} |
Hinweis
Nutzen Sie die Testumgebung während der Entwicklung und zum Testen. Es stehenn Test-Bankkarten bereit. Bei Testkäufen wird kein Geld von echten Konten abgebucht.
Nutzen Sie die Testumgebung während der Entwicklung und zum Testen. Es stehenn Test-Bankkarten bereit. Bei Testkäufen wird kein Geld von echten Konten abgebucht.
Sobald die erste tatsächliche Zahlung erfolgt ist, tritt eine strenge Zahlungsrichtlinie für die Testumgebung in Kraft: Ab dann dürfen nur noch die unter Kundenportal > Firmeneinstellungen > Nutzer angegebenen Nutzer ein Zahlung in der Testumgebung tätigen .
Der Kauf von virtueller Währung und Gegenständen gegen echtes Geld ist erst nach Unterzeichnung einer Lizenzvereinbarung möglich. Navigieren Sie dazu im Kundenportal zu Vereinbarungen und Steuern > Vereinbarungen, füllen Sie das Formular aus, und warten Sie auf die Bestätigung. Die Prüfung kann bis zu drei Werktage dauern.
Die Testumgebung können Sie aktivieren oder deaktivieren. Ändern Sie dazu einfach den Wert des Parameters sandbox in der Schnellkauf- bzw. Warenkorbkauf-Anfrage. Die Testumgebung ist standardmäßig deaktiviert.
Mögliche Bestellstatus:
new– Bestellung angelegtpaid– Zahlung erhaltendone– Artikel geliefertcanceled– Bestellung storniertexpired– Bestellung abgelaufen
Tracken Sie den Bestellstatus mit einer der folgenden Methoden:
API-Aufrufe, die umfangreiche Datensätze zurückgeben (beispielsweise beim Erstellen eines Katalogs), liefern Daten seitenweise. Die Paginierung ist ein Mechanismus, der die Anzahl der in einer einzelnen API-Antwort zurückgegebenen Elemente begrenzt und es ermöglicht, aufeinanderfolgende Seiten der Reihe nach abzurufen.
Mithilfe der folgenden Parameter können Sie die Anzahl der zurückgegebenen Elemente steuern:
limit– Anzahl der Elemente pro Seiteoffset– Index des ersten Elements auf der Seite (Nummerierung beginnt bei 0)has_more– gibt an, ob eine weitere Seite verfügbar isttotal_items_count– Gesamtanzahl der Elemente
Beispielanfrage:
GET /items?limit=20&offset=40Beispielantwort:
{
"items": [...],
"has_more": true,
"total_items_count": 135
}Es wird empfohlen, nachfolgende Anfragen zu senden, bis die Antwort has_more = false zurückgibt.
Datums- und Zeitwerte werden im ISO 8601-Format übermittelt.
Folgende Formate werden unterstützt:
- UTC-Offset
null-Wert, wenn keine zeitliche Einschränkung für die Anzeige eines Artikels besteht- Unix-Zeitstempel (in Sekunden), der in einigen Feldern verwendet wird
Format: YYYY-MM-DDTHH:MM:SS±HH:MM
Beispiel: 2026-03-16T10:00:00+03:00
Xsolla unterstützt die Lokalisierung von benutzerseitigen Feldern wie Artikelname und Beschreibung. Lokalisierte Werte werden als Objekt übermittelt, wobei der Sprachcode als Schlüssel verwendet wird. Die vollständige Liste der unterstützten Sprachen ist in der Dokumentation verfügbar.
Unterstützte Felder
Für die folgenden Parameter kann eine Lokalisierung festgelegt werden:
namedescriptionlong_description
Gebietsschemaformat
Der Gebietsschemaschlüssel kann in einem der folgenden Formate angegeben werden:
- Sprachencode bestehend aus zwei Buchstaben:
en,ru - Sprachencode bestehend aus fünf Buchstaben:
en-US,ru-RU,de-DE
Beispiele
Zweistelliger Sprachencode (Beispiel):
{
"name": {
"en": "Starter Pack",
"ru": "Стартовый набор"
}
}Fünfstelliger Sprachencode (Beispiel):
{
"description": {
"en-US": "Premium bundle",
"de-DE": "Premium-Paket"
}
}Wenn ein Fehler auftritt, gibt die API einen HTTP-Statuscode und einen JSON-Antwortrumpf zurück. Die vollständige Liste der shopbezogenen Fehler ist in der Dokumentation verfügbar.
Antwort (Beispiel):
{
"errorCode": 1102,
"errorMessage": "Validation error",
"statusCode": 422,
"transactionId": "c9e1a..."
}errorCode– Fehlercode.errorMessage– kurze Fehlerbeschreibung.statusCode– HTTP-Antwortstatus.transactionId– Anfrage-ID. Wird nur in einigen Fällen zurückgegeben.errorMessageExtended– zusätzliche Fehlerdetails, wie z. B. Anfrageparameter. Wird nur in einigen Fällen zurückgegeben.
Erweiterte Antwort (Beispiel):
{
"errorCode": 7001,
"errorMessage": "Chain not found",
"errorMessageExtended": {
"chain_id": "test_chain_id",
"project_id": "test_project_id",
"step_number": 2
},
"statusCode": 404
}Gängige HTTP-Statuscodes
400– ungültige Anfrage401– Authentifizierungsfehler403– mangelnde Berechtigungen404– Ressource nicht gefunden422– Validierungsfehler429– Ratenlimit überschritten
Empfehlungen
- Verarbeiten Sie den HTTP-Statuscode und den Antwortrumpf gemeinsam.
- Verwenden Sie
errorCode, um Fehler im Zusammenhang mit der Anwendungslogik zu verarbeiten. - Verwenden Sie
transactionId, um Anfragen bei der Fehleranalyse schneller zu identifizieren.
OpenAPI-Beschreibung herunterladen
Sprachen
Server
https://store.xsolla.com/api/
Mock server
https://xsolla.redocly.app/_mock/de/api/liveops/
Übersicht
Werbeaktionen sind Marketinginstrumente, die darauf abzielen, neue Nutzer zu gewinnen und den Umsatz zu steigern. Mithilfe der Xsolla-API können Sie folgende Werbeaktionen einrichten:
- Rabatte – reduzierte Preise auf ausgewählte Artikel.
- Boni – Artikel, die Nutzer bei einem Kauf als Dreingabe erhalten.
- Gutscheine – Codes, mit denen Nutzer einen oder mehrere Bonusartikel beim Einlösen erhalten.
- Promocodes – Codes, mit denen Nutzer Bonusartikel, einen Rabatt auf einen bestimmten Artikel oder einen Rabatt auf den gesamten Warenkorb erhalten können. Im Gegensatz zu Gutscheinen, die erst nach Eingabe durch den Nutzer eingelöst werden, werden Promocodes während des Kaufvorgangs (an der Kasse) eingelöst.
- Sonderangebote – versteckte Artikel, die den Nutzern erst nach Eingabe eines exklusiven Angebotscode im Katalog angezeigt werden. Wird der Code nicht eingegeben, bleiben die Artikel ausgeblendet.
Konfiguration einer Rabattaktion (Beispielhafter Ablauf):
- Erstellen Sie Artikel mit den Aufrufen aus dem Unterabschnitt Verwaltung der Gruppen Virtuelle Gegenstände und Währung, Bundles oder Spielschlüssel.
- Erstellen Sie eine Werbeaktion mit dem Aufruf Rabattaktion für Artikel erstellen. Übermitteln Sie im
items-Array die erforderlichen Artikel-SKUs. - Legen Sie die Gültigkeitszeiträume der Werbeaktion fest. Rufen Sie dazu die Methoden Rabattaktion für Artikel erstellen oder Artikelaktion aktualisieren auf, und übermitteln Sie das
promotion_periods-Feld als Objekt-Array, wobeidate_fromdas Startdatum unddate_untildas Enddatum des Gültigkeitszeitraums definiert. - Aktivieren Sie eine Werbeaktion mit dem Aufruf Artikelaktion aktualisieren. Übermitteln Sie den Parameter
"is_enabled": true. - Um Informationen über Artikelpreise (einschließlich ermäßigter Preise) zu erhalten, müssen Sie die clientseitigen API-Methoden für den Abruf eines Artikelkatalogs aus den Unterabschnitten Allgemeines > Katalog, Virtuelle Gegenstände und Währung > Katalog und Bundles > Katalog aufrufen.
Weitere Informationen zur Konfiguration von Werbeaktionen finden Sie in unserer Dokumentation:
Gutscheine
Mit den API-Methoden aus diesem Unterabschnitt können Sie Gutscheinaktionen konfigurieren und verwalten.
Hinweis
Weitere Informationen zu Gutscheinen finden Sie in unserer Dokumentation.
Operationen
Promocodes
Mit den API-Methoden aus diesem Unterabschnitt können Sie Promocode-Aktionen konfigurieren und verwalten.
Hinweis
Weitere Informationen zu Promocodes finden Sie in unserer Dokumentation.
Operationen
Katalogsonderangebote
Mit den API-Methoden aus diesem Unterabschnitt können Sie Katalogsonderangebote konfigurieren und verwalten.
Hinweis
Weitere Informationen zu Sonderangeboten finden Sie in unserer Dokumentation.
Operationen
Rabatte
Mit den API-Methoden aus diesem Unterabschnitt können Sie Rabattaktionen konfigurieren und verwalten.
Hinweis
Weitere Informationen zu Rabatten finden Sie in unserer Dokumentation.
Operationen
Boni
Mit den API-Methoden aus diesem Unterabschnitt können Sie Bonusaktionen konfigurieren und verwalten.
Hinweis
Weitere Informationen zu Boni finden Sie in unserer Dokumentation.
Operationen
Personalisierter Katalog
Mithilfe der Personalisierung können Sie die Bedingungen festlegen, unter denen der Artikelkatalog und Werbeaktionen bestimmten autorisierten Nutzern angezeigt werden. Die Bedingungen werden auf der Grundlage von Nutzerattributen definiert und ermöglichen es Ihnen, Artikeln und Werbeaktionen anzubieten, die für bestimmte Nutzer am relevantesten sind.
Die folgenden Personalisierungstypen sind verfügbar:
- Personalisierung aufseiten von Xsolla. Personalisierungsregeln und ‑logik werden aufseiten von Xsolla konfiguriert und gespeichert. Sie übermitteln die Nutzerattribute, und basierend darauf erstellt Xsolla einen personalisierten Katalog.
- Personalisierung aufseiten des Partners. Sie konfigurieren die Personalisierungsregeln und ‑logik in Ihrem System und senden eine endgültige Katalog-Payload für einen bestimmten Nutzer an Xsolla.
Hinweis
Sie können nur einen Personalisierungstyp verwenden. Wie Sie den Personalisierungstyp ändern, erfahren Sie in der Anleitung.
Sie können nur einen Personalisierungstyp verwenden. Wie Sie den Personalisierungstyp ändern, erfahren Sie in der Anleitung.
So konfigurieren Sie die Personalisierung aufseiten von Xsolla mithilfe der Xsolla-API:
Erstellen Sie Artikel mit den API-Aufrufen aus dem Unterabschnitt Verwaltung der Gruppen Virtuelle Gegenstände und Währung, Bundles oder Spielschlüssel.
Richten Sie Nutzerattribute mit der Xsolla-Login-API ein, und halten Sie diese synchron, indem Sie die Daten in Xsolla aktualisieren, sobald sich in Ihrem Spiel Änderungen ergeben.
Konfigurieren Sie die Personalisierung für Artikel oder Werbeaktionen:
- Um den Artikelkatalog zu personalisieren, müssen Sie Kataloganzeigeregeln mit dem API-Aufruf Katalogfilterregel erstellen definieren:
- Legen Sie im Array attribute_conditions die Bedingungen (auf Basis von Nutzerattributen) fest, unter denen die Artikel verfügbar sind.
- Geben Sie im Array items die Liste der Artikel an, die dem Nutzer angezeigt werden sollen, wenn dessen Attribute den festgelegten Bedingungen entsprechen
- Verwenden Sie die API-Aufrufe zum Erstellen und Aktualisieren des gewünschten Werbeaktionstyp, um personalisierte Werbeaktionen zu konfigurieren. Legen Sie im Array attribute_conditions die Bedingungen (auf Basis von Nutzerattributen) fest, unter denen die Werbeaktion verfügbar ist.
- Um den Artikelkatalog zu personalisieren, müssen Sie Kataloganzeigeregeln mit dem API-Aufruf Katalogfilterregel erstellen definieren:
Übermitteln Sie den Benutzer-JWT mitsamt der Nutzerattribute an die API-Aufrufe zur Katalogabfrage, um einen personalisierten Katalog abzurufen.
Konfiguration und Anwendung der Xsolla-seitigen Personalisierung für den Artikelkatalog (Ablauf):
Konfiguration und Anwendung der Xsolla-seitigen Personalisierung für Werbeaktionen (Ablauf):
Hinweis
Detaillierte Informationen finden Sie:
Detaillierte Informationen finden Sie:
- im Leitfaden zur Konfiguration der Personalisierung aufseiten von Xsolla und aufseiten des Partners
- im Schritt-für-Schritt-Tutorial zur Personalisierung des Artikelkatalogs aufseiten von Xsolla
Operationen
Übersicht
Mit Werbeaktionslimits können Sie begrenzen, wie oft ein bestimmter Nutzer eine Werbeaktion in Anspruch nehmen darf. Zudem können Sie festlegen, wann das Limit zurückgesetzt wird.
Limits werden aufseiten von Xsolla gespeichert und in den Werbeaktionseinstellungen im Kundenportal oder über das limits-Objekt in den folgenden API-Aufrufen konfiguriert:
- Rabattaktion für Artikel erstellen oder Rabattaktion aktualisieren
- Bonusaktion erstellen oder Bonusaktion aktualisieren
Informationen zu den Limits werden in den folgenden API-Aufrufen zum Abrufen des Artikelkatalogs im Objekt items.promotions.limits zurückgegeben:
- Liste virtueller Gegenstände abrufen
- Liste virtueller Währungen abrufen
- Liste virtueller Währungspakete abrufen
- Liste der Bundles abrufen
- Spieleliste abrufen
Mit den API-Aufrufen im Unterabschnitt Verwaltung der Gruppe Limits können Sie den aktuellen Status der Limits abrufen und diese für einen bestimmten Nutzer aktualisieren – beispielsweise den Zähler nach Abschluss einer Quest zurücksetzen oder die verbleibende Menge manuell anpassen.
Hinweis
Ausführliche Informationen zur Konfiguration von Limits im Katalog finden Sie im Abschnitt Werbeaktionslimits.
Ausführliche Informationen zur Konfiguration von Limits im Katalog finden Sie im Abschnitt Werbeaktionslimits.
Sie können limits.per_user konfigurieren, d. h., wie häufig ein Nutzer eine Werbeaktion in Anspruch nehmen darf.
Nicht authentifizierten Nutzern wird stets die Höchstzahl angezeigt, also wie oft man die Werbeaktion maximal in Anspruch nehmen darf.
Um anzuzeigen, wie oft der Nutzer die Werbeaktion unter Berücksichtigung des geltenden Limits noch in Anspruch nehmen darf, müssen Sie bei der Abfrage des Artikelkatalogs die Autorisierungsdaten des Nutzers übermitteln.
Um zu konfigurieren, wie häufig das Limit zurückgesetzt werden soll (täglich, wöchentlich oder monatlich), müssen Sie das limits.recurrent_schedule-Objekt beim Erstellen oder Aktualisieren der Werbeaktion übermitteln.
Konfiguration und Durchsetzung von Limits (Anwendungsszenario)
- Sie erstellen eine Werbeaktion mit dem API-Aufruf Rabattaktion für Artikel erstellen oder Bonusaktion erstellen und übermitteln das
limits-Objekt. - Sie rufen den Katalog für einen nicht authentifizierten Nutzer ab – in der Antwort ist das
items.promotions.limits-Objekt enthalten, darin ist angegeben, wie oft die Werbeaktion maximal in Anspruch genommen werden darf. - Der Nutzer meldet sich an.
- Sie rufen den Katalog mit dem Autorisierungstoken des Nutzers ab – in der Antwort ist angegeben, wie oft der Nutzer die Werbeaktion unter Berücksichtigung des aktiven Limits noch in Anspruch nehmen darf.
- Der Nutzer wählt einen Aktionsartikel aus und kauft ihn.
- Nach erfolgreicher Bezahlung aktualisiert Xsolla den Wert des Parameters
items.promotions.limits.per_user. Wenn der Parameter den Wert0erreicht, wird der Artikel in den Katalog-API-Aufrufen ohne Rabatt oder Bonus zurückgegeben. - Sie können das Limit mit den API-Aufrufen aus dem Unterabschnitt Verwaltung aktualisieren:
- Sie rufen den aktualisierten Limitwert (
items.promotions.limits) bei der nächsten Katalogabfrage mit dem Autorisierungstoken des Nutzers ab und zeigen ihn dem Nutzer an.
Übersicht
Belohnungsketten motivieren die Nutzer dazu, im Shop mit echtem Geld einzukaufen. Bei jedem Kauf erhalten die Nutzer Wertpunkte und durchlaufen dabei die einzelnen Schritte einer Belohnungskette. Sind die Nutzer Mitglieder eines Clans, fließen die Wertpunkte aus den Käufen dem gesamten Clan zu. Ausführliche Informationen zur Konfiguration der Belohnungsketten finden Sie im Abschnitt Belohnungssystem.
Verwenden Sie zur Konfiguration von Belohnungsketten die API-Aufrufe aus dem Unterabschnitt Verwaltung. Zur Anzeige von Ketten und zur Inanspruchnahme von Belohnungen verwenden Sie die API-Aufrufe aus dem Unterabschnitt Client. Für die Arbeit mit Clan-Belohnungsketten verwenden Sie die API-Aufrufe aus dem Unterabschnitt Clans-Client.
Konfiguration einer Belohnungskette (Beispielhafter Ablauf):
- Erstellen Sie Artikel mithilfe der API-Aufrufe aus dem Unterabschnitt Verwaltung der Gruppen Virtuelle Gegenstände und Währung oder Bundles.
- rstellen Sie Wertpunkte mithilfe des API-Aufrufs Wertpunkt erstellen.
- Weisen Sie Artikeln Wertpunkte zu, indem Sie den API-Aufruf Wertpunkte für Artikel festlegen verwenden. Beim Kauf dieser Artikel erhalten die Nutzer Wertpunkte.
- Erstellen Sie eine Belohnungskette mithilfe des API-Aufrufs Belohnungskette erstellen. Übermitteln Sie den Parameter
is_enabled: true, um die Kette zu aktivieren. - Implementieren Sie die Anzeige der Belohnungsketten. Fordern Sie dazu die Liste der verfügbaren Ketten mithilfe des API-Aufrufs Belohnungsketten des aktuellen Nutzers abrufen an. In der Antwort sind alle aktiven Ketten und deren Schritte und Statusangaben enthalten.
- Implementieren Sie die Anzeige des Wertpunktguthabens. Verwenden Sie dazu den API-Aufruf Wertpunktestand des aktuellen Nutzers abrufen.
- Implementieren Sie die Inanspruchnahme von Schrittbelohnungen. Verwenden Sie dazu den API-Aufruf Schrittbelohnung gewähren.
- Konfigurieren Sie das Bestellstatus-Tracking, z. B. mithilfe von Webhooks, um Daten zu in Anspruch genommenen Belohnungen umgehend zu erhalten und diese dem Nutzer zu gewähren.
Anfrage
Ruft die Liste der Belohnungsketten ab.
Achtung
Bei allen Projekten ist die Anzahl der Artikel begrenzt, die Sie in der Antwort erhalten können. Der Standard- und Höchstwert beträgt 10 Artikel pro Antwort. Um pro Seite mehr Daten zu erhalten, verwenden Sie die Felder limit und offset.
Bei allen Projekten ist die Anzahl der Artikel begrenzt, die Sie in der Antwort erhalten können. Der Standard- und Höchstwert beträgt 10 Artikel pro Antwort. Um pro Seite mehr Daten zu erhalten, verwenden Sie die Felder limit und offset.
Sicherheit
basicAuth
Pfad
Projekt-ID. Dieser Parameter wird im Kundenportal neben dem Projektnamen angezeigt sowie in der Adressleiste des Browsers, wenn Sie im Kundenportal ein Projekt geöffnet haben. Die URL hat das folgende Format: https://publisher.xsolla.com/<merchant_id>/projects/<project_id>.
Beispiel: 44056
- https://store.xsolla.com/api/v3/project/{project_id}/admin/reward_chain
- Mock serverhttps://xsolla.redocly.app/_mock/de/api/liveops/v3/project/{project_id}/admin/reward_chain
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X GET \
-u <username>:<password> \
'https://store.xsolla.com/api/v3/project/44056/admin/reward_chain?limit=50&offset=0&enabled=0'Die Liste der Belohnungsketten wurde erfolgreich empfangen.
One of:
Eine Belohnungskette.
Objekt mit Lokalisierungen für Artikelnamen. Werte können in zwei Formaten angegeben werden: Sprachencode bestehend aus zwei Kleinbuchstaben (z. B. en) oder fünfstelliger Gebietsschemacode (z. B. en-US). Beide Formate werden als Eingabe akzeptiert, als Antwort werden jedoch stets zweistellige Sprachencodes in Kleinbuchstaben zurückgegeben. Wenn für dieselbe Sprache beide Optionen angegeben sind (z. B. en und en-US), wird der zuletzt angegebene Wert gespeichert. Die vollständige Liste der unterstützten Sprachen finden Sie in der Dokumentation.
Any of:
Sprachencodes bestehend aus zwei Kleinbuchstaben.
Objekt mit Lokalisierungen für Artikelbeschreibungen. Werte können in zwei Formaten angegeben werden: Sprachencode bestehend aus zwei Kleinbuchstaben (z. B. en) oder fünfstelliger Gebietsschemacode (z. B. en-US). Beide Formate werden als Eingabe akzeptiert, als Antwort werden jedoch stets zweistellige Sprachencodes in Kleinbuchstaben zurückgegeben. Wenn für dieselbe Sprache beide Optionen angegeben sind (z. B. en und en-US), wird der zuletzt angegebene Wert gespeichert. Die vollständige Liste der unterstützten Sprachen finden Sie in der Dokumentation.
Any of:
Sprachencodes bestehend aus zwei Kleinbuchstaben.
Objekt mit Lokalisierungen für lange Artikelbeschreibungen. Werte können in zwei Formaten angegeben werden: Sprachencode bestehend aus zwei Kleinbuchstaben (z. B. en) oder fünfstelliger Gebietsschemacode (z. B. en-US). Beide Formate werden als Eingabe akzeptiert, als Antwort werden jedoch stets zweistellige Sprachencodes in Kleinbuchstaben zurückgegeben. Wenn für dieselbe Sprache beide Varianten angegeben sind (z. B. en und en-US), wird der zuletzt angegebene Wert gespeichert. Die vollständige Liste der unterstützten Sprachen finden Sie in der Dokumentation.
Any of:
Sprachencodes bestehend aus zwei Kleinbuchstaben.
Gültigkeitszeitraum der Belohnungskette. Wenn mehrere Zeiträume angegeben sind, sind sowohl date_from als auch date_until erforderlich.
Startdatum für die angegebene Belohnungskette.
Beispiel: "2020-08-11T10:00:00+03:00"
Zusätzliche Medieninhalte des Artikels wie Screenshots, Gameplay-Videos usw.
One of:
Wiederkehrender Reset-Zeitraum der Belohnungskette.
object or null
Conditions for validating user attributes. Determine chain availability based on whether user attributes match all specified conditions.
One of:
Benutzerattributcode.
Art der durchgeführten Operation nach Bedingung. Für den Attributtyp string.
Mögliche Werte:
eq– ist gleichne– ist ungleich
Enum"eq""ne"
Bedingungswert, mit dem der Benutzerattributwert verglichen wird. Der Typ hängt vom Attributtyp ab.
Gibt an, dass die Bedingung erfüllt ist, auch wenn das Attribut in den Benutzerattributen fehlt. Übermitteln Sie true, um den Artikel den Nutzern anzuzeigen, die dieses Attribut nicht haben. Nutzer, die das Attribut haben, dessen Wert jedoch nicht mit dem in der Bedingung angegebenen Wert übereinstimmt, sehen den Artikel nicht. false – Nutzer, die das Attribut haben, dessen Wert jedoch nicht mit dem in der Bedingung angegebenen Wert übereinstimmt oder bei denen das Attribut fehlt, sehen den Artikel nicht.
Ob die Kette für alle Nutzer sichtbar ist. Wenn true festgelegt ist, wird die Kette stets angezeigt, unabhängig vom Authentifizierungsstatus oder den Attributen des Nutzers.
Um die Personalisierung konfigurieren zu können, müssen Sie false übermitteln. Die Logik der Kettenanzeige ist wie folgt:
- Wenn
falseübermittelt wird und die Sichtbarkeitsbedingungen im Arrayattribute_conditionsangegeben sind, gilt die Kette als personalisiert und wird nur autorisierten Nutzern angezeigt, die die angegebenen Bedingungen erfüllen. - Wenn
falseübermittelt wird und das Arrayattribute_conditionsnicht übermittelt wird oder leer ist, wird die Kette auch nicht autorisierten Nutzern angezeigt. Das Gleiche gilt für Fälle, in denen für den autorisierten Nutzer keine passende Kette gefunden wird.
Ob die Belohnungskette (Wertpunkte und Fortschritt aller Nutzer) nach dem Enddatum zurückgesetzt wird:
- Wenn
truefestgelegt ist, wird die Belohnungskette nach dem Enddatum zurückgesetzt. - Wenn
falsefestgelegt ist, wird die Belohnungskette nach dem Enddatum nicht zurückgesetzt.
Hinweis
true ist nicht möglich, wenn: - in
recurrent_scheduleein Zeitraum für das Zurücksetzen angegeben ist. - der Wert
nullim Parameterperiods.date_untilübermittelt wird.
Antwort
application/json
{ "has_more": true, "items": [ { … }, { … } ] }
Pfad
Bodyapplication/jsonProjekt-ID. Dieser Parameter wird im Kundenportal neben dem Projektnamen angezeigt sowie in der Adressleiste des Browsers, wenn Sie im Kundenportal ein Projekt geöffnet haben. Die URL hat das folgende Format: https://publisher.xsolla.com/<merchant_id>/projects/<project_id>.
Beispiel: 44056
One of:
Eine Belohnungskette.
Objekt mit Lokalisierungen für Artikelnamen. Werte können in zwei Formaten angegeben werden: Sprachencode bestehend aus zwei Kleinbuchstaben (z. B. en) oder fünfstelliger Gebietsschemacode (z. B. en-US). Beide Formate werden als Eingabe akzeptiert, als Antwort werden jedoch stets zweistellige Sprachencodes in Kleinbuchstaben zurückgegeben. Wenn für dieselbe Sprache beide Optionen angegeben sind (z. B. en und en-US), wird der zuletzt angegebene Wert gespeichert. Die vollständige Liste der unterstützten Sprachen finden Sie in der Dokumentation.
Any of:
Sprachencodes bestehend aus zwei Kleinbuchstaben.
Objekt mit Lokalisierungen für Artikelbeschreibungen. Werte können in zwei Formaten angegeben werden: Sprachencode bestehend aus zwei Kleinbuchstaben (z. B. en) oder fünfstelliger Gebietsschemacode (z. B. en-US). Beide Formate werden als Eingabe akzeptiert, als Antwort werden jedoch stets zweistellige Sprachencodes in Kleinbuchstaben zurückgegeben. Wenn für dieselbe Sprache beide Optionen angegeben sind (z. B. en und en-US), wird der zuletzt angegebene Wert gespeichert. Die vollständige Liste der unterstützten Sprachen finden Sie in der Dokumentation.
Any of:
Sprachencodes bestehend aus zwei Kleinbuchstaben.
Objekt mit Lokalisierungen für lange Artikelbeschreibungen. Werte können in zwei Formaten angegeben werden: Sprachencode bestehend aus zwei Kleinbuchstaben (z. B. en) oder fünfstelliger Gebietsschemacode (z. B. en-US). Beide Formate werden als Eingabe akzeptiert, als Antwort werden jedoch stets zweistellige Sprachencodes in Kleinbuchstaben zurückgegeben. Wenn für dieselbe Sprache beide Varianten angegeben sind (z. B. en und en-US), wird der zuletzt angegebene Wert gespeichert. Die vollständige Liste der unterstützten Sprachen finden Sie in der Dokumentation.
Any of:
Sprachencodes bestehend aus zwei Kleinbuchstaben.
Gültigkeitszeitraum der Belohnungskette. Wenn mehrere Zeiträume angegeben sind, sind sowohl date_from als auch date_until erforderlich.
Startdatum für die angegebene Belohnungskette.
Beispiel: "2020-08-11T10:00:00+03:00"
Objekt mit Lokalisierungen für Artikelnamen. Werte können in zwei Formaten angegeben werden: Sprachencode bestehend aus zwei Kleinbuchstaben (z. B. en) oder fünfstelliger Gebietsschemacode (z. B. en-US). Beide Formate werden als Eingabe akzeptiert, als Antwort werden jedoch stets zweistellige Sprachencodes in Kleinbuchstaben zurückgegeben. Wenn für dieselbe Sprache beide Optionen angegeben sind (z. B. en und en-US), wird der zuletzt angegebene Wert gespeichert. Die vollständige Liste der unterstützten Sprachen finden Sie in der Dokumentation.
Any of:
Sprachencodes bestehend aus zwei Kleinbuchstaben.
Eindeutige Artikel-ID. Die SKU darf nur lateinische Klein- und Großbuchstaben, Ziffern, Punkte, Bindestriche und Unterstriche enthalten.
Conditions for validating user attributes. Determine reward availability for reward chain steps based on whether user attributes match all specified conditions.
One of:
steps[].reward[].attribute_conditions[].attributestring[ 1 .. 255 ] characters^[-_.\d\w]+$erforderlich
Benutzerattributcode.
Art der durchgeführten Operation nach Bedingung. Für den Attributtyp string.
Mögliche Werte:
eq– ist gleichne– ist ungleich
Enum"eq""ne"
Bedingungswert, mit dem der Benutzerattributwert verglichen wird. Der Typ hängt vom Attributtyp ab.
Gibt an, dass die Bedingung erfüllt ist, auch wenn das Attribut in den Benutzerattributen fehlt. Übermitteln Sie true, um den Artikel den Nutzern anzuzeigen, die dieses Attribut nicht haben. Nutzer, die das Attribut haben, dessen Wert jedoch nicht mit dem in der Bedingung angegebenen Wert übereinstimmt, sehen den Artikel nicht. false – Nutzer, die das Attribut haben, dessen Wert jedoch nicht mit dem in der Bedingung angegebenen Wert übereinstimmt oder bei denen das Attribut fehlt, sehen den Artikel nicht.
One of:
Wiederkehrender Reset-Zeitraum der Belohnungskette.
object or null
Conditions for validating user attributes. Determine chain availability based on whether user attributes match all specified conditions.
One of:
Benutzerattributcode.
Art der durchgeführten Operation nach Bedingung. Für den Attributtyp string.
Mögliche Werte:
eq– ist gleichne– ist ungleich
Enum"eq""ne"
Bedingungswert, mit dem der Benutzerattributwert verglichen wird. Der Typ hängt vom Attributtyp ab.
Gibt an, dass die Bedingung erfüllt ist, auch wenn das Attribut in den Benutzerattributen fehlt. Übermitteln Sie true, um den Artikel den Nutzern anzuzeigen, die dieses Attribut nicht haben. Nutzer, die das Attribut haben, dessen Wert jedoch nicht mit dem in der Bedingung angegebenen Wert übereinstimmt, sehen den Artikel nicht. false – Nutzer, die das Attribut haben, dessen Wert jedoch nicht mit dem in der Bedingung angegebenen Wert übereinstimmt oder bei denen das Attribut fehlt, sehen den Artikel nicht.
Ob die Kette für alle Nutzer sichtbar ist. Wenn true festgelegt ist, wird die Kette stets angezeigt, unabhängig vom Authentifizierungsstatus oder den Attributen des Nutzers.
Um die Personalisierung konfigurieren zu können, müssen Sie false übermitteln. Die Logik der Kettenanzeige ist wie folgt:
- Wenn
falseübermittelt wird und die Sichtbarkeitsbedingungen im Arrayattribute_conditionsangegeben sind, gilt die Kette als personalisiert und wird nur autorisierten Nutzern angezeigt, die die angegebenen Bedingungen erfüllen. - Wenn
falseübermittelt wird und das Arrayattribute_conditionsnicht übermittelt wird oder leer ist, wird die Kette auch nicht autorisierten Nutzern angezeigt. Das Gleiche gilt für Fälle, in denen für den autorisierten Nutzer keine passende Kette gefunden wird.
Ob die Belohnungskette (Wertpunkte und Fortschritt aller Nutzer) nach dem Enddatum zurückgesetzt wird:
- Wenn
truefestgelegt ist, wird die Belohnungskette nach dem Enddatum zurückgesetzt. - Wenn
falsefestgelegt ist, wird die Belohnungskette nach dem Enddatum nicht zurückgesetzt.
Hinweis
true ist nicht möglich, wenn: - in
recurrent_scheduleein Zeitraum für das Zurücksetzen angegeben ist. - der Wert
nullim Parameterperiods.date_untilübermittelt wird.
- https://store.xsolla.com/api/v3/project/{project_id}/admin/reward_chain
- Mock serverhttps://xsolla.redocly.app/_mock/de/api/liveops/v3/project/{project_id}/admin/reward_chain
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X POST \
-u <username>:<password> \
https://store.xsolla.com/api/v3/project/44056/admin/reward_chain \
-H 'Content-Type: application/json' \
-d '{
"name": {
"en": "Reward chain"
},
"description": {
"en": "Reward chain description."
},
"long_description": {
"en": "Lange Beschreibung der Belohnungskette."
},
"is_enabled": true,
"image_url": "https://cdn.xsolla.net/img/misc/images/5c3b8b45c5be5fe7803e59fbc8041be4.png",
"order": 1,
"periods": [
{
"date_from": "2026-01-01T01:00:00+05:00",
"date_until": "2026-01-31T23:59:59+05:00"
},
{
"date_from": "2026-02-01T01:00:00+05:00",
"date_until": "2026-02-28T23:59:59+05:00"
}
],
"value_point": {
"sku": "com.xsolla.value_point_1"
},
"steps": [
{
"name": {
"en": "First step of the reward chain"
},
"image_url": "https://cdn.xsolla.net/img/misc/images/5c3b8b45c5be5fe7803e59fbc8041be4.png",
"reward": [
{
"sku": "com.xsolla.item_1",
"quantity": 5
},
{
"sku": "com.xsolla.item_2",
"quantity": 1
}
],
"price": {
"amount": 10
}
},
{
"name": {
"en": "Second step of the reward chain"
},
"image_url": "https://cdn.xsolla.net/img/misc/images/5c3b8b45c5be5fe7803e59fbc8041be4.png",
"reward": [
{
"sku": "com.xsolla.item_3",
"quantity": 5
},
{
"sku": "com.xsolla.item_4",
"quantity": 1
}
],
"price": {
"amount": 15
}
}
],
"recurrent_schedule": {
"interval_type": "weekly",
"day_of_week": 1,
"time": "01:00:00+08:00"
},
"attribute_conditions": [
{
"attribute": "race",
"operator": "eq",
"value": "ork",
"type": "string",
"can_be_missing": false
}
],
"is_always_visible": true,
"is_reset_after_end": true
}'Antwort
application/json
{ "reward_chain_id": 10 }
Pfad
Projekt-ID. Dieser Parameter wird im Kundenportal neben dem Projektnamen angezeigt sowie in der Adressleiste des Browsers, wenn Sie im Kundenportal ein Projekt geöffnet haben. Die URL hat das folgende Format: https://publisher.xsolla.com/<merchant_id>/projects/<project_id>.
Beispiel: 44056
- https://store.xsolla.com/api/v3/project/{project_id}/admin/reward_chain/id/{reward_chain_id}
- Mock serverhttps://xsolla.redocly.app/_mock/de/api/liveops/v3/project/{project_id}/admin/reward_chain/id/{reward_chain_id}
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X GET \
-u <username>:<password> \
https://store.xsolla.com/api/v3/project/44056/admin/reward_chain/id/101Die angegebene Belohnungskette wurde erfolgreich empfangen.
One of:
Eine Belohnungskette.
Objekt mit Lokalisierungen für Artikelnamen. Werte können in zwei Formaten angegeben werden: Sprachencode bestehend aus zwei Kleinbuchstaben (z. B. en) oder fünfstelliger Gebietsschemacode (z. B. en-US). Beide Formate werden als Eingabe akzeptiert, als Antwort werden jedoch stets zweistellige Sprachencodes in Kleinbuchstaben zurückgegeben. Wenn für dieselbe Sprache beide Optionen angegeben sind (z. B. en und en-US), wird der zuletzt angegebene Wert gespeichert. Die vollständige Liste der unterstützten Sprachen finden Sie in der Dokumentation.
Any of:
Sprachencodes bestehend aus zwei Kleinbuchstaben.
Objekt mit Lokalisierungen für Artikelbeschreibungen. Werte können in zwei Formaten angegeben werden: Sprachencode bestehend aus zwei Kleinbuchstaben (z. B. en) oder fünfstelliger Gebietsschemacode (z. B. en-US). Beide Formate werden als Eingabe akzeptiert, als Antwort werden jedoch stets zweistellige Sprachencodes in Kleinbuchstaben zurückgegeben. Wenn für dieselbe Sprache beide Optionen angegeben sind (z. B. en und en-US), wird der zuletzt angegebene Wert gespeichert. Die vollständige Liste der unterstützten Sprachen finden Sie in der Dokumentation.
Any of:
Sprachencodes bestehend aus zwei Kleinbuchstaben.
Objekt mit Lokalisierungen für lange Artikelbeschreibungen. Werte können in zwei Formaten angegeben werden: Sprachencode bestehend aus zwei Kleinbuchstaben (z. B. en) oder fünfstelliger Gebietsschemacode (z. B. en-US). Beide Formate werden als Eingabe akzeptiert, als Antwort werden jedoch stets zweistellige Sprachencodes in Kleinbuchstaben zurückgegeben. Wenn für dieselbe Sprache beide Varianten angegeben sind (z. B. en und en-US), wird der zuletzt angegebene Wert gespeichert. Die vollständige Liste der unterstützten Sprachen finden Sie in der Dokumentation.
Any of:
Sprachencodes bestehend aus zwei Kleinbuchstaben.
Gültigkeitszeitraum der Belohnungskette. Wenn mehrere Zeiträume angegeben sind, sind sowohl date_from als auch date_until erforderlich.
Startdatum für die angegebene Belohnungskette.
Beispiel: "2020-08-11T10:00:00+03:00"
Eindeutige Artikel-ID. Die SKU darf nur lateinische Klein- und Großbuchstaben, Ziffern, Punkte, Bindestriche und Unterstriche enthalten.
Objekt mit Lokalisierungen für Artikelbeschreibungen. Werte können in zwei Formaten angegeben werden: Sprachencode bestehend aus zwei Kleinbuchstaben (z. B. en) oder fünfstelliger Gebietsschemacode (z. B. en-US). Beide Formate werden als Eingabe akzeptiert, als Antwort werden jedoch stets zweistellige Sprachencodes in Kleinbuchstaben zurückgegeben. Wenn für dieselbe Sprache beide Optionen angegeben sind (z. B. en und en-US), wird der zuletzt angegebene Wert gespeichert. Die vollständige Liste der unterstützten Sprachen finden Sie in der Dokumentation.
Any of:
Sprachencodes bestehend aus zwei Kleinbuchstaben.
Objekt mit Lokalisierungen für lange Artikelbeschreibungen. Werte können in zwei Formaten angegeben werden: Sprachencode bestehend aus zwei Kleinbuchstaben (z. B. en) oder fünfstelliger Gebietsschemacode (z. B. en-US). Beide Formate werden als Eingabe akzeptiert, als Antwort werden jedoch stets zweistellige Sprachencodes in Kleinbuchstaben zurückgegeben. Wenn für dieselbe Sprache beide Varianten angegeben sind (z. B. en und en-US), wird der zuletzt angegebene Wert gespeichert. Die vollständige Liste der unterstützten Sprachen finden Sie in der Dokumentation.
Any of:
Sprachencodes bestehend aus zwei Kleinbuchstaben.
Objekt mit Lokalisierungen für Artikelnamen. Werte können in zwei Formaten angegeben werden: Sprachencode bestehend aus zwei Kleinbuchstaben (z. B. en) oder fünfstelliger Gebietsschemacode (z. B. en-US). Beide Formate werden als Eingabe akzeptiert, als Antwort werden jedoch stets zweistellige Sprachencodes in Kleinbuchstaben zurückgegeben. Wenn für dieselbe Sprache beide Optionen angegeben sind (z. B. en und en-US), wird der zuletzt angegebene Wert gespeichert. Die vollständige Liste der unterstützten Sprachen finden Sie in der Dokumentation.
Any of:
Sprachencodes bestehend aus zwei Kleinbuchstaben.
Zusätzliche Medieninhalte des Artikels wie Screenshots, Gameplay-Videos usw.
Objekt mit Lokalisierungen für Artikelnamen. Werte können in zwei Formaten angegeben werden: Sprachencode bestehend aus zwei Kleinbuchstaben (z. B. en) oder fünfstelliger Gebietsschemacode (z. B. en-US). Beide Formate werden als Eingabe akzeptiert, als Antwort werden jedoch stets zweistellige Sprachencodes in Kleinbuchstaben zurückgegeben. Wenn für dieselbe Sprache beide Optionen angegeben sind (z. B. en und en-US), wird der zuletzt angegebene Wert gespeichert. Die vollständige Liste der unterstützten Sprachen finden Sie in der Dokumentation.
Any of:
Sprachencodes bestehend aus zwei Kleinbuchstaben.
Eindeutige Artikel-ID. Die SKU darf nur lateinische Klein- und Großbuchstaben, Ziffern, Punkte, Bindestriche und Unterstriche enthalten.
Conditions for validating user attributes. Determine reward availability for reward chain steps based on whether user attributes match all specified conditions.
One of:
Benutzerattributcode.
Art der durchgeführten Operation nach Bedingung. Für den Attributtyp string.
Mögliche Werte:
eq– ist gleichne– ist ungleich
Enum"eq""ne"
Bedingungswert, mit dem der Benutzerattributwert verglichen wird. Der Typ hängt vom Attributtyp ab.
Gibt an, dass die Bedingung erfüllt ist, auch wenn das Attribut in den Benutzerattributen fehlt. Übermitteln Sie true, um den Artikel den Nutzern anzuzeigen, die dieses Attribut nicht haben. Nutzer, die das Attribut haben, dessen Wert jedoch nicht mit dem in der Bedingung angegebenen Wert übereinstimmt, sehen den Artikel nicht. false – Nutzer, die das Attribut haben, dessen Wert jedoch nicht mit dem in der Bedingung angegebenen Wert übereinstimmt oder bei denen das Attribut fehlt, sehen den Artikel nicht.
One of:
Wiederkehrender Reset-Zeitraum der Belohnungskette.
object or null
Conditions for validating user attributes. Determine chain availability based on whether user attributes match all specified conditions.
One of:
Art der durchgeführten Operation nach Bedingung. Für den Attributtyp string.
Mögliche Werte:
eq– ist gleichne– ist ungleich
Enum"eq""ne"
Bedingungswert, mit dem der Benutzerattributwert verglichen wird. Der Typ hängt vom Attributtyp ab.
Gibt an, dass die Bedingung erfüllt ist, auch wenn das Attribut in den Benutzerattributen fehlt. Übermitteln Sie true, um den Artikel den Nutzern anzuzeigen, die dieses Attribut nicht haben. Nutzer, die das Attribut haben, dessen Wert jedoch nicht mit dem in der Bedingung angegebenen Wert übereinstimmt, sehen den Artikel nicht. false – Nutzer, die das Attribut haben, dessen Wert jedoch nicht mit dem in der Bedingung angegebenen Wert übereinstimmt oder bei denen das Attribut fehlt, sehen den Artikel nicht.
Ob die Kette für alle Nutzer sichtbar ist. Wenn true festgelegt ist, wird die Kette stets angezeigt, unabhängig vom Authentifizierungsstatus oder den Attributen des Nutzers.
Um die Personalisierung konfigurieren zu können, müssen Sie false übermitteln. Die Logik der Kettenanzeige ist wie folgt:
- Wenn
falseübermittelt wird und die Sichtbarkeitsbedingungen im Arrayattribute_conditionsangegeben sind, gilt die Kette als personalisiert und wird nur autorisierten Nutzern angezeigt, die die angegebenen Bedingungen erfüllen. - Wenn
falseübermittelt wird und das Arrayattribute_conditionsnicht übermittelt wird oder leer ist, wird die Kette auch nicht autorisierten Nutzern angezeigt. Das Gleiche gilt für Fälle, in denen für den autorisierten Nutzer keine passende Kette gefunden wird.
Ob die Belohnungskette (Wertpunkte und Fortschritt aller Nutzer) nach dem Enddatum zurückgesetzt wird:
- Wenn
truefestgelegt ist, wird die Belohnungskette nach dem Enddatum zurückgesetzt. - Wenn
falsefestgelegt ist, wird die Belohnungskette nach dem Enddatum nicht zurückgesetzt.
Hinweis
true ist nicht möglich, wenn: - in
recurrent_scheduleein Zeitraum für das Zurücksetzen angegeben ist. - der Wert
nullim Parameterperiods.date_untilübermittelt wird.
Antwort
application/json
{ "reward_chain_id": 1, "name": { "en": "Reward chain" }, "description": { "en": "Reward chain description" }, "long_description": { "en": "Reward chain long description" }, "is_enabled": true, "image_url": "https://cdn.xsolla.net/img/misc/images/5c3b8b45c5be5fe7803e59fbc8041be4.png", "order": 1, "periods": [ { … }, { … } ], "value_point": { "sku": "com.xsolla.reward_vp_1", "name": { … }, "type": "value_point", "is_enabled": true, "description": { … }, "long_description": { … }, "image_url": "https://cdn.xsolla.net/img/misc/images/5c3b8b45c5be5fe7803e59fbc8041be4.png", "media_list": [], "order": 1, "is_clan": false }, "steps": [ { … }, { … } ], "recurrent_schedule": { "day_of_week": 2, "displayable_reset_next_date": "2026-01-06T01:00:00+05:00", "displayable_reset_start_date": "2026-01-01T01:00:00+05:00", "interval_type": "weekly", "reset_next_date": 1767643200, "time": "01:00:00+05:00" }, "attribute_conditions": [ { … } ], "is_always_visible": true, "is_reset_after_end": true }
Übersicht
Angebotsketten sind eine Abfolge von Schritten mit jeweils einem Artikel, den Nutzer im Rahmen eines aktiven Angebots kaufen oder kostenlos erhalten können. Angebotsketten können exklusive Artikel umfassen, die nur im Rahmen der Kette erhältlich sind, sowie Artikel zu vergünstigten Preisen (verglichen mit den Preisen im Shop). Ausführliche Informationen zur Konfiguration dieses Marketingtools finden Sie im Abschnitt Angebotsketten.
Verwenden Sie zur Konfiguration von Angebotsketten die API-Aufrufe aus dem Unterabschnitt Verwaltung. Mit den API-Aufrufen aus dem Unterabschnitt Client können Sie die Ketten anzeigen und die Logik für die Arbeit mit den Artikeln implementieren.
Konfiguration einer Angebotskette (Beispielhafter Ablauf):
Erstellen Sie Artikel mithilfe der API-Aufrufe aus dem Unterabschnitt Verwaltung der Gruppe Virtuelle Gegenstände und Währung oder Bundles.
Erstellen Sie eine Kette mithilfe des API-Aufrufs Angebotskette erstellen. Übermitteln Sie den Parameter
is_enabled: true, um die Kette zu aktivieren.Implementieren Sie die Anzeige der Angebotskette. Fordern Sie dazu die Liste der verfügbaren Ketten mithilfe des API-Aufrufs Angebotsketten des aktuellen Nutzers abrufen an. In der Antwort sind alle aktiven Ketten und deren Schritte und Statusangaben enthalten.
Implementieren Sie die Logik für den Umgang mit Artikeln, die Nutzer erhalten:
Wenn es sich um einen kostenlosen Artikel handelt, verwenden Sie den API-Aufruf Kostenlosen Angebotskettenschritt sichern. Übermitteln Sie
offer_chain_idundstep_numberin der Anfrage.Wenn es sich um einen kostenpflichtigen Artikel handelt, verwenden Sie den API-Aufruf Bestellung für kostenpflichtigen Angebotskettenschritt anlegen. Übermitteln Sie
offer_chain_idundstep_numberin der Anfrage. In der Antwort ist dieorder_idund der Token zum Öffnen des Zahlungsportals enthalten.
Konfigurieren Sie das Bestellstatus-Tracking, z. B. mithilfe von Webhooks, um Daten zu in Anspruch genommenen oder gekauften Artikeln umgehend zu erhalten und diese dem Nutzer zu gewähren.
