Bundles

So funktioniert's

Ein Bundle enthält mehrere Artikel, die als Gesamtpaket verkauft werden.

Hauptmerkmale:

Ein Bundle wird automatisch nach einem erfolgreichen Kauf entpackt. Wenn ein Bundle ein anderes Bundle enthält, wird das eingebundene Bundle automatisch in eigenständige Artikel zerlegt.

Die Bereitstellungsmethode für das Entpacken eines Bundles hängt vom Artikeltyp ab:

  • virtuelle Währungspakete, virtuelle Gegenstände, zeitlich begrenzte Artikel und Bundles werden wie folgt bereitgestellt:
  • Spielschlüssel werden wie folgt bereitgestellt:

Hinweis
Wenn Sie die Logiken des In-Game Stores auf Ihren Servern implementiert haben, können Sie Webhooks für den Artikelkauf einrichten. Der Webhook enthält ein Bundle und dessen gesamten Inhalt.

Wenn der Käufer das Paket zurückgibt, indem er z. B. eine Transaktion storniert, werden ihm automatisch alle aus dem Bundle gewährten Artikel entzogen. Wenn der Käufer einige der Artikel bereits genutzt hat, werden ihm die restlichen Artikel trotzdem entzogen.

Einschränkungen:

  • Folgende Artikel können einem Bundle nicht hinzugefügt werden:
    • dasselbe Bundle
    • physische Waren
  • Es kann kein leeres Bundle erstellt werden.
  • Der Verkauf des Bundles wird pausiert, wenn die darin enthaltenen Schlüssel aufgebraucht sind.
  • Das Bundle sollte gegen Echtgeld und/oder virtuelle Währung sowie zu einem Festpreis angeboten werden.
  • Sie können regionale Beschränkungen für ein Bundle nur über die API konfigurieren.

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

Der Bundle-Kauf lässt sich beschränken. Sie können beispielsweise:

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

Erreicht der Benutzer das festgelegte Limit, wird ihm das Bundle nicht mehr im Katalog angezeigt. Wenn das Bundle ein virtuelles Währungspaket oder einen virtuellen Gegenstand mit einem Kauflimit enthält und der Benutzer die zulässige Menge bereits gekauft hat, wird das Bundle nicht im Katalog angezeigt.

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

Um beim Erstellen eines Bundles im Kundenportal ein Kauflimit festzulegen, müssen Sie den Schalter Anzahl der Bundle-Käufe pro Benutzer beschränken auf Ein stellen und festlegen, wie oft das Bundle gekauft werden darf.

Sie können die Methoden der Untergruppe Katalog aus der Methodengruppe Bundles nutzen, um Informationen über Bundles abzurufen.

In der Antwort sind neben den Informationen über das Bundle die folgenden Daten enthalten:

  • wie viele Bundles ein Benutzer maximal kaufen kann
  • die verbleibende Anzahl der Bundles, 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 Bundles sie maximal kaufen können. Um dem Benutzer die verbleibende Anzahl der Bundles (vorbehaltlich des aktuellen Limits) anzuzeigen, müssen Sie den Bundles-Katalog mithilfe der Methoden des Unterabschnitts Katalog aus der Methodengruppe Bundles anfordern und dabei die Benutzerautorisierungsdaten übermitteln.

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

Antwort mit Benutzerattributen (Beispiele):
Copy
Full screen
Small screen

{
  "items": [
    {
      "sku": "kg_1",
      "name": "kg_10.00_bundle",
      "type": "bundle",
      "description": "pricePoint_44056_1",
      "image_url": null,
      "long_description": null,
      "attributes": {
        "external_id": "genre",
        "name": "Genre",
        "values": [
          {
            "external_id": "genre_e3364991f92e751689a68b96598a5a5a84010b85",
            "value": "Casual"
          },
          {
            "external_id": "genre_eba07bfd0f982940773cba3744d97264dd58acd7",
            "value": "Strategy"
          },
          {
            "external_id": "genre_b8d0c6d8f0524c2b2d79ebb93aa3cd0e8b5199a8",
            "value": "Mobile"
          }
        ]
      },
      "is_free": false,
      "order": 999,
      "groups": [],
      "price": {
        "amount": 9.99,
        "currency": "USD",
        "amount_without_discount": 9.99
      },
      "total_content_price": {
        "amount": 10.99,
        "currency": "USD",
        "amount_without_discount": 10.99
      },
      "media_list": [],
      "virtual_prices": [],
      "can_be_bought": true,
      "bundle_type": "standard",
      "limits": {
        "$ref": "./Catalog_item_limits.yaml"
      },
      "content": [
        {
          "sku": "big_rocket",
          "name": "Big Rocket",
          "description": "Big Rocket - short description.",
          "image_url": "https://popmedia.blob.core.windows.net/popyourself/male/outfit/male_armor_white_a-01.png",
          "type": "virtual_currency",
          "quantity": 100,
          "virtual_item_type": "non_consumable",
          "attributes": {
            "external_id": "size",
            "name": "Size",
            "values": [
              {
                "external_id": "size_e3364991f92e751689a68b96598a5a5a84010b85",
                "value": "Large"
              }
            ]
          },
          "is_free": false,
          "groups": [],
          "price": {
            "amount": 10.99,
            "currency": "USD",
            "amount_without_discount": 10.99
          },
          "virtual_prices": [],
          "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 Bundles als erlaubt kaufen.

Öffnet ein Benutzer das Zahlungsportal und bezahlt ein Bundle, verfallen alle unbezahlten Bestellungen, die dieses Bundle enthalten.

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

Anzeigedauer für Bundles im Shop begrenzen

Sie können den Anzeigezeitraum für einen Artikel im Shop festlegen und dadurch:
  • den Katalog je nach Zeitraum relevanter gestalten, z. B. während der Weihnachtsfeiertage
  • ein Bundle im Voraus erstellen, ohne es im Katalog anzuzeigen
  • Benutzer zum Kauf motivieren, indem man einen Timer neben dem Bundle 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 Bundle im Shop angezeigt wird. Wählen sie dazu die Option Zeitraum, und legen Sie die Zeitzone sowie das Start- und das Enddatum fest. Wenn Sie kein Enddatum für den Anzeigezeitraum des Bundles festlegen möchten, setzen Sie ein Häkchen bei Kein Enddatum.

Um die Anzeigedauer eines Bundles im Shop über die API zu begrenzen, übermitteln Sie die folgenden Parameter im API-Aufruf Create bundle oder Update bundle:

  • periods[0].date_from mitsamt dem Startdatum und der Startuhrzeit des Artikelanzeigezeitraums 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 Artikelanzeigezeitraums 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 Artikels festlegen möchten, übermitteln Sie null.

Sie können mehrere Zeiträume für die Anzeige eines Bundles im Shop festlegen. Übermitteln Sie dazu in der Methode Create bundle oder Update bundle 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 ein Set von Artikeln zu einem günstigeren Preis anbieten möchten, als die Gesamtsumme aller im Bundle enthalten Artikel (um so den Umsatz anzukurbeln und neue Spieler zu gewinnen).

    Wie komme ich dazu

    Integrationsablauf

    1. Richten Sie ein Bundle ein.
    2. Implementieren Sie den Abruf von in Katalogen befindlichen Bundles.

    Bundle einrichten

    Richten Sie Bundles auf eine der folgenden Arten ein:

    Über Kundenportal einrichten

    1. Navigieren Sie im Kundenportal zu Online-Shop > Bundles, und klicken Sie auf Bundle erstellen.
    2. Legen Sie die folgenden Parameter für das Bundle fest:
      1. Bild
      2. Name
      3. Beschreibung
      4. Inhalte
      5. Preis
      6. Im Online-Shop anzeigen
    3. Prüfen Sie die Einstellungen, und klicken Sie auf Speichern.

    Über API-Methoden einrichten

    Sie können die Methoden aus der Untergruppe Admin der Methodengruppe Bundles nutzen, um Bundles 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.

    Spielschlüssel einem Bundle hinzufügen

    Um einem Bundle einen Spielschlüssel für eine ausgewählte Plattform hinzuzufügen, übermitteln Sie ein Array mit SKUs der gewünschten Plattformen an die Methode Create bundle oder Update bundle.

    Copy
    Full screen
    Small screen
    
    "content": [{
         “sku”: “brilliant_game_sku_steam”,
         “quantity”: 1
      }
    ]
    

    Regionale Beschränkungen einrichten

    Um für ein Bundle regionale Beschränkungen einzurichten, übermitteln Sie ein Array der IDs der unterstützten Regionen an die Methode Create bundle oder Update bundle.

    Hinweis
    Richten Sie Regionen in einem Projekt über API-Methoden ein oder wenden Sie sich dazu an Ihren Customer Success Manager.
    Copy
    Full screen
    Small screen
    "regions": [{
         “id”: “123”
      }, {
         “id”: “456”
      }
    ]
    

    Regionale Preise festlegen

    Um für ein Bundle regionale Preise festzulegen, übermitteln Sie ein Array der Objekte mit den Preisen für die jeweiligen Regionen an die Methode Create bundle oder Update bundle.

    Hinweis
    Richten Sie Regionen in einem Projekt über API-Methoden ein oder wenden Sie sich dazu an Ihren Customer Success Manager.
    Copy
    Full screen
    Small screen
    "regional_prices": [{
         “region_id”: “123”,
         “country_iso”: “CHN”,
         “amount”: 40,
         “currency_iso”: “CNY”,
         “is_default”: true,
         “is_enabled”: true
      }
    ]
    

    In einem Katalog befindliche Bundles abrufen

    Sie können die Methoden aus der Untergruppe Catalog der Methodengruppe Bundles nutzen, um in einem Katalog vorhandene Bundles abzurufen.
    Hinweis
    Methoden aus der Untergruppe Catalog dienen dazu, einen Katalog im Front-End des Online-Shops zu erstellen. Die Methoden erfordern keine Autorisierung.
    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!