Kostenlose Artikel

Funktionsweise

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 Spielschlüsseln für Spiele und DLCs

Anwendungsfälle:

• Kostenlose Artikel, die zu bestimmten Meilensteinen oder besonderen Anlässen wie einem Jubiläum angeboten werden, um Nutzer für ihre Treue zu belohnen.
• Kostenlose Add-ons für Nutzer, die das Basisspiel bereits gekauft haben, als Belohnung für ihre Treue.
• Kostenlose Starterpakete im Webshop, um neue Nutzer für das Spiel zu gewinnen.

Nur autorisierte Nutzer können kostenlose virtuelle Gegenstände, virtuelle Währungen und Bundles erhalten. Kostenlose Spielschlüssel sind hingegen für alle Nutzer (ob autorisiert oder nicht) verfügbar. Begrenzungen dahingehend, wie viele kostenlose Artikel man erhalten kann, können nur für autorisierte Nutzer konfiguriert werden.

Kostenlose Artikel einrichten

2. Wählen Sie erst Manuell erstellen aus und danach in der Drop-down-Liste die Option Virtuelle Gegenstände.

3. Geben Sie im Abschnitt Allgemeine Einstellungen Folgendes an:
   • SKU
   • eine oder mehrere Gruppen, zu denen der Artikel gehören soll (optional)
   • Name
   • kurze Beschreibung
   • erweiterte Beschreibung – aktivieren Sie hierzu den entsprechenden Schalter (optional)

4. Im Abschnitt Medien können Sie optional ein oder mehrere Bilder oder Videos von Ihrem Gerät oder über einen Link hochladen. In dem mit dem Xsolla-Website-Editor erstellten Shop wird auf allen Artikelkarten die als Main gekennzeichnete Datei angezeigt, während die übrigen Dateien nur auf Artikelkarten mit einer Mediengalerie sichtbar sind. Die als Main gekennzeichnete Datei wird außerdem in den Antworten der API-Aufrufe zur Katalogabfrage zurückgegeben.

5. Wählen Sie unter Preiseinstellungen die Option Kostenloser Gegenstand aus.

6. So begrenzen Sie, wie viele Artikel ein Nutzer erhalten kann:
   1. Aktivieren Sie den Schalter im Abschnitt Limits, und legen Sie die gewünschte Höchstmenge fest.
   2. Konfigurieren Sie, wie häufig das Limit zurückgesetzt werden soll. Wählen Sie dazu einen Zeitraum aus der Drop-down-Liste aus:
      1. Täglich.
      2. Wöchentlich.
      3. Monatlich.
      4. Benutzerdefiniertes Intervall. Das Intervall läuft ab dem Datum los, an dem der Artikel im Shop erstmals angezeigt wird.
      5. Nicht regelmäßig zurücksetzen.
   3. Legen Sie anhand der Parameter für den ausgewählten Zeitraum fest, wann das Limit zurückgesetzt wird.

7. So richten Sie eine zeitliche Anzeigebegrenzung für den Artikel ein (optional):

   1. Aktivieren Sie den Schalter im Abschnitt Bestimmten Anzeigezeitraum hinzufügen.
   2. Legen Sie die Zeitzone sowie den Beginn und das Ende des Zeitraums fest.

   Aktivieren Sie bei Bedarf den Schalter Kein Enddatum, um das Ende des Anzeigezeitraums offen zu lassen.

8. Konfigurieren Sie Attribute optional auf eine der folgenden Arten:
   1. Attribute und zugehörige Werte im JSON-Format hinzufügen
   2. Attribute und Werte manuell erstellen und diese einem bestimmten Artikel zuordnen

9. Klicken Sie auf Erstellen.
10. Wählen Sie im sich öffnenden Fenster den Artikelstatus aus, und klicken Sie danach auf Weiter.

Der erstellte Artikel wird im Abschnitt Alle Artikel angezeigt.

Ü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 Wenn Sie begrenzen möchten, wie viele kostenlose Artikel ein Nutzer erhalten kann, müssen Sie in den Aufrufen zum Erstellen oder Aktualisieren des Artikels die folgenden Parameter übermitteln:
  • limits und die entsprechende Menge
  • limits.recurrent_schedule und wie oft das Limit zurückgesetzt werden soll

Sie können außerdem den Anzeigezeitraum für Artikel im Shop konfigurieren und regionale Beschränkungen festlegen.

Kostenlose Artikel im Katalog 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 kostenlose Artikel.

2. Navigieren Sie in Ihrem Projekt im Kundenportal zum Menüpunkt Storefronts > Websites.
3. Klicken Sie bei der gewünschten Website auf Site Builder öffnen.

2. Navigieren Sie in Ihrem Projekt im Handyspiele-Konto zum Menüpunkt Web Shop.
3. Klicken Sie auf die gewünschten Website.

4. Wenn Ihre Website aus mehreren Seiten besteht, wählen Sie die gewünschte Seite aus:
   1. Klicken Sie oben im Site Builder auf den Titel der aktuellen Seite.
   2. Wählen Sie die gewünschte Seite aus der Drop-down-Liste aus.
5. Wählen Sie im Online-Shop-Block im Feld Artikeltyp den kostenlosen Artikeltyp aus, und geben Sie gegebenenfalls dessen Gruppe an.
6. Konfigurieren Sie das Artikelkarten-Layout.
7. Nachdem Sie alle erforderlichen Änderungen vorgenommen und Ihre Website für den Launch vorbereitet haben, müssen Sie:
   1. oben rechts im Site Builder auf Veröffentlichen klicken.
   2. die Kontrollkästchen neben den zu veröffentlichenden Seiten aktivieren.
   3. auf Veröffentlichen klicken.

Sobald die Website veröffentlicht ist, werden die kostenlosen Artikel in einem gesonderten Bereich angezeigt. Wenn keine kostenlosen Artikel angezeigt werden, sollten Sie überprüfen, ob deren Status auf “Verfügbar” gesetzt ist und keine zeitliche Anzeigebeschränkung aktiv ist.

Informationen zu kostenlosen Artikeln über die API abrufen

Wenn Ihr Katalog über die API konfiguriert ist, 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:

• Befinden sich im Warenkorb des Nutzers sowohl kostenpflichtige als auch kostenlose Artikel, 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 über das Zahlungsportal ab.
• Befinden sich im Warenkorb des Nutzers nur kostenlose Artikel, müssen Sie den API-Aufruf Bestellung mit einem kostenlosen Warenkorb anlegen oder Bestellung mit einem bestimmten kostenlosen Warenkorb anlegen verwenden. Das Zahlungsportal kommt hierbei nicht zum Einsatz.

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

Objekt order 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 vergeben. Wir empfehlen, einen Webhook-Handler einzurichten, um Bestelldaten in Ihrem Backend zu empfangen. Die erforderlichen Daten sind im Webhook Erfolgreiche Bezahlung der Bestellung enthalten.

Weitere Informationen zu dieser und anderen Optionen zum Abruf von Kaufdaten finden Sie im Abschnitt Bestellstatus-Tracking einrichten.