Бандлы

Как это работает

Бандл — комплект, состоящий из нескольких товаров, которые продаются как единое целое.

Основные возможности:

Распаковка бандла происходит автоматически после: 

Если в составе бандла содержится другой бандл, он распакуется на отдельные товары.

Способ доставки товаров из распакованного бандла зависит от типа товара:

Примечание
Если логика In-Game Store реализована на ваших серверах, вы можете настроить вебхук о покупке товаров. В вебхуке будет содержаться бандл и все предметы из его состава.

При возврате бандла, например, при отмене транзакции, у пользователя списываются все товары, которые были в его составе. Если какие-то из товаров на момент возврата уже потрачены игроком, спишется только доступный остаток.

Ограничения:

  • В состав бандла нельзя добавить:
    • этот же бандл;
    • физический товар.
  • Нельзя создать пустой бандл.
  • Продажа бандла будет приостановлена, если кончились свободные для продажи ключи из состава бандла.
  • Цена бандла должна быть задана только фиксированным значением в реальной и/или виртуальной валюте.
  • Региональные ограничения на бандл настраиваются только через методы API.

Ограничение количества доступных для покупки бандлов

Вы можете задать ограничения на покупку бандлов. Например, вы можете продавать:

  • ограниченное количество бандлов одному пользователю;
  • приветственные бандлы, которые доступны к покупке только один раз.

Если пользователь превысил заданное ограничение, бандл не будет отображаться в каталоге. Если в состав бандла входит предмет или пакет виртуальной валюты с ограничением на покупку и пользователь уже купил допустимое количество, бандл не будет отображаться в каталоге.

Вы можете отобразить в интерфейсе максимальное доступное количество бандлов и оставшееся количество бандлов, которое доступно пользователю.

Чтобы задать ограничение на покупку, при создании бандла в Личном кабинете установите переключатель Ограничивать покупку бандла пользователем в положение Вкл и укажите количество, доступное для покупки.

Вы можете получить информацию о бандлах, используя методы подраздела Catalog из группы методов Bundles.

В ответе, кроме информации о бандле, вы получите следующую информацию:

  • максимальное количество бандлов, которое может купить пользователь;
  • оставшееся количество бандлов, доступное пользователю для покупки.

Подробнее о том, как настроить или обновить ограничения, вы можете прочитать в инструкции Ограничения для пользователя.

Примечание

Для неавторизованного пользователя всегда отображается максимальное количество бандлов, которое он может купить. Чтобы отобразить пользователю оставшееся количество бандлов с учетом действующего ограничения, необходимо передавать данные авторизации пользователей на этапе запроса каталога бандлов с использованием методов подраздела Catalog из группы методов Bundles.

Для корректного отображения количества бандлов, которое доступно пользователю, необходимо настроить аутентификацию.

Пример ответа:
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
           },
          }
        }
      ]
    }
  ]
}
Примечание

Xsolla контролирует соблюдение ограничений и не позволяет пользователям приобрести количество бандлов, которое превышает заданное ограничение.

При открытии платежного интерфейса и оплате бандла все неоплаченные заказы с этим бандлом становятся недействительными.

Пример: пользователь может открыть форму оплаты бандла с ограничением на покупку в нескольких вкладках браузера, пока бандл не был куплен. Это автоматически приводит к созданию нескольких заказов на один бандл. После покупки бандла на одной вкладке Xsolla аннулирует все неоплаченные заказы с бандлом.

Ограничение времени отображения бандлов в магазине

Вы можете указать период отображения товаров в магазине, чтобы:
  • поддерживать актуальность каталога в заданное время, например, во время праздничных распродаж;
  • создать бандл заранее, не отображая его в каталоге;
  • мотивировать пользователей к покупке с помощью таймера, который может отображаться рядом с бандлом.
Примечание
При создании интерфейса каталога с помощью Site Builder таймер будет отображаться автоматически. При создании каталога в собственном интерфейсе таймер необходимо реализовать самостоятельно.

Чтобы настроить ограничение времени отображения бандлов через Личный кабинет, выберите пункт Период времени и укажите часовой пояс, начало и конец периода. Чтобы не указывать конец периода отображения бандла, установите флажок Без даты окончания.

Чтобы настроить ограничение времени отображения бандла в магазине через методы API, передайте в методе Create bundle или Update bundle параметры:

  • periods[0].date_from с данными о дате и времени начала периода отображения валюты в формате YYYY-MM-DDThh:mm:ss±TMZ, где TMZ — указатель часового пояса в формате hh:mm GMT;
  • periods[0].date_until с данными о дате и времени конца периода отображения валюты в формате YYYY-MM-DDThh:mm:ss±TMZ, где TMZ — указатель часового пояса в формате hh:mm GMT. Чтобы не указывать конец периода отображения валюты, передайте значение null.

Вы можете настроить несколько периодов отображения бандла в магазине. Для этого передайте в методе Create bundle или Update bundle массив объектов с датами начала и конца всех периодов.

Пример:

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"
          }
    ]
    

    Для кого подходит

    Для партнеров, которые хотят продавать наборы товаров по цене ниже стоимости его содержимого, что способствует увеличению продаж и привлечению игроков, и у которых подключен один из следующих продуктов (или оба):

    • In-Game Store с настроенными модулями Виртуальная валюта или Виртуальные товары.
    • Buy Button с настроенным модулем Игровые ключи.

    Как настроить

    Сценарий интеграции

    1. Настройте бандл.
    2. Реализуйте получение бандлов в каталоге.

    Настройка бандла

    Настройте бандлы одним из следующих способов:

    Настройка через Личный кабинет

    1. В разделе Store > Бандлы в Личном кабинете нажмите кнопку Создать бандл.
    2. Настройте бандл:
      1. Загрузите изображение.
      2. Укажите название.
      3. Укажите описание.
      4. Настройте содержимое.
      5. Настройте стоимость.
      6. Настройте отображение в магазине.
    3. Проверьте настройки и нажмите кнопку Сохранить.

    Настройка через методы API

    Для настройки бандлов используются методы подраздела Admin из группы методов Bundles.
    Внимание
    Методы из подраздела Admin не предназначены для построения каталога в магазине на клиенте. Они не должны использоваться на лендингах, в веб-магазинах и внутриигровой логике.

    Добавление в бандл игрового ключа

    Чтобы добавить в бандл игровой ключ для выбранной платформы, передайте в метод Create bundle или Update bundle массив объектов с артикулами нужных платформ.

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

    Настройка региональных ограничений

    Чтобы настроить региональные ограничения на бандл, передайте в метод Create bundle или Update bundle массив объектов с ID регионов, в которых бандл будет доступен для продажи.

    Примечание
    Предварительно необходимо настроить регионы в проекте через методы API или запрос к персональному менеджеру проекта.
    Copy
    Full screen
    Small screen
    "regions": [{
         “id”: “123”
      }, {
         “id”: “456”
      }
    ]
    

    Настройка региональных цен

    Чтобы настроить региональные цены на бандл, передайте в метод Create bundle или Update bundle массив объектов с настройками цен для регионов.

    Примечание
    Предварительно необходимо настроить регионы в проекте через методы API или запрос к персональному менеджеру проекта.
    Copy
    Full screen
    Small screen
    "regional_prices": [{
         “region_id”: “123”,
         “country_iso”: “CHN”,
         “amount”: 40,
         “currency_iso”: “CNY”,
         “is_default”: true,
         “is_enabled”: true
      }
    ]
    

    Получение бандлов в каталоге

    Для получения каталога бандлов используются методы подраздела Catalog из группы методов Bundles.
    Примечание
    Методы из подраздела Catalog предназначены для построения каталога в магазине на клиенте. Для их использования авторизация не требуется.
    Была ли статья полезна?
    Спасибо!
    Что может сделать страницу еще лучше? Сообщение
    Жаль, что так произошло
    Расскажите, почему статья не была полезна. Сообщение
    Спасибо за обратную связь!
    Ваши мысли и идеи помогут нам улучшить ваш пользовательский опыт.
    Оценить страницу
    Оценить страницу
    Что может сделать страницу еще лучше?

    В другой раз

    Спасибо за обратную связь!
    Последнее обновление: 10 октября 2023

    Нашли опечатку или ошибку в тексте? Выделите ее и нажмите Ctrl+Enter.

    Сообщите о проблеме
    Мы постоянно улучшаем качество нашей документации. Ваш отзыв поможет нам в этом.
    Укажите email-адрес, чтобы мы могли связаться с вами
    Спасибо за обратную связь!