Kostenlose Artikel

So funktioniert's

Kostenlose Artikel sind Artikel, die Nutzer erhalten können, ohne virtuelle oder echte Währung auszugeben. Kostenlose Artikel lassen sich für folgende Szenarien erstellen:

• Verkauf von Ingame-Items: virtuelle Gegenstände, virtuelle Währungspakete und Bundles
• Verkauf von Spielen und DLCs über Spielschlüssel

• Kostenlose Artikel, die zu Projektmeilensteinen oder besonderen Anlässen (wie beispielsweise einem Jubiläum) angeboten werden, um Nutzer für ihre Treue zu belohnen.
• Kostenlose Add-ons als Treueprämie für Nutzer, die das Basisspiel bereits erworben haben.
• Kostenlose Starterpakete im Web Shop, um neue Nutzer für das Spiel zu gewinnen.

Kostenlose Artikel einrichten

Im Kundenportal einrichten

1. Navigieren Sie in Ihrem Kundenportal-Projekt zum Menüpunkt Artikelkatalog > Alle Artikel.
2. Klicken Sie auf Hinzufügen, und wählen Sie aus der Drop-down-Liste die Option Virtuelle Gegenstände aus.

3. Legen Sie die folgenden Parameter fest:
   • Bild (optional)
   • SKU
   • eine oder mehrere Gruppen, zu denen das Bundle gehören soll
   • Name
   • Beschreibung (optional)
4. Wählen Sie unter Preiseinstellungen die Option Kostenloser Gegenstand aus.
5. Wenn Sie begrenzen möchten, wie oft ein Nutzer den Gegenstand kaufen darf, müssen Sie den Schalter Anzahl der Käufe dieses Artikels pro Benutzer beschränken aktivieren und die gewünschte Höchstmenge festlegen.
6. So legen Sie fest, wie oft das Limit zurückgesetzt wird:
   1. Wählen Sie in der Drop-down-Liste einen Zeitraum aus:
      • Täglich
      • Wöchentlich
      • Monatlich
      • Benutzerdefiniertes Intervall – wird anhand des Anzeigezeitraums des Bundles berechnet.
      • Nicht regelmäßig aktualisieren
   2. Legen Sie entsprechend dem gewählten Zeitraum fest, wann das Limit zurückgesetzt werden soll.
7. Legen Sie fest, wie der Gegenstand im Shop angezeigt werden soll:
   • Wählen Sie einen Status aus.
   • Legen Sie einen Anzeigezeitraum für den Gegenstand fest (optional): Geben Sie die Zeitzone sowie den Beginn und das Ende des Zeitraums an. Wenn Sie kein Enddatum angeben möchten, aktivieren Sie das Kontrollkästchen Kein Enddatum.
8. Konfigurieren Sie die Artikelattribute (optional) mithilfe einer der folgenden Optionen:
   • Attribute und zugehörige Werte im JSON-Format hinzufügen
   • Attribute und Werte manuell erstellen und diese einem bestimmten Artikel zuordnen
9. Klicken Sie auf Artikel anlegen.

Über die API einrichten

Damit ein Artikel kostenlos wird, müssen Sie beim Aufruf der folgenden API-Aufrufe aus der Gruppe Verwaltung im Anfragerumpf den Parameterwert “is_free”: true übermitteln:

• Virtuellen Gegenstand erstellen oder Virtuellen Gegenstand aktualisieren
• Spiel erstellen, Spiel anhand der ID aktualisieren oder Spiel anhand der SKU aktualisieren
• Virtuelle Währung erstellen oder Virtuelle Währung aktualisieren
• Virtuelles Währungspaket erstellen oder Virtuelles Währungspaket aktualisieren
• Bundle erstellen oder Bundle aktualisieren

• limits und die gewünschte Menge
• limits.recurrent_schedule und wie häufig das Limit zurückgesetzt werden soll

Kostenlose Artikel im Shop anzeigen

Kostenlose Artikel werden im Katalog angezeigt, je nachdem, wie sie implementiert sind: über Site Builder oder über die API.

Anzeige über Site Builder

So zeigen Sie kostenlose Artikel auf Ihrer Website an:

1. Erstellen Sie einen kostenlosen Artikel.
2. Navigieren Sie im Kundenportal zum Menüpunkt Storefronts > Websites.
3. Klicken Sie bei der gewünschten Website auf Site Builder öffnen.

4. Wählen Sie im Online-Shop-Block im Feld Artikeltyp den kostenlosen Artikeltyp aus, und geben Sie gegebenenfalls dessen Gruppe an.
5. Wählen Sie ein Artikelkarten-Layout aus.
6. Gehen Sie wie folgt vor, nachdem Sie alle erforderlichen Änderungen vorgenommen haben und Ihre Website für den Launch bereit ist:
   1. Klicken Sie oben rechts im Site Builders auf Veröffentlichen.
   2. Aktivieren Sie die Kontrollkästchen neben den Seiten, die Sie veröffentlichen wollen.
   3. Klicken Sie Veröffentlichen.

Informationen zu kostenlosen Artikel über die API abrufen

Wenn Sie den Katalog mittels API konfiguriert haben, lassen sich Daten zu kostenlosen Artikeln über die im Unterabschnitt Katalog aufgelisteten Aufrufe abrufen:

• Liste virtueller Gegenstände abrufen
• Liste virtueller Währungen abrufen
• Liste virtueller Währungspakete abrufen
• Liste der Bundles abrufen
• Spieleliste abrufen

Nutzern kostenlose Artikel gewähren

Wie eine Bestellung mit kostenlosen Artikeln abgewickelt wird, hängt davon ab, ob beim Kauf ein Warenkorb verwendet wird. Wenn ein Nutzer einen Artikel ohne die Warenkorbfunktion kauft, müssen Sie den API-Aufruf Bestellung mit angegebenem kostenlosen Artikel anlegen verwenden. Wenn ein Nutzer Artikel mit der Warenkorbfunktion kauft, sind folgende Szenarien möglich:

• Wenn im Warenkorb des Nutzers sowohl kostenpflichtige als auch kostenlose Artikel enthalten sind, müssen Sie den API-Aufruf Bestellung mit allen Artikeln aus einem angegebenen Warenkorb anlegen oder Bestellung mit allen Artikeln aus dem aktuellen Warenkorb anlegen verwenden. In diesem Fall schließt der Nutzer die Zahlung im Zahlungsportal ab.
• Wenn im Warenkorb des Nutzers nur kostenlose Artikel enthalten sind, müssen Sie den API-Aufruf Bestellung mit einem kostenlosen Warenkorb anlegen oder Bestellung mit einem bestimmten kostenlosen Warenkorb anlegen verwenden. In diesem Fall wird das Zahlungsportal nicht verwendet.

In beiden Fällen sendet Xsolla den Webhook Erfolgreiche Bezahlung der Bestellung mitsamt den Artikeldaten, die zur Gewährung der Artikel an den Nutzer verwendet werden. Bei kostenlosen Artikeln wird der Parameter order.invoice_id im Webhook auf null gesetzt.

Bestellobjekt für kostenlose Artikel (Beispiel):

 1{
 2  "method": "POST",
 3  "url": "https://mybestgame.com/xsolla/notification",
 4  "body": {
 5    "items": [
 6      {
 7        "sku": "gift_direct_game_reward-supercoin",
 8        "type": "virtual_currency",
 9        "is_pre_order": false,
10        "quantity": 500,
11        "amount": "0",
12        "promotions": [
13
14        ]
15      },
16      {
17        "sku": "package-500_supercoin",
18        "type": "bundle",
19        "is_pre_order": false,
20        "quantity": 1,
21        "amount": "0",
22        "promotions": [
23
24        ]
25      },
26      {
27        "sku": "xsolla-giveaway_offer_11_14_22",
28        "type": "bundle",
29        "is_pre_order": false,
30        "quantity": 1,
31        "amount": "0",
32        "promotions": [
33
34        ]
35      }
36    ],
37    "notification_type": "order_paid",
38    "order": {
39      "id": 12345678,
40      "mode": "default",
41      "currency_type": "unknown",
42      "currency": null,
43      "amount": "0",
44      "status": "paid",
45      "platform": "xsolla",
46      "comment": null,
47      "invoice_id": null,
48      "promotions": [
49
50      ]
51    },
52    "user": {
53      "external_id": "1234567812345678",
54      "email": null
55    }
56  },
57  "headers": {
58    "Authorization": "Signature 3b840ccefea111dcdfd111db1fdc6df969a3ec11",
59    "Accept": "application/json",
60    "Content-Type": "application/json"
61  },
62  "type": "webhook_payment",
63  "callback_parameters": {
64    "order_id": 12345678
65  }
66}

Je nach Ihren Projektintegrationseinstellungen werden Artikel dem Nutzer auf eine der folgenden Arten gewährt:

• Wenn Sie PlayFab integriert haben, werden virtuelle Währungen und Gegenstände automatisch dem PlayFab-Inventar des Nutzers hinzugefügt.
• Wenn Sie ein eigenes Bereitstellungssystem verwenden, werden alle virtuellen Gegenstände und Währungen von Ihrem System gewährt. Wir empfehlen, einen Webhook-Handler einzurichten, um Bestelldaten in Ihrem Backend zu empfangen. Die erforderlichen Daten sind im Webhook Erfolgreiche Bezahlung der Bestellung enthalten.