Virtuelle Gegenstände

So funktioniert's

Bei virtuellen Gegenständen handelt es sich um Ingame-Inhalte, die Sie gegen echte oder virtuelle Währung verkaufen können.

Hauptmerkmale:

Merkmale der Preiskonfiguration:

  • Ein Artikel kann sowohl in echter als auch in virtueller Währung bepreist werden.
  • Sie können Preise in mehreren echten oder virtuellen Währungen festlegen. In diesem Falle müssen Sie eine Standardwährung festlegen.
  • Sie können einen Artikel erstellen, ohne seinen Preis in echter oder virtueller Währung anzugeben. Wird ein solcher Artikel im Shop angezeigt, ist er für die Benutzer kostenlos erhältlich.

Einschränkungen bei der Preiskonfiguration:

  • Sie können keinen Artikel mit einem Preiswert von Null erstellen.

Es gibt drei Typen von virtuellen Gegenständen:

Aufbrauchbare virtuelle Gegenstände

Ein aufbrauchbar Gegenstand ist ein Gegenstand im Inventar. Er lässt sich in großer Stückzahl und mehrmals kaufen. Die Menge nimmt mit jedem Einsatz durch den Benutzer ab.

Hauptmerkmale:

  • Auffüllen des Bestands an Gegenständen im Inventar.
  • Hinterlegen zahlreicher Instanzen desselben Gegenstands im Benutzerinventar.
  • Nutzung/Verbrauch kann aufseiten des Clients erfolgen.

Beispiel: Granaten, Kugeln usw.

Nicht aufbrauchbare virtuelle Gegenstände

Ein nicht aufbrauchbar virtueller Gegenstand ist ein Gegenstand im Inventar. Er kann nur einmal gesammelt bzw. gekauft werden.

Hauptmerkmale:

  • Benutzer können nur ein Stück dieses Gegenstands im Inventar halten.
  • Verschwindet durch den Einsatz aufseiten des Clients nicht aus dem Inventar. Lässt sich nur durch eine Servermethode aus dem Inventar entfernen.

Beispiel: Status, Skins, vorinstallierte DLC, Zugang zu einem Ort, Werbefreiheit in Handyspielen usw.

Zeitlich begrenzte Artikel

Bei einem zeitlich begrenzten Artikel handelt es sich um einen Einmalkauf. Der Benutzer muss ihn also nach Ablauf erneut erwerben.

Hauptmerkmale:

  • Wird nach dem Ablauf inaktiv.
  • Benutzer muss das Abonnement erneut erwerben, damit es aktiviert wird.

Beispiel: Battle Pass, Season Pass, temporärer Zugriff auf Ingame-Items, Skins oder sonstige Inhalte.

Weitere Informationen finden Sie in der Anleitung für zeitlich begrenzte Artikel.

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

Der Artikelkauf lässt sich beschränken. Sie können beispielsweise:

  • festlegen, wie viele Artikel ein Benutzer kaufen darf;
  • Willkommensartikel erstellen, die nur einmal gekauft werden können.

Erreicht der Benutzer das festgelegte Limit, wird ihm der Artikel nicht mehr im Katalog angezeigt.

Sie können die maximale und die verbleibende Anzahl von Artikeln anzeigen, die der Benutzer kaufen kann.

Um beim Erstellen eines virtuellen Gegenstands im Kundenportal ein Kauflimit festzulegen, müssen Sie den Schalter Anzahl der Käufe dieses Artikels pro Benutzer beschränken auf Ein stellen, und festlegen, wie oft der virtuelle Gegenstand gekauft werden darf.

Sie können die Methoden der Untergruppe Katalog aus der Methodengruppe Virtuelle Gegenstände und Währung nutzen, um Informationen über Artikel abzurufen.

In der Antwort sind neben den Informationen über den virtuellen Gegenstand die folgenden Daten enthalten:

  • wie viele Artikel ein Benutzer maximal kaufen kann
  • die verbleibende Anzahl der Artikel, die ein Benutzer kaufen kann

Wie Sie Beschränkungen einrichten oder aktualisieren, erfahren Sie in der Anleitung Limits pro Benutzer.

Hinweis

Nicht autorisierten Benutzern wird stets angezeigt, wie viele Artikel sie maximal kaufen können. Um dem Benutzer die verbleibende Anzahl der Artikel (vorbehaltlich des aktuellen Limits) anzuzeigen, müssen Sie den Artikelkatalog mithilfe der Methoden des Unterabschnitts Katalog aus der Methodengruppe Virtuelle Gegenstände und Währung anfordern und dabei die Benutzerautorisierungsdaten übermitteln.

Um die Anzahl der für den Benutzer erhältlichen Artikel korrekt anzuzeigen, müssen Sie die Authentifizierung konfigurieren.

Antwortbeispiel:
Copy
Full screen
Small screen

{
  "items": [
    {
      "sku": "big_rocket",
      "name": "Big Rocket",
      "groups": [
        {
          "external_id": "accessory",
          "name": "Accessory"
        }
      ],
      "attributes": [
        {
          "external_id": "stack_size",
          "name": "Stack size",
          "values": [
            {
              "external_id": "size_e3364991f92e751689a68b96598a5a5a84010b85",
              "value": "5"
            }
          ]
        }
      ],
      "type": "virtual_good",
      "description": "Big Rocket - description",
      "image_url": "https://popmedia.blob.core.windows.net/popyourself/male/outfit/male_armor_white_a-01.png",
      "is_free": false,
      "price": {
        "amount": "100.99",
        "amount_without_discount": "100.99",
        "currency": "USD"
      },
      "virtual_prices": [
        {
          "amount": 100,
          "sku": "vc_test",
          "is_default": true,
          "amount_without_discount": 100,
          "image_url": "http://image.png",
          "name": "SHOTGUN FOR TRUE RAIDERS",
          "type": "virtual_currency",
          "description": "description"
        }
      ],
      "can_be_bought": true,
      "inventory_options": {
        "consumable": {
          "usages_count": 1
        },
        "expiration_period": {
          "type": "day",
          "value": 1
        }
      },
      "virtual_item_type": "non_renewing_subscription",
      "limits": {
        "per_user": {
            "total": 5,
            "available": 5
        },
        "per_item": null
      },
}
Hinweis

Xsolla achtet darauf, dass die Limits nicht überschritten werden und verhindert, dass Benutzer mehr Artikel als erlaubt kaufen.

Öffnet ein Benutzer das Zahlungsportal und bezahlt einen Artikel, verfallen alle unbezahlten Bestellungen, die diesen Artikel enthalten.

Beispiel: Der Benutzer öffnet Zahlungsmasken für einen Artikel, der Kaufbeschränkungen unterliegt, in mehreren Browser-Tabs. Es werden also automatisch mehrere Bestellungen für denselben Artikel angelegt. Nach dem Kauf des Artikels in einem der geöffneten Tabs storniert Xsolla alle unbezahlten Bestellungen, die denselben Artikel enthalten.

Anzeigedauer für virtuelle Gegenstände im Shop begrenzen

Sie können den Anzeigezeitraum für einen virtuellen Gegenstand im Shop festlegen und dadurch:
  • den Katalog je nach Zeitraum relevanter gestalten, z. B. während der Weihnachtsfeiertage
  • einen virtuellen Gegenstand im Voraus erstellen, ohne ihn im Katalog anzuzeigen
  • Benutzer zum Kauf motivieren, indem man einen Timer neben dem virtuellen Gegenstand einblendet
Hinweis
Wenn Sie eine Katalogoberfläche mit dem Site Builder erstellen, wird der Timer automatisch eingeblendet. Wenn Sie einen Katalog ohne den Site Builder erstellen, müssen Sie den Timer selbst implementieren.
Sie können im Kundenportal festlegen, wie lange ein Artikel im Shop angezeigt wird. Wählen sie dazu 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.
Hinweis
Nachdem Sie einen virtuellen Gegenstand, eine virtuelle Währung oder ein virtuelles Währungspaket erstellt haben, können Sie dem Artikel einen Status zuweisen und so festlegen, ob er verfügbar, nicht verfügbar oder teilweise verfügbar ist.
Um die Anzeigedauer eines virtuellen Gegenstands im Shop über die API zu begrenzen, übermitteln Sie die folgenden Parameter im API-Aufruf Virtuellen Gegenstand erstellen oder Virtuellen Gegenstand aktualisieren:
  • periods[0].date_from mitsamt dem Startdatum und der Startuhrzeit des Anzeigezeitraums des virtuellen Gegenstands im Format YYYY-MM-DDThh:mm:ss±TMZ, wobei TMZ die Zeitzonenangabe im Format hh:mm ist.
  • periods[0].date_until mitsamt dem Enddatum und der Enduhrzeit des Anzeigezeitraums des virtuellen Gegenstands im Format YYYY-MM-DDThh:mm:ss±TMZ, wobei TMZ die Zeitzonenangabe – bezogen auf GMT – im Format hh:mm ist. Wenn Sie keine Ende für den Anzeigezeitraum des virtuellen Gegenstands festlegen möchten, übermitteln Sie null.

Sie können mehrere Zeiträume für die Anzeige eines virtuellen Gegenstands im Shop festlegen. Übermitteln Sie dazu in der Methode Virtuellen Gegenstand erstellen oder Virtuellen Gegenstand aktualisieren ein Objekt-Array mit dem jeweiligen Start- und Enddatum der Zeiträume.

Beispiel:

Copy
Full screen
Small screen
    "periods": [
          {
            "date_from": "2022-06-10T14:00:00+03:00",
            "date_until": "2022-06-30T14:00:00+03:00"
          },
           {
            "date_from": "2022-07-10T14:00:00+03:00",
            "date_until": "2022-07-30T14:00:00+03:00"
          },
           {
            "date_from": "2022-08-10T14:00:00+03:00",
            "date_until": "2022-08-30T14:00:00+03:00"
          }
    ]
    

    Für wen ist es

    • Partner, die eine Spielökonomie aufbauen oder ihr Spiel monetarisieren möchten, indem sie es um virtuelle Währung ergänzen, mit der sich virtuelle Gegenstände kaufen lassen.
    • Partner, die den In-Game Store integriert haben und einen neuen Produkttyp (virtuelle Gegenstände) einrichten möchten.

    Wie komme ich dazu

    Integrationsablauf

    1. Konfigurieren Sie virtuelle Gegenstände und Gruppen virtueller Gegenstände.
    2. Konfigurieren Sie regionale Beschränkungen und regionale Preise.

    Virtuelle Gegenstände und Gruppen virtueller Gegenstände konfigurieren

    Um virtuelle Gegenstände einrichten zu können, müssen Sie Gruppen von virtuellen Gegenständen konfigurieren. Mit Gruppen können Sie einen hierarchisch strukturierten Katalog erstellen. Gegenstände, denen keine bestimmte Gruppe zugewiesen ist, werden der Gruppe Ungrouped hinzugefügt.

    Sie können virtuelle Gegenstände und Gruppen virtueller Gegenstände wie folgt einrichten:

    Konfiguration über das Kundenportal

    Konfiguration über API-Aufrufe

    Nutzen Sie die API-Aufrufe aus der Untergruppe Admin der Gruppe Virtual Items & Currency, um virtuelle Gegenstände einzurichten.
    Achtung
    Methoden aus der Untergruppe Admin sind nicht dazu bestimmt, einen Katalog im Front-End des Online-Shops zu erstellen. Sie kommen stattdessen bei Landing-Pages, Internetshops und Ingame-Logiken zum Einsatz.

    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>/<Publisher Account section>.

    • 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
    Achtung

    Weitere Informationen über die Arbeit mit API-Schlüsseln finden Sie in der API-Referenz.

    Wichtige Empfehlungen:

    • Sie sind selbst dafür verantwortlich, den generierten API-Schlüssel zu speichern. Der API-Schlüssel wird im Kundenportal nur einmal angezeigt, nämlich dann, wenn er erstellt wird.
    • Halten Sie Ihren API-Schlüssel geheim. Er gewährt den Zugang zu Ihrem persönlichen Konto und Ihren Projekten im Kundenportal.
    • Der API-Schlüssel muss auf Ihrem Server gespeichert sein, niemals in Binärdateien oder im Frontend.

    Wenn ein API-Aufruf, den Sie benötigen, nicht den Pfadparameter project_id enthält, verwenden Sie den API-Schlüssel, der in allen Projekten des Unternehmens gültig ist, um die Autorisierung einzurichten.

    Nutzen Sie die API-Aufrufe aus der Untergruppe Catalog der Gruppe Virtual Items & Currency, um den Katalog mit virtuellen Gegenständen aufseiten des Clients abzurufen. Diese Aufrufe erfordern keine Basisautorisierung.

    Nutzen Sie den API-Aufruf Get virtual items list, um die komplette, nicht in Gruppen unterteilte 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 Get items list by specified group.

    Regionale Beschränkungen und regionale Preise festlegen

    Um regionale Beschränkungen für virtuelle Gegenstände einzurichten, übermitteln Sie ein Array von Objekten mit den Kennungen der Regionen, in denen der Gegenstand erhältlich sein soll, an den Aufruf Create item oder Update item.
    Copy
    Full screen
    Small screen
    "regions": [{
         “id”: “123”
      }, {
         “id”: “456”
      }
    ]
    

    Um regionale Preise für virtuelle Gegenstände einzurichten, übermitteln Sie ein Array von Objekten mit regionalen Preiseinstellungen an den Aufruf Create item oder Update item.

    Copy
    Full screen
    Small screen
    "regional_prices": [{
         “region_id”: “123”,
         “country_iso”: “CHN”,
         “amount”: 40,
         “currency_iso”: “CNY”,
         “is_default”: true,
         “is_enabled”: true
      }
    ]
    
    Hinweis
    Sie sollten die Regionen vorab im Projekt konfigurieren. Wenden Sie sich dazu an Ihren Customer Success Manager oder senden Sie eine E-Mail an csm@xsolla.com.
    War dieser Artikel hilfreich?
    Vielen Dank!
    Gibt es etwas, das wir verbessern können? Nachricht
    Das tut uns leid
    Bitte erläutern Sie, weshalb dieser Artikel nicht hilfreich ist. Nachricht
    Vielen Dank für Ihr Feedback!
    Wir werden Ihr Feedback aufgreifen und dazu nutzen, Ihr Erlebnis verbessern.
    Letztmalig aktualisiert: 10. Oktober 2023

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

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