Tasks

Tasks

Назначение Tasks

Задания (Tasks) — это механика заданий и геймификации, которая:

• Мотивирует пользователей выполнять целевые действия (покупки, регистрации, просмотры и т.д.)
• Позволяет настраивать многоуровневые задания с прогрессом выполнения
• Автоматически начисляет вознаграждение после завершения через интеграцию с модулем Flow

Примеры заданий

• «Совершите 3 покупки в июне — получите 500 баллов»
• «Заполните профиль — откройте новый уровень»
• «Приведите друга — получите 10% кэшбэка»
• «Заходите в приложение каждый день и получайте купон со скидкой»

Статусы заданий

Задание может находиться в одном из следующих статусов:

Управление статусами

• Статус меняется при выполнении определенных условий
• Изменение статуса выполняется либо бэкенд-системой клиента, либо сценариями в Flow
• Вручную изменить статус нельзя — только через API-методы
• При достижении expired_at задание автоматически переходит в статус expired

Пример логики изменения статуса в Flow:

1. Сценарий отслеживает пользовательское поведение
2. При выполнении условий задания сценарий меняет статус на completed
3. Параллельно создается сущность Reward как награда за выполнение

Прогресс выполнения заданий

Типы прогресса (progress_type)

Поле max

• Поле max определяет целевое значение прогресса, при достижении которого задание считается выполненным
• Проверка выполнения обычно производится decision engine или сценарием в Flow

Пример: Если max=3 и progress=2, значит выполнено 2 из 3 необходимых действий.

Как работает проверка прогресса

Процесс проверки:

1. Агрегация данных – система собирает информацию о действиях клиента
2. Проверка прогресса – через API передаются персонализированные параметры выполнения задания
3. Начисление награды – если пользователь выполнил условия, награда автоматически начисляется через Flow

Истечение срока задания

• Поле expired_at определяет дату и время окончания задания
• При наступлении этой даты задание автоматически переходит в статус expired
• Продлить задание напрямую нельзя, но можно изменить значение expired_at через API
• Важно: При изменении expired_at необходимо вручную обновить статус у всех клиентов, у которых есть это задание

Многоуровневые задания

Система поддерживает гибкую настройку многоуровневых заданий. Реализация зависит от бизнес-логики:

Вариант 1: Этапы внутри одного задания

• Одно задание с несколькими ключевыми точками
• При достижении каждого этапа выдается промежуточная награда
• Логика прописывается в Flow

Вариант 2: Цепочка заданий

• При выполнении одного задания оно переходит в статус completed
• Автоматически активируется следующее задание в цепочке
• Логика последовательности настраивается в Flow

Связь с наградами

Награды за выполнение заданий настраиваются и выдаются через модуль Flow:

• При выполнении условий сценарий создает сущность Reward для клиента
• Награды могут быть разными для разных пользователей
• Можно настроить выдачу нескольких наград за одно задание
• Поддерживается случайная выдача наград с использованием Treasures (Сундуков) — механики вероятностного получения призов

Совет: Подробнее о механике Treasures см. в разделе "Treasures (Сундуки с вероятностями)".

SQL и персонализация

SQL-запросы для персонализации заданий

Поле sql используется для динамической персонализации заданий по клиентам:

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

1. В поле sql указывается запрос с параметризацией, например: {{client_id}}
2. Запрос содержит условия WHERE для проверки выполнения критериев
3. При вызове API "Получить задания по клиенту" выполняется SQL-запрос
4. Если запрос возвращает строку — задание передается клиенту
5. Если запрос не возвращает результатов — задание не показывается

Пример SQL-запроса:

SELECT * FROM purchases 
WHERE client_id = {{client_id}} 
AND purchase_date >= '2025-06-01' 
AND purchase_date < '2025-07-01'
HAVING COUNT(*) >= 3

Этот запрос проверяет, совершил ли клиент 3 или более покупок в июне.

Персонализация данных

• Используйте объект personalization для замены статичных параметров на динамические
• Позволяет создавать уникальные условия для каждого клиента или сегмента

curl --request POST \
     --url /v1/management/tasks/ \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "environment_id": "accelera",
  "id": "june_purchases",
  "title": "Июньские покупки",
  "short_description": "Совершите 3 покупки в июне",
  "full_description": "Совершите 3 покупки в течение июня и получите 500 бонусных баллов",
  "details": "Награда: 500 баллов",
  "status": "active",
  "progress_type": "discrete",
  "max": 3,
  "position": 1,
  "expired_at": "2025-06-30T23:59:59Z"
}
'

curl --request PUT \
     --url /v1/management/tasks/ \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "environment_id": "accelera",
  "id": "june_purchases",
  "status": "completed"
}
'

curl --request DELETE \
     --url /v1/management/tasks/{{environment_id}}/{{id}} \
     --header 'accept: application/json'

curl --request GET \
     --url /v1/internal/tasks/clients/{{client_id}}/{{environment_id}} \
     --header 'accept: application/json'

Примечание: Этот запрос возвращает все задания, доступные клиенту, с учетом SQL-фильтрации и персонализации.

Создание задания по клиенту

curl --request PUT \
     --url /v1/internal/tasks/clients \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "client_id": "12345",
  "environment_id": "accelera",
  "id": "june_purchases",
  "status": "in_progress",
  "progress": 1
}
'

Удаление задания по клиенту

curl --request DELETE \
     --url /v1/internal/tasks/clients/{{client_id}}/{{environment_id}}/{{id}} \
     --header 'accept: application/json'

Интеграция с модулем Flow

Как Flow отслеживает выполнение заданий

Flow отслеживает выполнение заданий через систему событий (триггеров):

1. Получение событий – в Flow приходят системные события с определенными названиями
2. Машина состояний – Flow ведет клиента по машине состояний до нужного этапа
3. Проверка условий – сценарий проверяет выполнение условий задания
4. Изменение статуса – при выполнении условий статус задания меняется на completed
5. Выдача награды – параллельно создается сущность Reward

Триггеры событий

• События могут быть любыми системными, которые приходят через Event Adapter
• Примеры событий: purchase, login, profile_update, referral, item_purchase
• Каждое событие содержит данные о клиенте и контексте действия

Практический пример: Задание "Ежедневный вход"

Условие задания: "Заходите в приложение каждый день и получайте купон со скидкой"

Логика работы сценария в Flow:

1. Получение события – приходит событие login с данными клиента
2. Проверка даты – сценарий сравнивает дату последней авторизации с текущей датой
3. Условие выполнено:
   • Если это новый день → задание засчитывается
   • Прогресс увеличивается на 1
   • Создается награда (купон со скидкой)
   • Статус задания переходит в completed
4. Условие не выполнено:
   • Если это тот же день → ничего не происходит
5. Сброс статуса – в 00:00 статус задания снова переходит в active, и клиент может выполнить задание снова

Визуализация сценария:

[Событие Login] 
    ↓
[Проверка: Новый день?]
    ↓ Да
[Увеличить progress]
    ↓
[Создать Reward (купон)]
    ↓
[Статус = completed]
    ↓
[В 00:00 → Статус = active]