In-Game Store / Виртуальные предметы
  На главную

In-Game Store

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Примечание

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

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

Пример ответа:
Copy
Full screen
Small screen

{
  "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
      },
}
Примечание

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

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

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

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

Вы можете указать период отображения товаров в магазине, чтобы:
  • поддерживать актуальность каталога в заданное время, например, во время праздничных распродаж;
  • создать товар заранее, не отображая его в каталоге;
  • мотивировать пользователей к покупке с помощью таймера, который может отображаться рядом с товаром.
Примечание
При создании интерфейса каталога с помощью Site Builder таймер будет отображаться автоматически. При создании каталога в собственном интерфейсе таймер необходимо реализовать самостоятельно.
Чтобы настроить ограничение времени отображения предмета через Личный кабинет, выберите пункт Период времени и укажите часовой пояс, начало и конец периода. Чтобы не указывать конец периода отображения бандла, установите флажок Без даты окончания.
Примечание
После создания виртуального предмета, виртуальной валюты или пакета виртуальной валюты вы можете задать статусы для товара, чтобы определить, будет ли он доступен, недоступен или частично доступен для покупки.
Чтобы настроить ограничение времени отображения предмета в магазине через методы API, передайте в методе Create virtual item или Update virtual item параметры:
  • 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 массив объектов с датами начала и конца всех периодов.

Пример:

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

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

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

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

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

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

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

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

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

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

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

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

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

    Подробная информация о работе с ключами API приведена в справочнике API.

    Основные рекомендации:

    • Сохраните созданный ключ API на вашей стороне. Вы можете посмотреть ключ API в Личном кабинете только один раз при его создании.
    • Никому не сообщайте ваш ключ API, так как он дает доступ к управлению аккаунтом и проектами в Личном кабинете.
    • Ключ API должен храниться на вашем сервере и никогда — в бинарных файлах или на фронтенде.

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

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

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

    Чтобы настроить региональные ограничения на виртуальные предметы, передайте в метод Create item или Update item массив объектов с ID регионов, в которых предмет будет доступен для продажи.
    Copy
    Full screen
    Small screen
    "regions": [{
         “id”: “123”
      }, {
         “id”: “456”
      }
    ]
    

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

    Copy
    Full screen
    Small screen
    "regional_prices": [{
         “region_id”: “123”,
         “country_iso”: “CHN”,
         “amount”: 40,
         “currency_iso”: “CNY”,
         “is_default”: true,
         “is_enabled”: true
      }
    ]
    
    Примечание
    Предварительно необходимо настроить регионы в проекте. Для этого обратитесь к персональному менеджеру проекта или напишите на csm@xsolla.com.
    Была ли статья полезна?
    Спасибо!
    Что может сделать страницу еще лучше? Сообщение
    Жаль, что так произошло
    Расскажите, почему статья не была полезна. Сообщение
    Спасибо за обратную связь!
    Ваши мысли и идеи помогут нам улучшить ваш пользовательский опыт.
    Оценить страницу
    Оценить страницу
    Что может сделать страницу еще лучше?

    В другой раз

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

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

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