Zum Inhalt springen
/
Katalogfilterregel lösche...

LiveOps-API (2.0.0)

Überblick

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.

API-Aufrufe

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.

Authentifizierung

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.

Authentifizierung mit Benutzer-JWT

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.

HTTP-Basisauthentifizierung

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.

Bei der serverseitigen Basisauthentifizierung müssen alle API-Anfragen den folgenden Header enthalten:

  • für basicAuth – Authorization: Basic <your_authorization_basic_key>, wobei your_authorization_basic_key das gemäß Base64-Verfahren kodierte project_id:api_key-Paar ist
  • für basicMerchantAuth – Authorization: Basic <your_authorization_basic_key>, wobei your_authorization_basic_key das gemäß Base64-Verfahren kodierte merchant_id:api_key Paar ist

Die Parameterwerte finden Sie im Kundenportal an folgenden Orten:

  • merchant_id wird 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_id wird 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_key wird 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 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.

Authentifizierung mit Unterstützung für Gastzugang

Das Authentifizierungsschema AuthForCart wird für Warenkorbkäufe verwendet und unterstützt zwei Modi:

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

  2. 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-id samt Anfrage-ID
    • x-user samt der E-Mail-Adresse des Nutzers, kodiert in Base64

Grundstruktur der Entität

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.

Identifikation

  • merchant_id – Firmen-ID im Kundenportal
  • project_id – Projekt-ID im Kundenportal
  • sku – Artikel-SKU, einzigartig innerhalb des Projekts

Shop-Anzeige

  • name – Artikelname
  • description – Artikelbeschreibung
  • image_url – Bild-URL
  • is_enabled – Artikelverfügbarkeit
  • is_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ört
  • order – Anzeigereihenfolge im Katalog

Verkaufsbedingungen

  • prices – Preise in echter oder virtueller Währung
  • limits – Kauflimits
  • periods – Verfügbarkeitszeiträume
  • regions – 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": []
}

Grundlegender Kaufablauf

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

Artikel und Gruppen erstellen (Verwaltung)

Erstellen Sie für Ihren Shop einen Katalog mit Artikeln wie etwa virtuellen Gegenständen, Bundles oder virtueller Währung.

API-Aufrufe (Beispiele):

Werbeaktionen, Ketten und Limits einrichten (Verwaltung)

Konfigurieren Sie Tools für die Nutzergewinnung und Monetarisierung, wie etwa Rabatte, Boni, tägliche Belohnungen oder Angebotsketten.

API-Aufrufe (Beispiele):

Artikelinformationen abrufen (Client)

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.

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 "show_inactive_time_limited_items": 1 in der Kataloganfrage ergänzen.

Artikel verkaufen

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.

Schnellkauf

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.

Warenkorbkauf

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:

  1. 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).
  2. Aktualisieren Sie den Warenkorbinhalt basierend auf den Aktionen des Nutzers:
Hinweis

Mit dem API-Aufruf "Warenkorb des aktuellen Benutzers abrufen" können Sie den aktuellen Status des Warenkorbs abrufen.
  1. 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 new zugewiesen.

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:

  1. 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).
  2. 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 new zugewiesen.

Zahlungsportal öffnen

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.

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

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 angelegt
  • paid – Zahlung erhalten
  • done – Artikel geliefert
  • canceled – Bestellung storniert
  • expired – Bestellung abgelaufen

Tracken Sie den Bestellstatus mit einer der folgenden Methoden:

Paginierung

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 Seite
  • offset – Index des ersten Elements auf der Seite (Nummerierung beginnt bei 0)
  • has_more – gibt an, ob eine weitere Seite verfügbar ist
  • total_items_count – Gesamtanzahl der Elemente

Beispielanfrage:

GET /items?limit=20&offset=40

Beispielantwort:

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

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

Lokalisierung

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:

  • name
  • description
  • long_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"
  }
}

Fehlerantwortformat

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 Anfrage
  • 401 – Authentifizierungsfehler
  • 403 – mangelnde Berechtigungen
  • 404 – Ressource nicht gefunden
  • 422 – Validierungsfehler
  • 429 – 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
index.json
index.yaml
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):

  1. Erstellen Sie Artikel mit den Aufrufen aus dem Unterabschnitt Verwaltung der Gruppen Virtuelle Gegenstände und Währung, Bundles oder Spielschlüssel.
  2. Erstellen Sie eine Werbeaktion mit dem Aufruf Rabattaktion für Artikel erstellen. Übermitteln Sie im items-Array die erforderlichen Artikel-SKUs.
  3. 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, wobei date_from das Startdatum und date_until das Enddatum des Gültigkeitszeitraums definiert.
  4. Aktivieren Sie eine Werbeaktion mit dem Aufruf Artikelaktion aktualisieren. Übermitteln Sie den Parameter "is_enabled": true.
  5. 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.

Konfiguration einer Werbeaktion (Beispiel)

Weitere Informationen zur Konfiguration von Werbeaktionen finden Sie in unserer Dokumentation:

Allgemeine API-Aufrufe

Mit den API-Methoden aus diesem Unterabschnitt können Sie verschiedene Arten von Werbeaktionen verwalten.

Operationen

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.

So konfigurieren Sie die Personalisierung aufseiten von Xsolla mithilfe der Xsolla-API:

  1. Erstellen Sie Artikel mit den API-Aufrufen aus dem Unterabschnitt Verwaltung der Gruppen Virtuelle Gegenstände und Währung, Bundles oder Spielschlüssel.

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

  3. Konfigurieren Sie die Personalisierung für Artikel oder Werbeaktionen:

  4. Ü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):

Personalisierung für den Artikelkatalog

Konfiguration und Anwendung der Xsolla-seitigen Personalisierung für Werbeaktionen (Ablauf):

Personalisierung für Werbeaktionen

Hinweis

Detaillierte Informationen finden Sie:
Operationen

Katalogfilterregel patchenServer-sideAdministrator

Anfrage

Aktualisiert eine bestimmte Regel, die für Benutzerattribute gilt. Bei einer unbestimmten Eigenschaft wird der aktuelle Wert verwendet.

Sicherheit
basicAuth
Pfad
project_idintegererforderlich

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
rule_idnumbererforderlich

Regel-ID.

Beispiel: 1
Bodyapplication/json
namestring[ 1 .. 255 ] characters^\S

Verständlicher Name einer Regel. Dient dazu, eine Regel im Kundenportal anzuzeigen.

is_enabledboolean

Wenn die Regel aktiviert ist.

is_satisfied_for_unauthboolean

Ob der Artikel nicht autorisierten Nutzern angezeigt wird. Ist true festgelgt, wird der Artikel dem nicht autorisierten Nutzer unabhängig von den Kataloganzeigeregeln angezeigt. Standardmäßig ist false festgelgt.

attribute_conditionsArray of objects[ 1 .. 100 ] items

Conditions for validating user attributes. Determine item availability in the catalog based on whether user attributes match all specified conditions.

One of:
attribute_conditions[].​attributestring[ 1 .. 255 ] characters^[-_.\d\w]+$erforderlich

Benutzerattributcode.

attribute_conditions[].​typestringerforderlich

Benutzerattributtyp.

Wert"string"
attribute_conditions[].​operatorstringerforderlich

Art der durchgeführten Operation nach Bedingung. Für den Attributtyp string.

Mögliche Werte:

  • eq – ist gleich
  • ne – ist ungleich
Enum"eq""ne"
attribute_conditions[].​valuestring<= 255 characterserforderlich

Bedingungswert, mit dem der Benutzerattributwert verglichen wird. Der Typ hängt vom Attributtyp ab.

attribute_conditions[].​can_be_missingboolean

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.

itemsArray of objects[ 1 .. 100 ] items
One of:

Artikel, die einem Nutzer angezeigt werden, sofern ihre Attributwerte die Bedingungen erfüllen.

items[].​item_idnumbererforderlich

Artikel-ID.

curl -i -X PATCH \
  -u <username>:<password> \
  https://store.xsolla.com/api/v2/project/44056/admin/user/attribute/rule/1 \
  -H 'Content-Type: application/json' \
  -d '{
    "is_enabled": false
  }'

Antworten

Aktualisierung war erfolgreich.

Antwort
Kein Inhalt

Katalogfilterregel löschenServer-sideAdministrator

Anfrage

Löscht eine bestimmte Regel.

Sicherheit
basicAuth
Pfad
project_idintegererforderlich

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
rule_idnumbererforderlich

Regel-ID.

Beispiel: 1
curl -i -X DELETE \
  -u <username>:<password> \
  https://store.xsolla.com/api/v2/project/44056/admin/user/attribute/rule/1

Antworten

Löschen war erfolgreich.

Antwort
Kein Inhalt

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

Informationen zu den Limits werden in den folgenden API-Aufrufen zum Abrufen des Artikelkatalogs im Objekt items.promotions.limits zurückgegeben:

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.

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)

  1. Sie erstellen eine Werbeaktion mit dem API-Aufruf Rabattaktion für Artikel erstellen oder Bonusaktion erstellen und übermitteln das limits-Objekt.
  2. 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.
  3. Der Nutzer meldet sich an.
  4. 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.
  5. Der Nutzer wählt einen Aktionsartikel aus und kauft ihn.
  6. Nach erfolgreicher Bezahlung aktualisiert Xsolla den Wert des Parameters items.promotions.limits.per_user. Wenn der Parameter den Wert 0 erreicht, wird der Artikel in den Katalog-API-Aufrufen ohne Rabatt oder Bonus zurückgegeben.
  7. Sie können das Limit mit den API-Aufrufen aus dem Unterabschnitt Verwaltung aktualisieren:
  8. 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.

Werbeaktionslimits

Verwaltung

Operationen

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

  1. Erstellen Sie Artikel mithilfe der API-Aufrufe aus dem Unterabschnitt Verwaltung der Gruppen Virtuelle Gegenstände und Währung oder Bundles.
  2. rstellen Sie Wertpunkte mithilfe des API-Aufrufs Wertpunkt erstellen.
  3. Weisen Sie Artikeln Wertpunkte zu, indem Sie den API-Aufruf Wertpunkte für Artikel festlegen verwenden. Beim Kauf dieser Artikel erhalten die Nutzer Wertpunkte.
  4. Erstellen Sie eine Belohnungskette mithilfe des API-Aufrufs Belohnungskette erstellen. Übermitteln Sie den Parameter is_enabled: true, um die Kette zu aktivieren.
  5. 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.
  6. Implementieren Sie die Anzeige des Wertpunktguthabens. Verwenden Sie dazu den API-Aufruf Wertpunktestand des aktuellen Nutzers abrufen.
  7. Implementieren Sie die Inanspruchnahme von Schrittbelohnungen. Verwenden Sie dazu den API-Aufruf Schrittbelohnung gewähren.
  8. 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.

Konfiguration einer Belohnungskette (Ablauf)

Administrator

Operationen

Client

Operationen

Clans-Client

Operationen

Administrator

Operationen

Client

Operationen

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

  1. Erstellen Sie Artikel mithilfe der API-Aufrufe aus dem Unterabschnitt Verwaltung der Gruppe Virtuelle Gegenstände und Währung oder Bundles.

  2. Erstellen Sie eine Kette mithilfe des API-Aufrufs Angebotskette erstellen. Übermitteln Sie den Parameter is_enabled: true, um die Kette zu aktivieren.

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

  4. Implementieren Sie die Logik für den Umgang mit Artikeln, die Nutzer erhalten:

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

Konfiguration einer Belohnungskette (Ablauf)

Administrator

Operationen

Client

Operationen

Administrator

Operationen

Client

Operationen