Виртуальные предметы

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

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

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

• Настройка цен в реальной и виртуальной валюте.
• Настройка каталога с одним или несколькими уровнями вложенности.
• Автоматическое определение валюты и страны пользователя.
• Ограничение количества доступных для покупки предметов.
• Ограничение времени отображения предметов в магазине.
• Бесплатные товары.

Особенности настройки цен:

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

Ограничения настройки цен:

• Нельзя создать предмет с нулевой ценой.

Виртуальные предметы делятся на три типа:

• расходуемые
• нерасходуемые
• с ограниченным сроком действия

Расходуемые виртуальные предметы

Расходуемый предмет — это предмет в инвентаре, который можно накапливать и покупать многократно. После использования его количество уменьшается.

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

• Пополнение количества предметов в инвентаре.
• Хранение множества единиц предмета в инвентаре пользователя.
• Можно расходовать с клиента игры.

Пример: Гранаты, патроны и т. д.

Нерасходуемые виртуальные предметы

Нерасходуемый предмет — это предмет в инвентаре, который можно начислить или купить только один раз.

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

• Хранение предмета в инвентаре пользователя в единственном экземпляре.
• Нельзя расходовать с клиента игры, изымается из инвентаря только серверным методом.

Пример: Доступ к локациям, статусы персонажа, косметические улучшения, предустановленные DLC, опция для отключения рекламы в игре и т. д.

Предметы с ограниченным сроком действия

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

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

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

Пример: Battle Pass, Season Pass, временный доступ к скину, предмету или другой дополнительный контент, доступный на ограниченный период времени.

Подробная информация приведена в рецепте Предметы с ограниченным сроком действия.

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

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

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

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

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

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

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

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

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

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

{
  "items": [
    {
      "sku": "big_rocket",
      "name": "Big Rocket",
      "groups": [
        {
          "external_id": "accessory",
          "name": "Accessory"
        }
      ],
      "attributes": [
        {
          "external_id": "stack_size",
          "name": "Stack size",
          "values": [
            {
              "external_id": "size_e3364991f92e751689a68b96598a5a5a84010b85",
              "value": "5"
            }
          ]
        }
      ],
      "type": "virtual_good",
      "description": "Big Rocket - description",
      "image_url": "https://popmedia.blob.core.windows.net/popyourself/male/outfit/male_armor_white_a-01.png",
      "is_free": false,
      "price": {
        "amount": "100.99",
        "amount_without_discount": "100.99",
        "currency": "USD"
      },
      "virtual_prices": [
        {
          "amount": 100,
          "sku": "vc_test",
          "is_default": true,
          "amount_without_discount": 100,
          "image_url": "http://image.png",
          "name": "SHOTGUN FOR TRUE RAIDERS",
          "type": "virtual_currency",
          "description": "description"
        }
      ],
      "can_be_bought": true,
      "inventory_options": {
        "consumable": {
          "usages_count": 1
        },
        "expiration_period": {
          "type": "day",
          "value": 1
        }
      },
      "virtual_item_type": "non_renewing_subscription",
      "limits": {
        "per_user": {
            "total": 5,
            "available": 5
        },
        "per_item": null
      },
}

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

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

• 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 virtual item или Update virtual item массив объектов с датами начала и конца всех периодов.

Пример:

"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 и хотят настроить новый тип товара — виртуальные предметы.

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

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

1. Настройте виртуальные предметы и их группы.
2. Настройте региональные ограничения и региональные цены.

Настройка виртуальных предметов и их групп

Для настройки виртуальных предметов необходимо настроить группы. Группы позволяют создавать многоуровневый каталог. Предметы, созданные без указания группы, попадают в отдельную группу Ungrouped.

Виртуальные предметы и их группы можно настроить одним из следующих способов:

• через Личный кабинет;
• через методы API.

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

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

Для использования методов требуется базовая аутентификация. Передайте в запросе параметр Authorization:Basic <your_authorization_basic_key>, где <your_authorization_basic_key> — пара ID продавца:ключ API, закодированная по стандарту Base64. Значения параметров вы можете найти в Личном кабинете:

• ID продавца указан:
  • В разделе Настройки компании > Компания.
  • Aдресной строке браузера на любой странице Личного кабинета. URL-адрес имеет вид https:​//publisher.xsolla.com/<merchant ID>/<Publisher Account section>.

• Ключ API отображается в Личном кабинете только при создании и должен храниться на вашей стороне. Создать ключ можно в разделах:
  • Настройки компании > Ключи API;
  • Настройки проекта > Ключи API.

Для получения каталога виртуальных предметов на клиенте используйте методы подраздела Catalog из группы методов Virtual Items & Currency. Для их использования авторизация не требуется.

Чтобы получить весь список предметов, независимо от их групп, используйте метод Get virtual items list. Чтобы получить список предметов определенной группы, передайте в метод Get items list by specified group параметр external_id.

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

"regions": [{
     “id”: “123”
  }, {
     “id”: “456”
  }
]

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

"regional_prices": [{
     “region_id”: “123”,
     “country_iso”: “CHN”,
     “amount”: 40,
     “currency_iso”: “CNY”,
     “is_default”: true,
     “is_enabled”: true
  }
]