Kostenlose Artikel

So funktioniert's

Kostenlose Artikel sind ein Artikeltyp, den ein Benutzer erhalten kann, ohne virtuelle oder echte Währung ausgeben zu müssen. Zu solchen Artikeln zählen:

• virtuelle Gegenstände
• Bundles
• virtuelle Währungspakete

Nur autorisierte Benutzer können kostenlose Artikel erhalten. Nicht autorisierte Benutzer können nur den Katalog der kostenlosen Artikel einsehen.

Nutzungsbeispiel:

• An wichtigen Tagen können Sie kostenlose Artikel verschenken (z. B. am Gründungstag des Projekts), um treue Spieler zu belohnen.
• Sie können im Ingame-Shop kostenlose Starterpakete für das Spiel verschenken, um neue Nutzer für das Spiel zu gewinnen.

Sie können das kostenlose Verschenken von einzigartigen Artikeln einschränken, falls der Nutzer diese bereits besitzt.

Für wen ist es

• Für Partner, die den In-Game Store bereits integriert haben und einen neuen Produkttyp (kostenlose Artikel) einrichten möchten.
• Für Partner, die die Nutzerbindung erhöhen oder neue Spieler gewinnen möchten.

Integrationsablauf

1. Kostenlose Artikel lassen sich auf einen der folgenden Wege erstellen:
   • über das Kundenportal
   • über API-Aufrufe
2. Richten Sie den Online-Shop ein.
3. Rufen Sie den Status der Bestellung des Benutzers ab.

Über das Kundenportal erstellen

1. Öffnen Sie Ihr Projekt im Kundenportal.
2. Klicken Sie in der Seitenleiste auf Online-Shop.
3. Klicken Sie bei Virtuelle Gegenstände auf Konfigurieren.
4. Klicken Sie auf das +-Symbol, und wählen Sie Artikel anlegen aus der Drop-down-Liste aus.
5. Geben Sie Folgendes an:
   • Bild
   • SKU
   • Eine oder mehrere Gruppen, zu denen der Gegenstand gehören soll
   • Name
   • Beschreibung
   • Gegenstandseigenschaften: aufbrauchbar, nicht aufbrauchbar oder zeitlich begrenzter Artikel
6. Wählen Sie im Abschnitt Preiseinstellungen die Option Kostenloser Artikel.
7. Wenn Sie beschränken möchten, wie oft ein Benutzer diesen Artikel kaufen darf, stellen Sie den Schalter Anzahl der Käufe dieses Artikels pro Benutzer beschränken auf Ein, und legen Sie fest, wie oft der Artikel gekauft werden kann.
8. Damit der Artikel im Online-Shop angezeigt wird, müssen Sie den Schalter Gegenstand im Online-Shop aktivieren auf Ein stellen.
9. Klicken Sie auf Artikel anlegen.

Über API-Aufrufe erstellen

1. Verwenden Sie API-Aufrufe aus dem Unterabschnitt "Admin", um kostenlose Artikel zu erstellen:
   • Für virtuelle Gegenstände – Virtuellen Gegenstand erstellen
   • Für Währungspakete – Virtuelles Währungspaket erstellen
   • Für Bundles – Bundle erstellen
   Wenn Sie einen Artikel erstellen oder bearbeiten, müssen Sie is_free = true im Anfragerumpf übermitteln.
2. Wenn Sie beschränken möchten, wie oft ein bestimmter Benutzer einen Artikel kaufen darf, rufen Sie die Methode zum Erstellen oder Bearbeiten eines Artikels auf, und legen Sie den Wert im Parameter limits.per_user fest.

Online-Shop einrichten

Schnellkauf

{
  "method": "POST",
  "url": "https://mybestgame.com/xsolla/notification",
  "body": {
    "items": [
      {
        "sku": "gift_direct_game_reward-supercoin",
        "type": "virtual_currency",
        "is_pre_order": false,
        "quantity": 500,
        "amount": "0",
        "promotions": [

        ]
      },
      {
        "sku": "package-500_supercoin",
        "type": "bundle",
        "is_pre_order": false,
        "quantity": 1,
        "amount": "0",
        "promotions": [

        ]
      },
      {
        "sku": "xsolla-giveaway_offer_11_14_22",
        "type": "bundle",
        "is_pre_order": false,
        "quantity": 1,
        "amount": "0",
        "promotions": [

        ]
      }
    ],
    "notification_type": "order_paid",
    "order": {
      "id": 12345678,
      "mode": "default",
      "currency_type": "unknown",
      "currency": null,
      "amount": "0",
      "status": "paid",
      "platform": "xsolla",
      "comment": null,
      "invoice_id": null,
      "promotions": [

      ]
    },
    "user": {
      "external_id": "1234567812345678",
      "email": null
    }
  },
  "headers": {
    "Authorization": "Signature 3b840ccefea111dcdfd111db1fdc6df969a3ec11",
    "Accept": "application/json",
    "Content-Type": "application/json"
  },
  "type": "webhook_payment",
  "callback_parameters": {
    "order_id": 12345678
  }
}

• Senden Sie als Antwort den HTTP-Statuscode 200 oder 204, wenn Ihr Listener den Webhook korrekt akzeptiert und verarbeitet hat.
• Senden Sie bei einem Fehler den entsprechenden HTTP-Statuscode: 4xx.
Hinweis
In diesem Fall werden die Artikel dem Inventar des Spielers hinzugefügt und die Bestellung wird aufseiten von Xsolla als erfolgreich gekennzeichnet.
• Ihr Listener kann ebenso mit dem HTTP-Statuscode 5xx antworten, um auf temporäre Serverfehler hinzuweisen. In diesem Fall verwendet der Xsolla-Warndienst einen Wiederholungsmechanismus.

Warenkorbkauf

Bei Nutzung der Warenkorbfunktion:

• Sind im Warenkorb des Benutzers sowohl kostenpflichtige als auch kostenlose Artikel enthalten, rufen Sie die standardmäßigen API-Methoden Bestellung mit allen Artikeln aus einem bestimmten Warenkorb erstellen und Bestellung mit allen Artikeln aus dem aktuellen Warenkorb erstellen auf, um Bestellungen anzulegen. Der Benutzer bezahlt die Bestellung über die Zahlungsmaske der Pay Station.
• Sind im Warenkorb des Benutzers nur kostenlose Artikel enthalten, rufen Sie die API-Methoden Bestellung mit kostenlosem Warenkorb erstellen und Bestellung mit einem bestimmten kostenlosen Warenkorb erstellen auf, um einen kostenlosen Warenkorb zusammenzustellen. In diesem Fall wird das Zahlungsportal nicht verwendet.

Das Webhook-Beispiel ähnelt dem Beispiel für den Schnellkauf.