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

Общая информация

Виртуальные предметы — это внутриигровые товары, которые пользователь может приобрести за реальную или виртуальную валюту или получить в качестве бонуса. Эти товары не имеют физического выражения и используются исключительно внутри игры. Примеры виртуальных предметов: скины, зелья, оружие, ключи и другие элементы, влияющие на игровой процесс или внешний вид персонажа.

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

• Гибкая настройка цен:
  • Возможность указать для одного предмета цену и в реальной, и в виртуальной валюте.
  • Возможность указать для одного предмета цены в нескольких реальных и виртуальных валютах. В этом случае необходимо указать валюту по умолчанию для каждого типа: одну — среди реальных, одну — среди виртуальных.
  • Создание бесплатных предметов.
  • Настройка региональных цен.
• Автоматическое определение валюты и страны пользователя.
• Настройка доступности:
  • Ограничение продажи предметов в различных регионах.
  • Ограничение количества доступных для покупки предметов.
  • Ограничение времени отображения предметов в магазине.
  • Настройка предметов недоступных для покупки. Предмет может быть скрыт из каталога, но при этом доступен для получения в составе бандла или в качестве бонуса к другому товару.
• Организация каталога:
  • Создание групп.
  • Сортировка предметов в каталоге.

Настройка в Личном кабинете

Создание группы

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

Чтобы создать группу:

1. В проекте в Личном кабинете перейдите в раздел Store > Виртуальные предметы.
2. Нажмите + и в раскрывающемся списке выберите Создать группу.

3. Задайте необходимые параметры:
   • External ID — уникальный ID группы.
   • Название группы.
4. Чтобы группа была сразу доступна в магазине, установите переключатель Показывать группу в магазине в положение Вкл. В этом случае группа создастся со статусом Включена. Вы сможете изменить статус группы позже.
5. Нажмите Создать группу.

Примечание

Если группа имеет статус Выключена, такая группа:

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

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

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

Чтобы включить уже созданную группу в состав другой группы:

1. В проекте в Личном кабинете перейдите в раздел Store > Виртуальные предметы.
2. Выберите группу, которую вы хотите включить в состав ранее созданной группы.
3. Нажмите значок ••• и выберите пункт Редактировать группу.
4. В раскрывающемся списке Путь к каталогу выберите группу, в состав которой вы хотите включить текущую группу.

5. Нажмите Сохранить изменения.

Создание виртуального предмета

Чтобы создать виртуальный предмет:

1. В проекте в Личном кабинете перейдите в раздел Store > Виртуальные предметы.
2. Нажмите + и в раскрывающемся списке выберите Создать предмет.

3. Определите доступность виртуального предмета в каталоге. Для этого выберите один из статусов:
   • Недоступен (по умолчанию) — предмет недоступен для покупки в каталоге, не может быть добавлен в состав бандла или указан как бонус при покупке другого товара.
   • Доступен — предмет доступен для покупки в каталоге, может быть добавлен в состав бандла или указан как бонус при покупке другого товара.
   • Частично доступен — предмет скрыт из каталога, но доступен при покупке бандла или другого товара, в котором он указан как бонус.
   Позже вы сможете изменить статус предмета.

4. Задайте базовые настройки, укажите:
   • изображение (опционально);
   • артикул;
   • одну или несколько групп, которым должен принадлежать предмет;
   • название предмета;
   • описание предмета (опционально).

5. Оставьте свойство предмета по умолчанию — Расходуемый (рекомендуется).

6. Настройте цены для виртуального предмета:
   • Чтобы создать бесплатный виртуальный предмет, в поле Платно или бесплатно выберите Бесплатный предмет.
   • Чтобы создать платный виртуальный предмет, в поле Платно или бесплатно выберите Платный предмет, укажите цену в одной или нескольких валютах.
   • Задайте региональные цены (опционально).

7. Задайте ограничение количества доступных для покупки предметов (опционально). Для этого:
   1. Установите переключатель Ограничивать покупку предметов пользователем в положение Вкл и и укажите количество, доступное для покупки пользователем.
   2. Настройте частоту обновления ограничений:
      1. Если вы не хотите обновлять ограничения — выберите в раскрывающемся списке пункт Без регулярного обновления.
      2. Если вы хотите, чтобы ограничения регулярно обновлялись — выберите в раскрывающемся списке частоту обновления и задайте, когда должно происходить обновление ограничения.
8. Задайте ограничение времени отображения товаров в магазине (опционально). Для этого в поле Показать предмет в магазине выберите Период времени и укажите часовой пояс, начало и конец периода. Чтобы не указывать конец периода отображения предмета, установите флажок Без даты окончания.
9. Добавьте дополнительные атрибуты (опционально).
10. Нажмите Создать предмет.

API для работы с виртуальными предметами

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

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

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

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

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

Чтобы получить весь список предметов, независимо от их групп, используйте метод Получение списка виртуальных предметов. Чтобы получить список предметов определенной группы, передайте в метод Получение списка товаров по указанной группе параметр external_id.

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

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

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

Примеры использования:

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

Настроить ограничение на покупку можно следующими способами:

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

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

Если при запросе каталога (используя методы API подраздела Catalog из группы методов Виртуальные предметы и валюта) в заголовке передан авторизационный токен пользователя, Xsolla рассчитывает, сколько экземпляров каждого товара еще может приобрести именно этот пользователь. В ответе для товаров с ограничениями возвращается объект limits, содержащий максимально допустимое количество товаров для покупки (параметр total) и оставшееся количество предметов, доступное для покупки конкретным пользователем (параметр available). Эти значения можно использовать для отображения информации в интерфейсе.

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

Пример ответа с товарами с настроенными ограничениями:

 1{
 2  "items": [
 3    {
 4      "sku": "big_rocket",
 5      "name": "Big Rocket",
 6      "groups": [
 7        {
 8          "external_id": "accessory",
 9          "name": "Accessory"
10        }
11      ],
12      "attributes": [
13        {
14          "external_id": "stack_size",
15          "name": "Stack size",
16          "values": [
17            {
18              "external_id": "size_e3364991f92e751689a68b96598a5a5a84010b85",
19              "value": "5"
20            }
21          ]
22        }
23      ],
24      "type": "virtual_good",
25      "description": "Big Rocket - description",
26      "image_url": "https://popmedia.blob.core.windows.net/popyourself/male/outfit/male_armor_white_a-01.png",
27      "is_free": false,
28      "price": {
29        "amount": "100.99",
30        "amount_without_discount": "100.99",
31        "currency": "USD"
32      },
33      "virtual_prices": [
34        {
35          "amount": 100,
36          "sku": "vc_test",
37          "is_default": true,
38          "amount_without_discount": 100,
39          "image_url": "http://image.png",
40          "name": "SHOTGUN FOR TRUE RAIDERS",
41          "type": "virtual_currency",
42          "description": "description"
43        }
44      ],
45      "can_be_bought": true,
46      "inventory_options": {
47        "consumable": {
48          "usages_count": 1
49        },
50        "expiration_period": {
51          "type": "day",
52          "value": 1
53        }
54      },
55      "virtual_item_type": "non_renewing_subscription",
56      "limits": {
57        "per_user": {
58            "total": 5,
59            "available": 5
60        },
61        "per_item": null
62      },
63}

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

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

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

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

Настроить ограничение времени отображения товара в магазине можно следующими способами:

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

С помощью методов API вы можете задать несколько периодов отображения. Для этого укажите массив объектов с датами начала и окончания всех периодов.

Пример массива periods:

 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]

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

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

Чтобы настроить региональные ограничения на продажу виртуальных предметов, при вызове методов API Создание виртуального предмета или Обновление виртуального предмета в теле запроса передайте массив объектов regions с ID регионов, в которых предмет будет доступен для продажи.

Пример массива regions:

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

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

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

Настроить ограничение на покупку можно следующими способами:

• Через Личный кабинет вручную: При создании или редактировании предмета в области Настройки цен установите переключатель Цены в реальной валюте в положение Вкл., нажмите Настроить цены. Вы можете указать цены вручную или рассчитать их автоматически на основе валют и налогов.
• При импорте цен в Личном кабинете из файла: В файле CSV вы можете добавить несколько строк с ценами для товара с указанием региона. Подробная информация о структуре файла и примеры заполнения приведены в разделе Региональные цены.

 1SKU,Currency,Amount,Country,IsDefault,Platform
 2game-key-1,EUR,9.09,,1,steam
 3game-key-1,EUR,9.2,DE,0,steam
 4game-key-1,EUR,8.09,IT,0,steam
 5game-key-1,USD,10.1,US,0,steam
 6game-key-1,MYR,47,MY,0,steam
 7game-key-2,EUR,2.09,,1,steam
 8game-key-2,EUR,2.2,DE,0,steam
 9game-key-2,EUR,1.79,IT,0,steam
10game-key-2,USD,2.3,US,0,steam
11game-key-2,MYR,24,MY,0,steam

• Через API: При  создании или редактировании предмета передайте в теле запроса массив prices с настройками цен для регионов.

 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    ]

Полезные ссылки