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

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

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

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

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

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

Призовые баллы

Прогресс пользователя в цепочке определяется призовыми баллами. Существует два типа баллов: индивидуальные и клановые — аналогично типам цепочек наград.

Если в нескольких цепочках используются одни и те же призовые баллы:

• Баланс баллов будет общим для всех цепочек, включая новые.
• Во вновь созданной цепочке пользователь сохранит уже накопленные баллы.
• При сбросе цепочки баланс баллов обнуляется во всех цепочках, где используются эти баллы.
• После окончания периода действия цепочки призовые баллы сбрасываются не сразу. Сброс выполняется 4 раза в час: в :00, :15, :30 и :45. Например, если цепочка закончилась в 12:03, сброс произойдет в 12:15.
  Между цепочками с общими призовыми баллами оставляйте интервал не менее 15 минут, иначе баланс не успеет обнулиться, и пользователи начнут новую цепочку с прежним балансом. Чтобы сбросить прогресс немедленно, используйте метод API Сброс цепочки наград.

Баланс клана рассчитывается как сумма балансов его участников, поэтому после сброса цепочки баланс клана также обнулится.

Награды

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

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

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

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

Вы можете настроить систему вознаграждений через Личный кабинет или через методы API:

1. Создайте призовые баллы. Убедитесь, что в магазине есть товары, за покупку которых баллы будут начисляться.
2. Создайте цепочку наград.

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

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

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

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

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

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

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

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

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

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

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

9. После того как вы добавили нужное количество шагов, нажмите Далее.
10. Если вы хотите сделать цепочку наград персонализированной:

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

11. Укажите период действия цепочки наград: часовой пояс, начало и конец периода. Чтобы не указывать конец периода действия цепочки, установите флажок Без даты окончания.

Примечание

Чтобы добавить еще один период действия цепочки наград, нажмите +. Если у цепочки несколько периодов, каждый из них должен иметь дату окончания. Цепочка завершается в последнюю секунду указанной минуты. Например, если указано время 12:00, цепочка завершится в 12:00:59.

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

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

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

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

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

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

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

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

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

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

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

6. В раскрывающемся списке выберите цепочку наград.

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

9. Чтобы изменения вступили в силу, опубликуйте сайт:
   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.

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

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

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

Глоссарий

Предварительные условия

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

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

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

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

2. В области списка призовых баллов нажмите значок +.

3. Выберите тип призовых баллов — Индивидуальные призовые баллы или Клановые призовые баллы. Тип призовых баллов определяется на этапе создания и не может быть изменен впоследствии.

4. Добавьте изображение (опционально).

5. Введите имя.

6. Введите уникальный артикул призовых баллов.

7. Нажмите Далее.

8. Назначьте призовые баллы:

   1. Нажмите Добавить затронутый товар.

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

   3. Нажмите Выбрать.

   Если в вашем магазине еще нет товаров, вы можете сохранить текущие настройки и вернуться к этому шагу позже.

9. Нажмите Далее.

10. Проверьте настройки призовых баллов.

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

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

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

2. Приступите к созданию наград одним из следующих способов:
   1. На панели инструментов нажмите значок + и выберите Reward chain.
   2. В области списка цепочек наград нажмите значок +.
   3. Откройте контекстное меню в любом месте на канвасе и выберите Reward chain.

3. Выберите тип цепочки — Индивидуальная цепочка наград или Клановая цепочка наград. Тип цепочки наград определяется на этапе создания и не может быть изменен впоследствии.

4. Укажите основные параметры цепочки:

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

5. Нажмите Далее.

6. Настройте призовые баллы — создайте новые призовые баллы или выберите из существующих.

7. Нажмите Далее.

8. Добавьте награду для каждого шага цепочки. Чтобы добавить награду для одного шага:

   1. Нажмите Добавить новый шаг.

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

   3. Нажмите Добавить предмет.

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

10. Чтобы изменить порядок наград в цепочке, перетащите строку на нужную позицию, используя значок ☰ (опционально).

11. После того как вы добавили награды для каждого шага, нажмите Далее.

12. Укажите срок действия цепочки наград: часовой пояс, дату начала и дату окончания. Если вы не хотите указывать конец срока действия, установите флажок Без даты окончания.

Примечание

Чтобы добавить еще один срок действия цепочки наград, нажмите Добавить период. Если у цепочки несколько сроков действия, каждый из них должен иметь дату окончания. Цепочка завершается в последнюю секунду указанной минуты. Например, если указано время окончания 12:00, цепочка завершится в 12:00:59.

Если вы используете одни и те же призовые баллы для нескольких цепочек наград, оставьте как минимум 15 минут между окончанием одного периода цепочки и началом следующего. Призовые баллы и прогресс по шагам сбрасываются фоновым заданием, которое выполняется в :00, :15, :30 и :45 каждого часа (не в момент окончания периода). Если следующий период начинается раньше, чем одно из этих времен, пользователи могут сохранить свой предыдущий баланс. Если вы хотите немедленно сбросить прогресс по шагам, вызовите метод API Сброс цепочки наград.

13. Чтобы автоматически сбросить прогресс в цепочке наград, включите переключатель Сброс призовых баллов.

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

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

    1. Включите переключатель Персонализированная цепочка наград.

    2. Выберите один из вариантов отображения цепочки:

       • Отображать авторизованным пользователям — в этом случае цепочка отображается только авторизованным пользователям, которые соответствуют указанным условиям.

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

    3. Если вы выбрали вариант Отображать авторизованным пользователям, укажите условие:

       1. Укажите тип атрибута пользователя — строка, число или дата.

       2. Выберите атрибут пользователя из выпадающего списка.

       3. Выберите оператор сравнения.

       4. Укажите значение атрибута пользователя.

    4. Чтобы добавить больше условий, нажмите Добавить условие и заполните отображаемые поля (опционально).

16. Нажмите Далее.

17. Проверьте цепочку.

18. Чтобы активировать цепочку сразу (опционально), включите переключатель Создать в статусе Активно.

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

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

    1. Откройте сайт в конструкторе, нажав Open или Open in Site Builder на баннере в форме редактирования.
    2. Следуйте инструкциям из раздела Отображение системы вознаграждений.

Примечание

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

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

• Из карточки цепочки наград
• Из списка цепочек наград
• При редактировании цепочки

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

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

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

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

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

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

6. В раскрывающемся списке выберите цепочку наград.

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

9. Чтобы изменения вступили в силу, опубликуйте сайт:
   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.