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

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

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

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

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

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

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

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

Настройка системы вознаграждений

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

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

Для создания товаров вручную в проекте в Личном кабинете перейдите в раздел Каталог товаров > Все товары. Подробная информация об этом и других способах создания товаров приведена в разделе документации Каталог товаров.

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

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

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

4. Нажмите Добавить строку, чтобы добавить нужное количество товаров.
5. Нажмите Создать призовые баллы.

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

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

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

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

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

9. После того как вы добавили нужное количество шагов, нажмите Далее.

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

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

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

16. Нажмите Создать.

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

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

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

Отображение системы вознаграждений

Отображение через конструктор сайтов

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

Чтобы цепочки наград отобразились на вашем сайте:

1. В проекте в Личном кабинете перейдите в раздел Каналы продаж > Веб-сайты.
2. Выберите ваш сайт и нажмите Открыть Site Builder.
3. В основной части конструктора выберите место, где вы хотите добавить новый блок и нажмите Добавить блок.
4. Выберите блок Система наград.
5. В раскрывающемся списке выберите цепочку наград.

6. При необходимости настройте цвет кнопок и текста.
7. Для проверки цепочки в правом верхнем углу конструктора нажмите Просмотр.

8. Чтобы изменения вступили в силу, опубликуйте сайт:
   1. В правом верхнем углу конструктора сайтов нажмите Опубликовать.
   2. Установите флажки напротив страниц, которые вы хотите опубликовать.
   3. Нажмите Опубликовать.

Особенности отображения призовых баллов через конструктор сайтов

Вы можете выбрать несколько цепочек наград в одном блоке и выбрать способ их отображения: друг под другом или на вкладках. Вы можете настроить отдельно внешний вид для каждой цепочки.

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

Пример:

У вас настроены 2 цепочки наград: индивидуальная и клановая. У первой цепочки призовой балл с названием Crystal, у второй — Magic Bubble.

В каталоге товаров есть товар Sword с призовыми баллами: при покупке этого товара участнику клана будет начислено 20 Crystals и 40 Magic Bubbles.

Когда вы добавляете блок Магазин в конструкторе и выбираете тип и группу товаров, в которой есть товар Sword:

1. Если вы не добавили цепочку наград на сайт, призовые баллы у товара Sword не будут отображаться.
2. Если вы добавили на сайт только индивидуальную цепочку наград и она активна, то у товара Sword отображается только 20 Crystals.
3. Если вы добавили на сайт только клановую цепочку наград и она активна, то у товара Sword отображается только 40 Magic Bubbles.
4. Если вы добавили на сайт обе цепочки наград — индивидуальную и клановую, то у товара Sword отображается и 20 Crystals, и 40 Magic Bubbles.

Для участников клана 40 Magic Bubbles будет отображаться как активное значение.

Для пользователей без клана 40 Magic Bubbles будет отображаться как заблокированное значение.

Отображение цепочек наград через API

1. В интерфейсе приложения реализуйте элементы для отображения шагов цепочки наград.
2. Реализуйте логику работы с цепочками с помощью следующих клиентских методов API из группы методов Цепочки наград и призовые баллы:

3. Убедитесь, что товары корректно начисляются пользователю.

Настройка клана пользователя

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

1. Настройте схему атрибутов в Xsolla Login.

 1{
 2	"$schema": "https://json-schema.org/draft/2020-12/schema",
 3	"additionalProperties": false,
 4	"description": "JSON Schema example for user attributes. Not the actual schema.",
 5	"properties": {
 6
 7		"clan_id": {
 8			"description": "name of clan",
 9			"type": "string"
10		},
11		"custom-id": {
12			"description": "custom-id of a user.",
13			"type": "number"
14		},
15		"had_ban": {
16			"description": "Whether the user was banned.",
17			"type": "boolean"
18		},
19		"last_purchase": {
20			"description": "Date of user's last purchase.",
21			"type": "string"
22		},
23	},
24	"required": [],
25	"title": "Example",
26	"type": "object"
27}

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

 1{
 2  "user": {
 3    "id": "1234567890",
 4    "picture": "https://example.com",
 5    "name": "test-name"
 6  },
 7  "attributes": [
 8    {
 9     "key": "clan_id",
10     "value": "beetles"
11    }
12  ]
13}

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

Особенности настройки для Web Shop

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

Если на сайте используется авторизация по ID пользователя, передайте данные о клане пользователя в ответе на вебхук Проверка пользователя в Web Shop при авторизации:

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

Пример ответа на вебхук:

 1{
 2  "user": {
 3    "id": "1234567890",
 4    "picture": "https://example.com",
 5    "name": "test-name"
 6  },
 7  "attributes": [
 8    {
 9     "key": "clan_id",
10     "value": "beetles"
11    }
12  ]
13}

• Если пользователь покинул клан и не вступил в другой, передайте значение clan_id в поле removing_keys.

Пример ответа на вебхук:

 1{
 2  "user": {
 3    "id": "1234567890",
 4    "picture": "https://example.com",
 5    "name": "test-name"
 6  },
 7  "removing_keys": [
 8    {
 9      "key": "clan_id"
10    }
11  ]
12}

Особенности настройки для API

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