Перейти к основному содержимому

Теги клиентов

Тег в Sailplay — это именованная метка, закрепляемая за конкретным клиентом, которая фиксирует значимое состояние профиля или факт взаимодействия.

Клиентские теги лежат в основе:

  • триггерных сценариев,
  • сегментации,
  • автоматизаций,
  • аналитики,
  • персонализированных коммуникаций.

Виды тегов​

По смыслу теги делятся на два типа:

  • Тег-событие — отражает совершённое действие
    Например: «Подтвердил email», «Оставил заявку», «Открыл письмо»

  • Тег-сегмент — отражает принадлежность клиента к группе
    Например: «VIP-статус», «Устройство Android», «Возраст: 21–25»

Классификация тегов​

В Sailplay теги делятся на две категории:

  • Системные
  • Пользовательские

⚙️ Системные теги​

Системные теги встроены в платформу и назначаются автоматически.

Как появляются​

Проставляются при:

  • системных событиях,
  • обновлении профиля клиента,
  • наличии определённых данных (например, даты рождения).

Кто управляет​

Удалить или изменить системный тег нельзя.
В отдельных случаях допускается снятие тега у конкретного клиента, если это предусмотрено логикой.

Для чего используются​

Используются как универсальные признаки:

  • для сегментаций,
  • для автоматизаций,
  • для триггерных сценариев.

Примеры системных тегов​

  • Регистрация в программе лояльности
    Проставляется автоматически при создании клиента через метод
    /api/v2/users/add/

  • День рождения
    Используется для запуска сценариев в день рождения или за заданное время до него

  • Изменён Email
    Назначается при смене email клиента
    В параметрах сохраняется предыдущий email

🙋 Пользовательские теги​

Теги, которые партнёр создаёт самостоятельно под задачи бизнеса.

Как появляются​

  • вручную в интерфейсе Sailplay,
  • через автосегментации,
  • через триггерные сценарии,
  • через API.

Кто управляет​

Полностью управляются партнёром:

  • создание,
  • переименование,
  • присвоение,
  • снятие.

Для чего используются​

Позволяют:

  • реализовывать бизнес-логику,
  • запускать сложные сценарии,
  • управлять персонализацией.

Типы тегов​

Каждый тег имеет тип:

🚩 Флаг​

  • Может быть присвоен клиенту только один раз
  • Повторное присвоение игнорируется

🧮 Счётчик​

  • Может присваиваться несколько раз
  • Количество отображается в профиле клиента

Параметры тегов​

Параметры — это дополнительные данные, передаваемые вместе с тегом.

Возможности параметров​

  • Произвольная структура (ключ → значение)
  • Подстановка в шаблоны сообщений
  • Поддержка массивов
  • Отображение в карточке клиента

Пример простых параметров​

{
  "params": {
    "discount_code": "SALE2025",
    "bonus_points": "150"
  }
}

Карта методов API для клиентов​

ГруппаНазначениеURL метода
ТегиПрисвоить теги/api/v2/users/tags/add/
Снять теги/api/v2/users/tags/delete/
Получить список тегов/api/v2/users/tags/list/
Массовое присвоение тегов/api/v3/tags/add/bulk
Массовое снятие тегов/api/v2/users/tags/delete/bulk/
Присвоить теги без создания клиента/api/v2/users/tags/assign

Присвоить теги​

Метод позволяет добавить один или несколько тегов пользователю.

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

Чувствительность к пробелам: теги VIP и VIP считаются разными.

Кириллица и латиница: допускаются оба варианта.

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

  • Если тег отсутствует — он создаётся автоматически.
  • Если пользователь не существует — при вызове создаётся новый пользователь.
  • Предусмотрен вариант вызова, при котором пользователь не создаётся автоматически.

Триггерные сценарии: присвоение тега запускает сценарий, настроенный в интерфейсе Sailplay на одноимённый тег.

Снять теги​

Метод удаляет один или несколько тегов у пользователя. Удаление происходит по одному или нескольким тегам, переданным через запятую. Теги удаляются с учётом точного совпадения. Если тег был назначен несколько раз, достаточно снять его один раз — он полностью исчезнет из профиля.

Получить список тегов​

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

Массовое присвоение тегов​

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

Для управления запуском триггерных сценариев используйте query‑параметр run_chains:

  • 1 — запускает триггерные сценарии для всего пакета
  • 0 — присваивает теги без запуска сценариев

Структура тела запроса — массив клиентов и тегов:

[
  {
    "user": {},
    "tags": []
  },
  {
    "user": {},
    "tags": []
  }
]

Идентификация клиента​

Параметр user принимает один из идентификаторов. В рамках одного запроса можно комбинировать типы идентификаторов.

{
  "user": {
    "email": "mail@gmail.com"
  }
}
{
  "user": {
    "origin_user_id": "ID137813911"
  }
}
{
  "user": {
    "phone": "79998887766"
  }
}
{
  "user": {
    "id": 121823012
  }
}

Теги​

{
  "tags": [
    { "name": "Send message" },
    { "name": "In app" }
  ]
}

С дополнительными параметрами:

{
  "tags": [
    {
      "name": "Send message",
      "params": {
        "category": "Gift",
        "gift": "Free PIZZA"
      }
    }
  ]
}

Итоговый пример запроса​

[
  {
    "user": {
      "email": "mail@gmail.com"
    },
    "tags": [
      {
        "name": "Send message",
        "params": {
          "category": "Gift",
          "gift": "Free PIZZA"
        }
      }
    ]
  }
]

Ответ:

{
  "accepted": "ok"
}

Ответ означает, что запросы добавлены в очередь на исполнение. Скорость обработки зависит от объёма данных.

Массовое снятие тегов​

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

Присвоить теги без создания клиента​

Метод /api/v2/users/tags/assign/ присваивает теги только существующим клиентам. Если клиент не найден, запрос будет проигнорирован. Параметры аналогичны методу /api/v2/users/tags/add/.