Система вознаграждений

Глоссарий

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

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

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

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

За каждый уровень в цепочке пользователь может получить от 1 до 10 наград, а клан — от 1 до 10 наград для каждого участника.

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

• виртуальные предметы;
• виртуальную валюту;
• пакеты виртуальной валюты;
• бандлы.

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

Сценарий пользователя

1. Пользователь переходит на сайт.
2. Пользователь видит каталог товаров, систему вознаграждений и то, сколько призовых баллов можно получить за покупку каждого товара.
3. Пользователь авторизуется на сайте.
4. Пользователь видит текущий прогресс в системе вознаграждений.
5. Пользователь совершает покупку и продвигается по цепочке наград.

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

Чтобы настроить систему вознаграждений, вам потребуется следующая информация:

• дата начала и дата окончания действия системы вознаграждений;

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

Примеры предоставления информации приведены ниже.

Цепочка наград:

Описание	Пример
Название	Осколок
Сопроводительный текст	Собирайте осколки, чтобы получать награды.
Артикул	ExampleSKU003
Изображение или его URL-адрес

На своей стороне реализуйте:

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

Для работы системы вознаграждений реализуйте вызов следующих методов API:

• Получение списка виртуальных предметов
• Получение цепочки наград текущего пользователя
• Получение призовых баллов текущего пользователя
• Получение награды на уровне
• Обновление клана текущего пользователя
• Получение 10 участников, внесших наибольший вклад в продвижение по клановой цепочке наград

Определение клана пользователя

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

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

Пример:

 1
 2{
 3"attributes": [
 4{
 5
 6"key": "clan_id",
 7"value": "beetles"
 8}
 9],
10"publisher_id": 000000,
11"publisher_project_id": 000000
12}

Вы можете передать актуальные значения атрибутов непосредственно при авторизации пользователя, если вы используете метод API Auth by custom ID.

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

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

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

Создание призовых баллов

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

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

3. Задайте необходимые параметры:
   • Добавьте изображение (опционально).
   • Введите уникальный артикул призового балла.
   • Если вы создаете клановые призовые баллы, укажите, что призовой балл будет использоваться для клановых наград.
   • Укажите название призовых баллов.

4. Нажмите Далее.
5. Выберите артикул товара и количество призовых баллов, которые пользователь получит за покупку этого товара.
6. Нажмите +, чтобы добавить нужное количество позиций.
7. Нажмите Сохранить.

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

Создание цепочки наград

Чтобы создать цепочку наград:

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

3. Выберите тип цепочки — Индивидуальная цепочка наград или Клановая цепочка наград.
4. Задайте необходимые параметры. Если вы выбрали индивидуальную цепочку наград:
   1. Укажите название цепочки наград.
   2. Введите описание.
   3. В раскрывающемся списке выберите призовые баллы.

Если вы выбрали клановую цепочку наград:
1. В раскрывающемся списке Тип клана выберите тип клана.
2. Задайте параметры клановой цепочки наград:
   1. Введите название цепочки.
   2. Введите описание.
   3. Введите название всплывающего заголовка цепочки наград.
   4. Введите текст всплывающей подсказки: что нужно сделать, чтобы получать награды для клана.
   5. Добавьте изображение (опционально).
   6. В раскрывающемся списке выберите призовые баллы.

5. Нажмите Далее.
6. Нажмите Добавить уровень.
7. Укажите следующую информацию для создания уровня и нажмите Сохранить:
   1. Название уровня.
   2. Количество призовых баллов, которые нужно набрать, чтобы получить награду.
   3. Товар и его количество в награде.
8. Нажмите Далее.

9. Если вы хотите сделать цепочку наград персонализированной: 

   1. Установите переключатель Персонализированная цепочка наград в активное положение.
   2. Выберите один из вариантов отображения цепочки и нажмите Далее:
      • Показывать цепочку определенным пользователям. Если опция установлена, цепочка отобразится только для авторизованных пользователей, которые соответствуют заданным условиям.
      • Показывать цепочку пользователям, которые не соответствуют условиям. Если опция установлена, цепочка отображается, только если для пользователя не найдено ни одной подходящей цепочки наград. Например, если пользователь не авторизован или его атрибуты не соответствуют ни одной персонализированной цепочке.
   3. Если вы выбрали отображение цепочки определенным пользователям:
      1. Нажмите Добавить условие и укажите условия персонализации:
         • Атрибут пользователя — характеристика пользователя, например страна или возраст. Атрибуты настраиваются в разделе Login.
         • Тип атрибута — формат значения атрибута: строка, число, дата.
         • Оператор сравнения — способ сравнить значение атрибута пользователя с заданным условием. Например, равно, больше, меньше, содержит.
         • Значение атрибута — конкретное значение для сравнения. Например, если атрибут пользователя – возраст, тип атрибута — число, оператор сравнения – больше, а значение атрибута – 18, цепочка отобразится только для пользователей старше 18 лет.
      2. Чтобы добавить еще одно условие для персонализации, нажмите Добавить условие.
   4. Нажмите Далее.

10. Создайте нужное количество уровней и нажмите Сохранить.

11. Нажмите Далее.
12. Укажите период действия цепочки наград.
13. Если вы хотите, чтобы цепочка наград перезапускалась в определенное время, установите переключатель Сделать цепочку наград автообновляемой в активное положение и укажите режим обновления.

12. Нажмите Сохранить.

1. В каталоге наград выберите цепочку.
2. Нажмите ••• и в раскрывающемся списке выберите Активировать.

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

Для управления работой системы вознаграждений реализуйте вызов методов подраздела Admin из группы методов Цепочки наград и призовые баллы:

1. Создайте призовые баллы, за которые будет предоставляться доступ к наградам в системе вознаграждений, с помощью метода API Создание призовых баллов.
2. Настройте призовые баллы с помощью метода API Настройка призовых баллов для товаров. Пользователи получат эти баллы после покупки товаров.

3. Создайте цепочки наград с помощью метода API Создание цепочек наград. Чтобы создать персонализированную цепочку наград, передайте условие для отображения цепочки в массиве attribute_conditions.

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

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

4. Включите систему вознаграждений с помощью метода API Переключение цепочки наград.

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