Документация Accelera
МодулиLoyaltyРабота с сущностями

Counters

Counters

Назначение Counters

Counters (Счетчики) — это универсальная сущность для подсчета и отслеживания любых метрик по клиенту в программе лояльности.

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

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

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

Счетчики могут использоваться для подсчета чего угодно:

1. Активность и прогресс

{
  "id": "completed_tasks",
  "title": "Выполненные задания",
  "description": "Общее количество выполненных заданий клиентом",
  "value": 0
}

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

2. Стрики (дни подряд)

{
  "id": "login_streak",
  "title": "Дни подряд",
  "description": "Количество дней входа в приложение подряд",
  "value": 0
}

Применение: Мотивация ежедневной активности. При входе каждый день увеличивается счетчик, при пропуске - сбрасывается.

3. Реферальная программа

{
  "id": "invited_friends",
  "title": "Приглашенные друзья",
  "description": "Количество друзей, приглашенных клиентом",
  "value": 0
}

Применение: Подсчет рефералов для выдачи наград за приглашения.

4. Открытые сундуки

{
  "id": "opened_chests",
  "title": "Открытые сундуки",
  "description": "Общее количество открытых сундуков",
  "value": 0
}

Применение: Статистика для достижений типа "Открой 100 сундуков".

5. Лимиты и квоты

{
  "id": "cashback_categories_available",
  "title": "Доступные категории кэшбека",
  "description": "Количество категорий кэшбека, которые клиент может выбрать",
  "value": 3
}

Применение: Управление количеством доступных категорий. При выборе категории счетчик уменьшается, при снятии - увеличивается.

6. Опыт и уровни

{
  "id": "experience_points",
  "title": "Очки опыта",
  "description": "Общее количество накопленного опыта",
  "value": 0
}

Применение: Система прогрессии через уровни. При достижении определенного количества XP клиент переходит на новый уровень.

7. Купленные предметы

{
  "id": "items_purchased",
  "title": "Купленные предметы",
  "description": "Количество предметов, купленных в магазине",
  "value": 0
}

Применение: Статистика покупок для аналитики и достижений.

8. Исторические данные

{
  "id": "total_points_earned",
  "title": "Всего заработано баллов",
  "description": "Общее количество баллов, заработанных за все время",
  "value": 0
}

Применение: Историческая статистика, не влияет на текущий баланс.

9. Специальные события

{
  "id": "event_participations",
  "title": "Участия в событиях",
  "description": "Количество специальных событий, в которых участвовал клиент",
  "value": 0
}

Применение: Подсчет участия в акциях, турнирах, сезонных событиях.

Дефолтные и персональные счетчики

Дефолтные счетчики (is_default = true)

Дефолтные счетчики доступны всем клиентам с одинаковым начальным значением:

{
  "id": "daily_tasks_available",
  "title": "Доступные ежедневные задания",
  "description": "Количество доступных заданий сегодня",
  "is_default": true,
  "value": 5
}

Каждый клиент видит этот счетчик со значением 5 до создания персональной записи.

Персональные счетчики

При изменении счетчика для конкретного клиента создается персональная запись в таблице {{environment_id}}.counters:

{
  "client_id": "12345",
  "counter_id": "daily_tasks_available",
  "value": 2
}

Теперь этот клиент видит значение 2 вместо дефолтного 5.

Персонализация счетчиков

Счетчики поддерживают персонализацию через объект personalization:

{
  "id": "bonus_multiplier",
  "title": "Множитель бонусов",
  "description": "Ваш текущий множитель: {{multiplier}}x",
  "is_default": true,
  "value": 1,
  "personalization": {
    "context": {
      "multiplier": "1"
    },
    "dictionary": {}
  }
}

Для VIP-клиента:

{
  "personalization": {
    "context": {
      "multiplier": "2"
    }
  }
}

Клиент увидит: "Ваш текущий множитель: 2x"

Описание полей

Обязательные поля

ПараметрТип данныхОписание
environment_idVarchar(50)ID окружения, к которому относится счетчик
idVarchar(50)Уникальный идентификатор счетчика

Поля с описанием

ПараметрТип данныхОписание
titleVarchar(50)Название счетчика
descriptionVarchar(250)Описание назначения счетчика

Значения и параметры

ПараметрТип данныхОписание
valueIntegerЗначение счетчика по умолчанию
is_defaultBooleanФлаг дефолтной сущности (доступна всем клиентам)
minIntegerМинимальное значение счетчика (опционально)

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

ПараметрТип данныхОписание
personalizationJSONОбъект персонализации для динамической замены параметров
creatorVarchar(250)Создатель счетчика (имя пользователя)

Примеры заполнения Counters

Пример 1: Счетчик выполненных заданий

{
  "environment_id": "accelera",
  "id": "completed_tasks",
  "title": "Выполненные задания",
  "description": "Количество выполненных заданий за все время",
  "is_default": true,
  "value": 0,
  "min": 0
}

Пример 2: Стрик ежедневных входов

{
  "environment_id": "accelera",
  "id": "login_streak",
  "title": "Дни подряд",
  "description": "Вы заходили {{streak}} дней подряд!",
  "is_default": true,
  "value": 0,
  "min": 0,
  "personalization": {
    "context": {
      "streak": "0"
    },
    "dictionary": {}
  }
}

Пример 3: Квота категорий кэшбека

{
  "environment_id": "accelera",
  "id": "cashback_categories_limit",
  "title": "Доступные категории",
  "description": "Вы можете выбрать еще {{available}} категорий кэшбека",
  "is_default": true,
  "value": 3,
  "min": 0,
  "personalization": {
    "context": {
      "available": "3"
    },
    "dictionary": {}
  }
}

Примеры API-запросов

Создание счетчика в системе

curl --request POST \
     --url /v1/management/counters \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "environment_id": "accelera",
  "id": "login_streak",
  "title": "Дни подряд",
  "description": "Количество дней входа подряд",
  "is_default": true,
  "value": 0,
  "min": 0
}
'

Получение счетчиков клиента

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

Пример ответа:

{
  "counters": [
    {
      "counter_id": "completed_tasks",
      "title": "Выполненные задания",
      "value": 15
    },
    {
      "counter_id": "login_streak",
      "title": "Дни подряд",
      "value": 7
    },
    {
      "counter_id": "cashback_categories_limit",
      "title": "Доступные категории",
      "value": 2
    }
  ]
}

Назначение счетчика клиенту

curl --request PUT \
     --url /v1/internal/counters/clients/ \
     --header 'accept: application/json'
     --data '
{
  "client_id": "client1",
  "environment_id": "accelera",
  "id": "login_streak",
  "value": 0
}
'

Удаление счетчика клиента

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

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

Counters используются во многих механиках системы:

  1. Level - счетчик опыта для повышения уровня
  2. Rewards - подсчет полученных наград
  3. Items - подсчет купленных предметов
  4. Treasures - подсчет открытых сундуков
  5. Flow - использование счетчиков в условиях сценариев

Практические сценарии

Сценарий 1: Система стриков (дни подряд)

Задача: Мотивировать пользователей заходить каждый день.

Реализация:

  1. Создайте счетчик login_streak со значением 0
  2. В Flow настройте сценарий на событие login:
    • Проверить дату последнего входа
    • Если это новый день подряд → увеличить счетчик
    • Если пропущен день → сбросить счетчик в 0
  3. Выдавайте награды за стрики: 7 дней, 30 дней, 100 дней

Сценарий 2: Прогрессия через опыт

Задача: Система уровней на основе опыта.

Реализация:

  1. Создайте счетчик experience_points со значением 0
  2. За различные действия начисляйте XP:
    • Выполнение задания: +50 XP
    • Покупка предмета: +10 XP
    • Приглашение друга: +100 XP
  3. При достижении порогов выдавайте награду:
    • 0-99 XP → Награда 1
    • 100-299 XP → Награда 2
    • 300-599 XP → Награда 3

Сценарий 3: Отслеживание достижений

Задача: Выдать достижение за 100 выполненных заданий.

Реализация:

  1. Создайте счетчик completed_tasks со значением 0
  2. При выполнении каждого задания увеличивайте счетчик
  3. В сценарии проверяйте значение:
IF (counter.value == 100) THEN
  give_achievement("task_master")
  give_reward("achievement_bonus")

Сценарий 4: Дневные лимиты

Задача: Ограничить количество выданных призов в день.

Реализация:

  1. Создайте счетчик free_rewards_today со значением 3
  2. При открытии бесплатного сундука уменьшайте счетчик
  3. В 00:00 сбрасывайте счетчик обратно к 3 через scheduled job
  4. Если счетчик = 0 → показывать "Бесплатные сундуки закончились, попробуйте завтра"

Рекомендации по использованию

  1. Именование - используйте понятные ID счетчиков (login_streak, completed_tasks)
  2. Минимальные значения - устанавливайте min для предотвращения отрицательных значений
  3. Документирование - четко описывайте назначение в поле description
  4. Персонализация - используйте для отображения актуальных значений клиенту
  5. Сброс - предусмотрите механизмы периодического сброса для временных счетчиков
  6. Аналитика - используйте счетчики для сбора статистики и улучшения программы лояльности

Работа с Counters

Для работы со счетчиками используйте методы API, описанные выше. Счетчики могут создаваться и управляться через интерфейс ЛК менеджера или программно через API. Интеграция со сценариями Flow позволяет автоматически обновлять счетчики на основе действий пользователей.

Entities/Profiles

Предыдущая страница

Insights

Следующая страница

На этой странице

CountersНазначение CountersПримеры использования Counters1. Активность и прогресс2. Стрики (дни подряд)3. Реферальная программа4. Открытые сундуки5. Лимиты и квоты6. Опыт и уровни7. Купленные предметы8. Исторические данные9. Специальные событияДефолтные и персональные счетчикиДефолтные счетчики (is_default = true)Персональные счетчикиПерсонализация счетчиковОписание полейОбязательные поляПоля с описаниемЗначения и параметрыПерсонализация и метаданныеПримеры заполнения CountersПример 1: Счетчик выполненных заданийПример 2: Стрик ежедневных входовПример 3: Квота категорий кэшбекаПримеры API-запросовСоздание счетчика в системеПолучение счетчиков клиентаНазначение счетчика клиентуУдаление счетчика клиентаИнтеграция с другими сущностямиПрактические сценарииСценарий 1: Система стриков (дни подряд)Сценарий 2: Прогрессия через опытСценарий 3: Отслеживание достиженийСценарий 4: Дневные лимитыРекомендации по использованиюРабота с Counters