Virtuelle Gegenstände

Überblick

Virtuelle Gegenstände sind Ingame-Items, die Nutzer gegen echte oder virtuelle Währung kaufen oder als Bonus erhalten können. Diese Gegenstände sind nicht physisch und werden ausschließlich im Spiel verwendet. Beispiele für virtuelle Gegenstände sind: Skins, Tränke, Waffen, Schlüssel und andere Artikel, die das Gameplay oder das Aussehen eines Spielecharakters beeinflussen.

Hauptmerkmale:

• Flexible Preisgestaltung:
  • Es ist möglich, für denselben Artikel einen Preis in echter und virtueller Währung anzugeben.
  • Es ist möglich, Preise für denselben Artikel in mehreren echten und virtuellen Währungen anzugeben. In diesem Fall müssen Sie für jeden Währungstyp eine Standardwährung angeben: eine für echte Währungen und eine für virtuelle Währungen.
  • Es ist möglich, kostenlose Artikel zu erstellen.
  • Es ist möglich, regionale Preise festzulegen.
• Das Land und die zugehörige Landeswährung wird automatisch ermittelt.
• Verfügbare Einstellungen:
  • Beschränkung des Verkaufs von Artikeln in verschiedenen Regionen.
  • Begrenzung der Anzahl der käuflichen Artikel.
  • Begrenzung der Anzeigedauer für Artikel im Shop.
  • Erstellen von Artikeln, die nicht käuflich erhältlich sind. Ein Artikel kann im Katalog ausgeblendet sein, aber weiterhin als Teil eines Bundles erworben oder als Bonus für den Kauf eines anderen Artikels erhalten werden.
• Katalogstruktur:
  • Erstellen von Gruppen.
  • Sortierung der Artikel im Katalog.

Im Kundenportal einrichten

Gruppe erstellen

Gruppen ermöglichen es, einen mehrstufigen Katalog zu erstellen. Artikel, die keiner Gruppe zugewiesen sind, werden in der Gruppe Ungruppiert abgelegt. Die Gruppe Ungruppiert kann weder bearbeitet noch gelöscht werden.

So erstellen Sie eine Gruppe:

1. Navigieren Sie im Kundenportal zu Store > Virtuelle Gegenstände.
2. Klicken Sie auf +, und wählen Sie aus der Drop-down-Liste die Option Gruppe erstellen aus.

3. Legen Sie die folgenden Parameter fest:
   • Externe ID – eindeutige Gruppen-ID
   • Gruppenname
4. Damit die Gruppe im Shop angezeigt wird, müssen Sie den Schalter Gruppe im Online-Shop anzeigen auf Ein stellen. Daraufhin wird der Gruppe der Status Aktiviert zugewiesen. Sie können den Gruppenstatus später ändern.
5. Klicken Sie auf Gruppe erstellen.

Hinweis

Hat eine Gruppe den Status Deaktiviert, wird eine solche Gruppe:

• bei Aufruf der API-Methode Liste der Artikelgruppen abrufen nicht in der Antwort zurückgegeben.
• nicht in den Eigenschaften von Artikeln, die in dieser Gruppe enthalten sind, angezeigt, wenn clientseitige API-Methoden für den Abruf der Artikelliste aufgerufen werden.
• in Site Builder nicht zur Verwendung angezeigt.

Um den Status einer erstellten Gruppe zu ändern, müssen Sie einfach die gewünschte Gruppe unter Store > Virtuelle Gegenstände suchen und den gewünschten Status in der Spalte Status auswählen.

Sie können einen mehrstufigen Katalog erstellen, indem Sie neue Gruppen innerhalb bestehender Gruppen einfügen. Eine Ausnahme bildet die Gruppe Ungruppiert – darin lassen sich keine untergeordneten Gruppen erstellen.

So fügen Sie eine bestehende Gruppe in eine andere Gruppe ein:

1. Navigieren Sie im Kundenportal zu Store > Virtuelle Gegenstände.
2. Wählen Sie die Gruppe aus, die Sie in eine andere bestehende Gruppe einfügen möchten.
3. Klicken Sie auf •••, und wählen Sie aus der Drop-down-Liste die Option Gruppe bearbeiten aus.
4. Wählen Sie in der Drop-down-Liste Verzeichnisort die übergeordnete Gruppe aus, in der die aktuelle Gruppe platziert werden soll.

5. Klicken Sie auf Änderungen speichern.

Virtuellen Gegenstand erstellen

So erstellen Sie einen virtuellen Gegenstand:

1. Navigieren Sie im Kundenportal zu Store > Virtuelle Gegenstände.
2. Klicken Sie auf +, und wählen Sie aus der Drop-down-Liste die Option Artikel anlegen aus.

3. Legen Sie den Verfügbarkeitsstatus des virtuellen Gegenstands im Katalog fest. Wählen Sie eine der folgenden Optionen aus:
   • Nicht verfügbar (Standard) – der Gegenstand kann nicht im Katalog erworben werden, in keinem Bundle enthalten sein und auch nicht als Bonus für den Kauf eines anderen Artikels gewährt werden.
   • Verfügbar – der Gegenstand kann im Katalog erworben werden, in einem Bundle enthalten sein oder als Bonus für den Kauf eines anderen Gegenstands gewährt werden.
   • Teilweise verfügbar – der Gegenstand kann nicht im Katalog erworben, jedoch einem Bundle hinzugefügt oder als Bonus für den Kauf eines anderen Artikels gewährt werden.
   Sie können den Verfügbarkeitsstatus des Gegenstands später ändern.

4. Konfigurieren Sie die grundlegenden Einstellungen. Legen Sie Folgendes fest:
   • Bild (optional)
   • SKU
   • eine oder mehrere Gruppen, zu denen der Gegenstand gehören soll
   • Gegenstandsname
   • Gegenstandsbeschreibung (optional)

5. Belassen Sie die Gegenstandseigenschaft auf der Standardeinstellung: Aufbrauchbar (empfohlen).

6. Legen Sie Preise für die virtuellen Gegenstände fest:
   • Wenn Sie einen kostenlosen Gegenstand erstellen möchten, müssen Sie im Feld Kostenpflichtig oder kostenlos die Option Kostenloser Gegenstand auswählen.
   • Wenn Sie einen kostenpflichtigen Gegenstand erstellen möchten, müssen Sie im Feld Kostenpflichtig oder kostenlos die Option Kostenpflichtiger Gegenstand auswählen und den Preis in einer oder mehreren Währungen angeben.
   • Legen Sie regionale Preise fest (optional).

7. Begrenzen Sie, wie viele Artikel ein Nutzer kaufen kann (optional). Gehen Sie dazu wie folgt vor:
   1. Stellen Sie den Schalter Anzahl der Käufe dieses Artikels pro Benutzer beschränken auf Ein, und legen Sie fest, wie viele Artikel ein Nutzer maximal kaufen darf.
   2. Legen Sie fest, wann das Limit zurückgesetzt werden soll:
      1. Soll das Limit nicht zurückgesetzt werden, wählen Sie aus der Drop-down-Liste die Option Nicht regelmäßig aktualisieren aus.
      2. Soll das Limit hingegen regelmäßig zurückgesetzt werden, müssen Sie aus der Drop-down-Liste einen Zeitraum und das Datum auswählen.
8. Begrenzen Sie, wie lange die Artikel im Shop angezeigt werden (optional). Wählen Sie dazu im Feld Im Online-Shop anzeigen die Option Zeitraum aus, und legen Sie die Zeitzone sowie das Start- und das Enddatum fest. Wenn Sie kein Enddatum für den Anzeigezeitraum des Artikels festlegen möchten, setzen Sie ein Häkchen bei Kein Enddatum.
9. Ergänzen Sie zusätzliche Attribute (optional).
10. Klicken Sie auf Artikel anlegen.

Arbeiten mit virtuellen Gegenständen über die API

Nutzen Sie die API-Aufrufe aus der Untergruppe Verwaltung der Gruppe Virtuelle Gegenstände und Währung, um virtuelle Gegenstände einzurichten.

Die Basisauthentifizierung wird für API-Aufrufe genutzt. Übermitteln Sie Authorization:Basic <your_authorization_basic_key>, wobei <your_authorization_basic_key> das gemäß dem Base64-Standard kodierte Paar Händler-ID:API-Schlüssel ist. Die Parameter finden Sie im Kundenportal:

• Die Händler-ID 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>/.

• Der API-Schlüssel wird im Kundenportal nur einmal angezeigt, nämlich dann, wenn er erstellt wird. Sie sind selbst dafür verantwortlich, den Schlüssel zu speichern. Einen neuen Schlüssel können Sie in den folgenden Abschnitten erstellen:
  • Firmeneinstellungen > API-Schlüssel
  • Projekteinstellungen > API-Schlüssel

Nutzen Sie die API-Aufrufe aus der Untergruppe Katalog der Gruppe Virtuelle Gegenstände und Währung, um den Katalog mit virtuellen Gegenständen aufseiten des Clients abzurufen. Diese Aufrufe erfordern keine Basisautorisierung.

Nutzen Sie den API-Aufruf Liste virtueller Gegenstände abrufen, um die komplette, ungruppierte Liste der Gegenstände abzurufen. Um eine Liste der in einer bestimmten Gruppe enthaltenen Gegenstände abzurufen, übermitteln Sie den Parameter external_id an den Aufruf Artikelliste anhand angegebener Gruppe abrufen.

Erweiterte Einstellungen für virtuelle Gegenstände

Anzahl der käuflich erhältlichen Artikel beschränken

Sie können festlegen, wie oft ein bestimmter virtueller Gegenstand von einem einzelnen Nutzer maximal gekauft werden kann. Dadurch können Sie exklusive Angebote erstellen und deren Verfügbarkeit steuern.

Beispielhafte Anwendungsfälle:

• Tägliche, wöchentliche oder monatliche Kauflimits für einen virtuellen Gegenstand.
• Ein Willkommensartikel, der nur einmal gekauft werden kann.

Kauflimits lassen sich auf zwei Wege konfigurieren:

• Im Kundenportal: Stellen Sie beim Erstellen oder Bearbeiten eines Artikels den Schalter Anzahl der Käufe dieses Artikels durch einen Nutzer beschränken auf Ein, und legen Sie das Limit sowie den Zeitraum, nach dem das Limit zurückgesetzt wird, fest.
• Über die API: Übermitteln Sie beim Erstellen oder Aktualisieren eines Artikels die Kauflimits im Anfragerumpf im Objekt limits.

Xsolla kümmert sich vollumfänglich um die Durchsetzung der Limits. Das System verfolgt, wie oft ein Nutzer einen Artikel gekauft hat, und verhindert, dass das festgelegte Limit überschritten wird.

Wenn ein Nutzerzugriffstoken in einer Kataloganfrage enthalten ist (beim Aufruf von API-Methoden aus dem Unterabschnitt Katalog der Gruppe Virtuelle Gegenstände und Währung), berechnet Xsolla, wie viele Stückzahlen jedes Artikels der jeweilige Nutzer noch kaufen kann. In der Antwort ist das Objekt limits enthalten, das die zulässige Gesamtmenge (den Parameter total) und die für diesen Nutzer verfügbare Restmenge (den Parameter available) enthält. Beide Werte können verwendet werden, um die Verfügbarkeit auf der Benutzeroberfläche anzuzeigen.

Ist in der Anfrage kein Nutzerzugriffstoken angegeben, entspricht der Wert des Parameters available immer dem Gesamtlimit in der Antwort.

Antwort mit Artikeln, die einem Kauflimit unterliegen (Beispiel):

 1{
 2  "items": [
 3    {
 4      "sku": "big_rocket",
 5      "name": "Big Rocket",
 6      "groups": [
 7        {
 8          "external_id": "accessory",
 9          "name": "Accessory"
10        }
11      ],
12      "attributes": [
13        {
14          "external_id": "stack_size",
15          "name": "Stack size",
16          "values": [
17            {
18              "external_id": "size_e3364991f92e751689a68b96598a5a5a84010b85",
19              "value": "5"
20            }
21          ]
22        }
23      ],
24      "type": "virtual_good",
25      "description": "Big Rocket - description",
26      "image_url": "https://popmedia.blob.core.windows.net/popyourself/male/outfit/male_armor_white_a-01.png",
27      "is_free": false,
28      "price": {
29        "amount": "100.99",
30        "amount_without_discount": "100.99",
31        "currency": "USD"
32      },
33      "virtual_prices": [
34        {
35          "amount": 100,
36          "sku": "vc_test",
37          "is_default": true,
38          "amount_without_discount": 100,
39          "image_url": "http://image.png",
40          "name": "SHOTGUN FOR TRUE RAIDERS",
41          "type": "virtual_currency",
42          "description": "description"
43        }
44      ],
45      "can_be_bought": true,
46      "inventory_options": {
47        "consumable": {
48          "usages_count": 1
49        },
50        "expiration_period": {
51          "type": "day",
52          "value": 1
53        }
54      },
55      "virtual_item_type": "non_renewing_subscription",
56      "limits": {
57        "per_user": {
58            "total": 5,
59            "available": 5
60        },
61        "per_item": null
62      },
63}

Darüber hinaus überprüft Xsolla das Kauflimit sowohl bei der Initialisierung des Bezahlvorgangs als auch beim Abschluss der Bestellung. Wenn ein Nutzer mehrere Browser-Tabs geöffnet hat oder versucht, mehrere Bestellungen gleichzeitig anzulegen, schreitet das System ein und verhindert, dass das Limit überschritten wird. Hierzu werden alle unbezahlten Bestellungen, die bereits gekaufte Artikel enthalten, storniert.

Anzeigedauer für Artikel im Shop begrenzen

Sie können festlegen, wie lange Artikel im Shop angezeigt werden, um:

• den Katalog je nach Zeitraum relevanter zu gestalten, z. B. während der Weihnachtsfeiertage
• einen Artikel im Voraus zu erstellen, ohne ihn im Katalog anzuzeigen
• einen Timer neben dem Artikel einzublenden und so Nutzer zum Kauf zu animieren

Sie können den Anzeigezeitraum für einen Artikel im Shop auf folgende Wege festlegen:

• Im Kundenportal: Wählen Sie beim Erstellen oder Bearbeiten eines Artikels im Feld Im Online-Shop anzeigen die Option Zeitraum aus, und geben Sie die Zeitzone sowie das Start- und das Enddatum an. Wenn Sie kein Enddatum festlegen möchten, setzen Sie ein Häkchen bei Kein Enddatum.
• Über die API: Ergänzen Sie beim Erstellen oder Aktualisieren eines Artikels die folgenden Parameter im Objekt periods:
  • periods[0].date_from – das Startdatum samt Uhrzeit im Format YYYY-MM-DDThh:mm:ss±hh:mm.
  • periods[0].date_until – das Enddatum samt Uhrzeit. Wenn Sie kein Enddatum festlegen möchten, übermitteln Sie den Wert null.

Sie können mehrere Anzeigezeiträume mithilfe der API festlegen, indem Sie ein Array von Objekten mit jeweils einem Start- und Enddatum übermitteln.

Zeitraum-Array (Beispiel):

 1"periods": [
 2      {
 3        "date_from": "2022-06-10T14:00:00+03:00",
 4        "date_until": "2022-06-30T14:00:00+03:00"
 5      },
 6       {
 7        "date_from": "2022-07-10T14:00:00+03:00",
 8        "date_until": "2022-07-30T14:00:00+03:00"
 9      },
10       {
11        "date_from": "2022-08-10T14:00:00+03:00",
12        "date_until": "2022-08-30T14:00:00+03:00"
13      }
14]

Regionale Beschränkungen festlegen

Sie können festlegen, in welchen Regionen ein virtueller Gegenstand erhältlich ist. So können Sie steuern, wem der Gegenstand angezeigt wird. Zum Beispiel können Sie den Artikel für Nutzer in bestimmten Ländern ausblenden oder ihn nur in bestimmten Regionen im Rahmen einer regionalen Werbekampagne verfügbar machen.

Um regionale Beschränkungen für virtuelle Gegenstände festzulegen, müssen Sie ein Array mit regions-Objekten und den entsprechenden Regions-IDs in den Anfragerumpf einfügen, wenn Sie die API-Methode Virtuellen Gegenstand erstellen oder Virtuellen Gegenstand aktualisieren aufrufen.

Regionen-Array (Beispiel):

1"regions": [{
2     “id”: “123”
3  }, {
4     “id”: “456”
5  }
6]

Regionale Preise festlegen

Sie können regionale Preise festlegen und so die Kosten für virtuelle Gegenstände an die Wirtschaftslage verschiedener Länder anpassen. Dadurch werden Angebote für Nutzer in Regionen mit unterschiedlicher Kaufkraft attraktiver, was sowohl die Konversionsraten als auch den Gesamtumsatz erhöht.

Regionale Preise lassen sich auf folgende Wege festlegen:

• Im Kundenportal (manuell): Scrollen Sie beim Erstellen oder Bearbeiten eines Artikels zum Abschnitt Preiseinstellungen, stellen Sie den Schalter Preise in echter Währung auf Ein, und klicken Sie auf Preise festlegen. Sie können die Preise entweder manuell eingeben oder sie automatisch auf der Grundlage von Wechselkursen und Steuern berechnen lassen.
• Über einen CSV-Import im Kundenportal: In der CSV-Datei können Sie mehrere Zeilen mit Artikelpreisen für bestimmte Regionen hinzufügen. Weitere Informationen zur Dateistruktur und Beispiele finden Sie in der Anleitung Länderspezifische Preise.

 1SKU,Currency,Amount,Country,IsDefault,Platform
 2game-key-1,EUR,9.09,,1,steam
 3game-key-1,EUR,9.2,DE,0,steam
 4game-key-1,EUR,8.09,IT,0,steam
 5game-key-1,USD,10.1,US,0,steam
 6game-key-1,MYR,47,MY,0,steam
 7game-key-2,EUR,2.09,,1,steam
 8game-key-2,EUR,2.2,DE,0,steam
 9game-key-2,EUR,1.79,IT,0,steam
10game-key-2,USD,2.3,US,0,steam
11game-key-2,MYR,24,MY,0,steam

• Über die API: Fügen Sie beim Erstellen oder Aktualisieren eines Artikels das Array prices mit den regionalen Preiseinstellungen in den Anfragerumpf ein.

 1"prices": [
 2      {
 3        "amount": 100,
 4        "currency": "USD",
 5        "is_enabled": true,
 6        "is_default": true
 7      },
 8      {
 9        "amount": 200,
10        "currency": "CZK",
11        "country_iso": "CZ",
12        "is_enabled": false,
13        "is_default": false
14      }
15    ]

Nützliche Links