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 In-Game-Artikeln – virtuelle Gegenstände, virtuelle Währungspakete und Bundles
• Verkauf von Spielen und DLCs über Spielschlüssel

Anwendungsfälle:

• Kostenlose Artikel zu Projektmeilensteinen oder besonderen Daten, z. B. einem Jubiläum, als Belohnung für die Treue der Nutzer.
• Kostenlose Add-ons für Nutzer, die das Basisspiel bereits gekauft haben, als Treuebelohnung.
• 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 sowohl für autorisierte Nutzer als auch für nicht autorisierte Nutzer verfügbar. Begrenzungen dahingehend, wie viele kostenlose Artikel man erhalten darf, können nur für autorisierte Nutzer konfiguriert werden.

Kostenlose Artikel einrichten

2. Wählen Sie Create manually aus und danach in der Drop-down-Liste Virtual item.

3. Geben Sie im Abschnitt General settings Folgendes an:
   • SKU
   • eine oder mehrere Gruppen, zu denen der Artikel gehören soll (optional)
   • Name
   • Kurzbeschreibung
   • erweiterte Beschreibung – zum Hinzufügen aktivieren Sie den entsprechenden Schalter (optional)

4. Laden Sie im Abschnitt Media optional ein oder mehrere Bilder oder Videos hoch – von Ihrem Gerät oder über einen Link. Im mit dem Xsolla Site Editor erstellten Shop zeigen alle Artikelkarten die Datei mit der Markierung Main an, während die übrigen Dateien nur in Artikelkarten mit Mediengalerie verfügbar sind. Die als Main markierte Datei wird außerdem in den Antworten der API-Aufrufe zur Katalogabfrage zurückgegeben.

5. Wählen Sie unter Price settings die Option Free item aus.

6. Um die Anzahl der zum Kauf verfügbaren Artikel zu begrenzen:
   1. Aktivieren Sie den Schalter im Abschnitt Limits und geben Sie die Menge an.
   2. Konfigurieren Sie die Häufigkeit des Limit-Resets. Wählen Sie dazu einen Zeitraum aus der Drop-down-Liste aus:
      1. Daily.
      2. Weekly.
      3. Monthly.
      4. Custom interval. Der Zeitraum wird ab dem Startdatum der Artikelanzeige im Shop berechnet.
      5. No regular refresh.
   3. Richten Sie den Reset-Zeitplan ein, indem Sie die zum gewählten Zeitraum passenden Parameter angeben.

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

   1. Aktivieren Sie den Schalter im Abschnitt Add specific display period.
   2. Geben Sie die Zeitzone sowie den Beginn und das Ende des Zeitraums an.

   Um das Ende des Anzeigezeitraums offen zu lassen, aktivieren Sie den Schalter No end date.

8. Konfigurieren Sie Attribute optional auf eine der folgenden Arten:
   1. Fügen Sie Attribute und ihre Werte im JSON-Format hinzu.
   2. Erstellen Sie Attribute und ihre Werte manuell und verknüpfen Sie sie mit Artikeln.

9. Klicken Sie auf Create.
10. Wählen Sie im sich öffnenden Fenster den Artikelstatus aus und klicken Sie auf Continue.

Der erstellte Artikel erscheint im Abschnitt All items.

Ü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 nach ID aktualisieren oder Spiel nach 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 die Anzahl kostenloser Artikel begrenzen möchten, die ein Nutzer erhalten kann, übergeben Sie in den Aufrufen zum Erstellen oder Aktualisieren des Artikels die folgenden Parameter:
  • limits mit der angegebenen Menge
  • limits.recurrent_schedule mit der angegebenen Zurücksetzungsfrequenz

Sie können außerdem die Anzeigezeitbegrenzung des Artikels im Shop konfigurieren und regionale Beschränkungen festlegen.

Kostenlose Artikel im Katalog anzeigen

Kostenlose Artikel werden im Katalog abhängig von der Implementierung angezeigt – über den Site Builder oder per API.

Anzeige über den Site Builder

So zeigen Sie kostenlose Artikel auf Ihrer Website an:

1. Kostenlose Artikel erstellen.

2. Gehen Sie in Ihrem Projekt im Kundenportal zum Abschnitt Storefronts > Websites.
3. Klicken Sie im Bereich der gewünschten Website auf Open Site Builder.

2. Gehen Sie im Projekt in Ihrem Konto für Handyspiele zum Abschnitt Web Shop.
3. Klicken Sie auf den Bereich der gewünschten Website.

4. Wenn Ihre Website mehrere Seiten umfasst, wählen Sie die benötigte aus:
   1. Klicken Sie oben im Builder auf den aktuellen Seitentitel.
   2. Wählen Sie die gewünschte Seite aus der Drop-down-Liste.
5. Wählen Sie im Store-Abschnitt im Item type-Feld den kostenlosen Artikeltyp aus und geben Sie ggf. seine Gruppe an.
6. Konfigurieren Sie das Layout der Artikelkarte.
7. Nachdem Sie alle erforderlichen Änderungen vorgenommen und Ihre Website für den Start vorbereitet haben:
   1. Klicken Sie oben rechts im Site Builder auf Publish.
   2. Aktivieren Sie die Kontrollkästchen neben den Seiten, die Sie veröffentlichen möchten.
   3. Klicken Sie auf Publish.

Nachdem die Website veröffentlicht wurde, wird ein Abschnitt mit kostenlosen Artikeln verfügbar. Wenn Artikel nicht angezeigt werden, prüfen Sie, ob ihr Status auf Available gesetzt ist und keine zeitbasierte Anzeigebegrenzung aktiv ist.

Informationen zu kostenlosen Artikeln per API abrufen

Wenn Ihr Katalog über die API konfiguriert ist, werden Daten zu kostenlosen Artikeln über die im Unterabschnitt Catalog verfügbaren Aufrufe zurückgegeben:

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

Kostenlose Artikel an Nutzer vergeben

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 Warenkorb kauft, verwenden Sie den API-Aufruf Bestellung mit angegebenem kostenlosen Artikel anlegen.

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, verwenden Sie die API-Aufrufe zur Bestellanlegung Bestellung mit allen Artikeln aus einem bestimmten Warenkorb anlegen oder Bestellung mit allen Artikeln aus dem aktuellen Warenkorb anlegen. In diesem Fall schließt der Nutzer die Zahlung über das Zahlungsportal ab.
• Befinden sich im Warenkorb des Nutzers nur kostenlose Artikel, verwenden Sie die API-Aufrufe Bestellung mit kostenlosem Warenkorb anlegen oder Bestellung mit einem bestimmten kostenlosen Warenkorb anlegen. In diesem Fall wird das Zahlungsportal nicht verwendet.

  In beiden Fällen sendet Xsolla den Webhook Successful payment for order mit den 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.

Beispiel eines order-Objekts für kostenlose Artikel:

 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ährung und Gegenstände automatisch dem PlayFab-Inventar des Nutzers gutgeschrieben.
• Wenn Sie ein benutzerdefiniertes Auslieferungssystem verwenden, vergeben Sie alle virtuellen Gegenstände und Währung auf Ihrer Seite. Wir empfehlen, einen Webhook-Handler einzurichten, um Bestelldaten in Ihrem Backend zu empfangen. Die erforderlichen Daten sind im Webhook Successful payment for order enthalten.

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