Bundles

So funktioniert's

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

Hauptmerkmale:

• Hinzufügen verschiedener Artikeltypen zu einem Bundle:
  • virtuelle Währung (einschließlich der plattformabhängigen Währung)
  • virtuelles Währungspaket
  • Spielschlüssel für vorab ausgewählte Plattformen
  • virtuelle Gegenstände, einschließlich zeitlich begrenzter Artikel
  • Bundles
• Legen Sie die Preise für das Bundle in echter und virtueller Währung fest. Sie können Preise in mehreren echten oder virtuellen Währungen festlegen. In diesem Falle müssen Sie eine Standardwährung festlegen.
• Kostenloses Bundle.
• Beschränkung der Anzahl der käuflich erhältlichen Bundles.
• Begrenzung der Anzeigedauer von Bundles im Shop.

• Virtuelle Währungen, virtuelle Gegenstände, zeitlich begrenzte Artikel und Bundles werden per PlayFab bereitgestellt, sofern die PlayFab-Integration aktiviert ist.
• Spielschüssel werden per E-Mail bereitgestellt.
• Alle Artikeltypen lassen sich auch über Ihr eigenes System bereitstellen, und zwar mithilfe von Daten aus dem Webhook Erfolgreiche Bezahlung der Bestellung. Diese Methode wird angewandt, wenn:
  • die PlayFab-Integration nicht verwendet wird.
  • Sie die Bereitstellung von Artikeln an Nutzer lieber auf Ihrem eigenen Server steuern möchten.

1. Wenn die Integration von Bundle-Inhalten nicht deaktiviert ist, werden beim Kauf alle im Bundle enthaltenen Elemente im Array items als Liste einzelner Artikel übermittelt. Enthält das Bundle ein weiteres Bundle, wird auch dessen Inhalt als einzelne Artikel übermittelt.

Wenn ein Bundle erstattet wurde, beispielsweise aufgrund einer Stornierung einer Transaktion, wird der Webhook Stornierung der Bestellung gesendet. Verwenden Sie die Webhook-Daten, um die gekauften Artikel vom Benutzerkonto entfernen.

Einschränkungen:

• Sie können dem Bundle dasselbe Bundle nicht hinzufügen.
• Es kann kein leeres Bundle erstellt werden.
• Der Verkauf des Bundles wird pausiert, wenn die darin enthaltenen Schlüssel aufgebraucht sind.

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.

 1{
 2  "items": [
 3    {
 4      "sku": "kg_1",
 5      "name": "kg_10.00_bundle",
 6      "type": "bundle",
 7      "description": "pricePoint_44056_1",
 8      "image_url": null,
 9      "long_description": null,
10      "attributes": {
11        "external_id": "genre",
12        "name": "Genre",
13        "values": [
14          {
15            "external_id": "genre_e3364991f92e751689a68b96598a5a5a84010b85",
16            "value": "Casual"
17          },
18          {
19            "external_id": "genre_eba07bfd0f982940773cba3744d97264dd58acd7",
20            "value": "Strategy"
21          },
22          {
23            "external_id": "genre_b8d0c6d8f0524c2b2d79ebb93aa3cd0e8b5199a8",
24            "value": "Mobile"
25          }
26        ]
27      },
28      "is_free": false,
29      "order": 999,
30      "groups": [],
31      "price": {
32        "amount": 9.99,
33        "currency": "USD",
34        "amount_without_discount": 9.99
35      },
36      "total_content_price": {
37        "amount": 10.99,
38        "currency": "USD",
39        "amount_without_discount": 10.99
40      },
41      "media_list": [],
42      "virtual_prices": [],
43      "can_be_bought": true,
44      "bundle_type": "standard",
45      "limits": {
46        "$ref": "./Catalog_item_limits.yaml"
47      },
48      "content": [
49        {
50          "sku": "big_rocket",
51          "name": "Big Rocket",
52          "description": "Big Rocket - short description.",
53          "image_url": "https://popmedia.blob.core.windows.net/popyourself/male/outfit/male_armor_white_a-01.png",
54          "type": "virtual_currency",
55          "quantity": 100,
56          "virtual_item_type": "non_consumable",
57          "attributes": {
58            "external_id": "size",
59            "name": "Size",
60            "values": [
61              {
62                "external_id": "size_e3364991f92e751689a68b96598a5a5a84010b85",
63                "value": "Large"
64              }
65            ]
66          },
67          "is_free": false,
68          "groups": [],
69          "price": {
70            "amount": 10.99,
71            "currency": "USD",
72            "amount_without_discount": 10.99
73          },
74          "virtual_prices": [],
75          "limits": {
76            "per_user": {
77              "total": 5,
78              "available": 5
79              },
80            "per_item": null
81           },
82          }
83        }
84      ]
85    }
86  ]
87}

Anzeigedauer für Bundles im Shop begrenzen

• 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

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 Bundle erstellen oder Bundle aktualisieren:

• periods[0].date_from mitsamt dem Startdatum und der Startuhrzeit des Artikelanzeigezeitraums im Format YYYY-MM-DDThh:mm:ss±TMZ, wobei TMZ die Zeitzonenangabe – bezogen auf GMT – 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 Bundle erstellen oder Bundle aktualisieren ein Objekt-Array mit dem jeweiligen Start- und Enddatum der Zeiträume.

Beispiel:

 1"periods": [
 2      {
 3        "date_from": "2022-06-10T14:00:00+03:00",
 4        "date_until": "2022-06-30T14:00:00+03:00"
 5      },
 6       {
 7        "date_from": "2022-07-10T14:00:00+03:00",
 8        "date_until": "2022-07-30T14:00:00+03:00"
 9      },
10       {
11        "date_from": "2022-08-10T14:00:00+03:00",
12        "date_until": "2022-08-30T14:00:00+03:00"
13      }
14]

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

• über das Kundenportal
• über API-Methoden

Über Kundenportal einrichten

1. Öffnen Sie Ihr Projekt im Kundenportal, und navigieren Sie zu Store > Bundles.
2. Klicken Sie auf +, und wählen Sie aus der Drop-down-Liste die Option Bundle erstellen aus.
3. Legen Sie Folgendes fest:
   • Bild (optional)
   • SKU
   • eine oder mehrere Gruppen, zu denen das Bundle gehören soll
   • Name
   • Beschreibung (optional)
   • Inhalte
4. Legen Sie den Bundle-Preis fest:
1. Legen Sie die Preise fest oder erstellen Sie ein kostenloses Bundle:
1. Wenn Sie ein kostenloses Bundle erstellen möchten, müssen Sie im Feld Kostenpflichtig oder kostenlos die Option Kostenloses Bundle auswählen.
2. Wenn Sie stattdessen einen Preis festlegen möchten, müssen Sie Im Feld Kostenpflichtig oder kostenlos die Option Kostenpflichtiges Bundle auswählen und den Preis in echter oder virtueller Währung angeben. Bei Bedarf können Sie regionale Preise festlegen.
2. Begrenzen Sie, wie oft ein Nutzer das Bundle kaufen darf (optional). Stellen Sie dazu den Schalter Anzahl der Bundle-Käufe pro Benutzer beschränken auf Ein, und legen Sie das Limit fest.
5. Klicken Sie auf Weiter .
6. Gehen Sie wie folgt vor, damit das Bundle im Shop angezeigt wird:
   • Ändern Sie den Status in Verfügbar.
   • Legen Sie einen Zeitraum fest, innerhalb dem das Bundle im Shop angezeigt wird (optional). Wählen Sie dazu die Option Zeitraum aus, und legen Sie die Zeitzone sowie das Start- und das Enddatum fest. Wenn Sie kein Enddatum angeben möchten, setzen Sie ein Häkchen bei Kein Enddatum.
7. Klicken Sie auf Weiter.
8. Überprüfen Sie die Einstellungen, und klicken Sie auf Speichern.

Über API-Methoden einrichten

Spielschlüssel einem Bundle hinzufügen

Um einem Bundle einen Spielschlüssel für eine ausgewählte Plattform hinzuzufügen, müssen Sie ein content-Array mit den SKUs der gewünschten Plattformen an die Methode Bundle erstellen oder Bundle aktualisieren übermitteln.

1"content": [{
2     “sku”: “brilliant_game_sku_steam”,
3     “quantity”: 1
4  }
5]

Regionale Beschränkungen einrichten

Um für ein Bundle regionale Beschränkungen einzurichten, müssen Sie ein Array der IDs der unterstützten regions an die Methode Bundle erstellen oder Bundle aktualisieren übermitteln.

1"regions": [{
2     “id”: “123”
3  }, {
4     “id”: “456”
5  }
6]

Regionale Preise festlegen

Um für ein Bundle regionale Preise festzulegen, müssen Sie ein prices-Array mit den Einstellungen für die jeweiligen Regionen an die Methode Bundle erstellen oder Bundle aktualisieren übermitteln.

 1"prices": [
 2      {
 3        "amount": 100,
 4        "currency": "USD",
 5        "is_enabled": true,
 6        "is_default": true
 7      },
 8      {
 9        "amount": 200,
10        "currency": "CZK",
11        "country_iso": "CZ",
12        "is_enabled": false,
13        "is_default": false
14      }
15    ]

In einem Katalog befindliche Bundles abrufen

Konfigurieren von Artikelinformationen in Webhooks

Sie können konfigurieren, welche Artikeldaten in den Webhooks Erfolgreiche Bezahlung der Bestellung und Stornierung der Bestellung über den Array items integriert sind.

Aktivierung der Integration zusätzlicher Parameter

Aktivieren Sie die Integration von zusätzlichen Parametern die Folgendes angeben:

• ob der Artikel kostenlos ist (is_free)
• ob der Artikel ein Bonus ist (is_bonus)
• ob der Artikel ein Teil eines Bundles ist (is_bundle_content)

Um diese Parameter zu erhalten, müssen Sie Ihre Webhooks auf die Version 2 mithilfe des API-Aufrufs Informationen zu Webhook-Einstellungen aktualisieren umschalten. In der Version 1 (Standard) sind diese Parameter nicht verfügbar.

Beispiel eines Arrays von Artikeln mit zusätzlichen Parametern:

 1
 2"items": [
 3      {
 4        "sku": "com.xsolla.item_new_1",
 5        "type": "bundle",
 6        "is_pre_order": false,
 7        "is_free": false,
 8        "is_bonus": false,
 9        "Is_bundle_content": false,
10        "quantity": 1,
11        "amount": "1000",
12        "promotions": []
13      },
14      {
15        "sku": "com.xsolla.gold_1",
16        "type": "virtual_currency",
17        "is_pre_order": false,
18        "is_free": false,
19        "is_bonus": false,
20        "is_bundle_content": true,
21        "quantity": 1500,
22        "amount": "[null]",
23        "promotions": []
24      }
25 ],

Deaktivierung der Integration von Bundle-Inhalten

Standardmäßig enthalten Webhooks alle Elemente aus dem Bundle als Liste einzelner Artikel. Sie können den Webhook so konfigurieren, dass er nur das Bundle selbst enthält, ohne dessen Inhalt aufzulisten.

In diesem Fall werden die im Bundle enthaltenen Artikel nicht im Array der items einbezogen. Im oben angezeigten Array wird der Artikel mit dem SKU-com.xsolla.gold_1, der Teil des Bundles ist, ausgeschlossen.

Beispiel eines Arrays von Artikeln, wenn Bundle-Inhalte deaktiviert sind:

 1
 2"items": [
 3      {
 4        "sku": "com.xsolla.item_new_1",
 5        "type": "bundle",
 6        "is_pre_order": false,
 7        "is_free": false,
 8        "is_bonus": false,
 9        "Is_bundle_content": false,
10        "quantity": 1,
11        "amount": "1000",
12        "promotions": []
13      }
14 ],

Um die Integration des Bundle-Contents zu deaktivieren, kontaktieren Sie Ihren Customer Success Manager oder senden Sie eine E-Mail an [email protected]