Захват событий Altcraft
Захват событий (Action Hooks) — это механизм уведомления внешних систем о событиях платформы. Это могут быть как системные действия, связанные с доставкой сообщений или импортом профилей подписчиков, так и действия клиентов, отслеженные пикселями платформы Altcraft на Вашем сайте или в приложении.
Захват событий может работать со всеми базами данных или с какой-либо конкретной. Захваченные события могут передаваться батчем в формате JSON по HTTP или отправляться в очередь брокера асинхронно.
Конфигурируется мастер-пользователем аккаунта для определенной базы данных или для всех сразу.
Чтобы начать работу, в главном меню выберите Интеграции → Захват событий:
Существующие захваты событий вы можете активировать или остановить, клонировать или удалить с помощью контекстного меню. Если вы хотите отредактировать захват, нажмите на его заголовок. Чтобы добавить новый, нажмите + Создать в верхней части страницы:
Основные настройки захвата событий
В Основных настройках введите имя нового захвата. Здесь же находится переключатель для активации процесса отправки событий:
Выбор действий для захвата
Захваты событий могут работать со всеми Базами профилей сразу или с одной конкретной. В блоке Настройки захвата выберите необходимый вариант в выпадающем меню База данных:
В поле Действия выберите из выпадающего меню события, которые будут передаваться во внешние системы. Типы событий, их обозначения в меню и в запросе захвата, а также описания вы найдёте в этой статье.
По умолчанию Захват регистрирует все события выбранных вами типов. Ограничить события так, чтобы получать более узкую выборку, можно в блоке Дополнительные фильтры:
- Ресурсы — будут захвачены события, связанные с коммуникациями в рамках определённых ресурсов.
- Рассылки — будут захвачены события определённых маркетинговых рассылок.
- Сообщения — будут захвачены события рассылок, использующих определённые шаблоны сообщений.
- Сегменты — будут захвачены события, связанные с подписчиками, входящими в определённые сегменты.
- Пиксели — будут захвачены действия подписчиков на внешних ресурсах, зарегистрированные определёнными пикселями.
Настройки обратного запроса
Доступны следующие типы запроса:
- Отправить JSON запрос батчем. Подробнее.
- Отправить сообщение в очередь RabbitMQ. Подробнее.
- Отправить сообщение в exchange RabbitMQ. Подробнее.
- Отправить сообщение в Kafka broker. Подробнее.
Функция повторной отправки
Если во время отправки сообщения по каким-то причинам произошла ошибка (например, сбой сети), через определенное время сообщение будет отправлено снова. Количество повторных отправок и их периодичность устанавливаются в конфигурационном файле системы "main.json":
"HOOK_RETRY_TIMES": устанавливает максимальное количество попыток отправки (по умолчанию — 4)
"HOOK_RETRY_PERIOD_SEC": Периоды между попытками отправки, в секундах (по умолчанию — 15)
Передача дополнительных данных о событии в захвате
Данные профиля клиента в захвате
Вместе с информацией о захваченном событии можно передавать значения стандартных и дополнительных полей профиля. Набор доступных дополнительных полей зависит от выбранной базы данных. Выберите в выпадающем списке поля профиля, которые хотите добавить в custom_data:
Ниже можно задать шаблон custom_data. Платформа будет использовать в захват значение из этого шаблона, если в API-запросе на запуск триггера не переданы данные в поле custom_data.
Дополнительные данные в захвате
Помимо данных профиля, в объект custom_data можно передавать любые данные в формате mykey:myvalue. Для этого вручную введите ключ и значение, а затем нажмите Enter ↵.
Доступны шаблонные параметры:
| Параметр | Описание |
|---|---|
{{uuid}} | Генерирует новый UUIDv4 |
{{event_date}} | Дата события в формате "2006-01-25T15:04:05.999999Z" |
{{event_date_ymd}} | Дата события в формате "2006-01-25" |
{{event_date_rfc3339}} | Дата события в формате RFC 3339 |
{{event_date_unix}} | Дата события во времени unix, в строке |
{{event_date_unixnano}} | Дата события во времени unix (наносекунды), в строке |
{{campaign_name}} | Извлекает имя рассылки, если оно актуально для события, иначе пустое |
{{campaign_subid}} | Извлекает SubID рассылки, если оно актуально для события, иначе пустое |
{{database_name}} | Извлекает имя базы данных, если оно актуально для события, иначе пустое |
{{segment_name}} | Извлекает имя сегмента, если оно актуально для события, иначе пустое |
{{message_name}} | Извлекает имя шаблона, если оно актуально для события, иначе пустое |
{{message_subject}} | Извлекает тему сообщения в шаблоне, если оно актуально для события, иначе пустое |
{{resource_name}} | Извлекает имя ресурса, если оно актуально для события, иначе пустое |
Например, вы добавляете в custom_data поля:
В этом случае данные будут переданы следующим образом:
"custom_data": {
"cname": "Black Friday",
"email": "test@example.com",
"eventTime": "2023-03-17",
"eventTimeUnix": "1615988820",
"id": "dc876134-87a4-4437-aabb-d2fc8a3d4213",
}
Поле custom_data может содержать любые произвольные данные. Передаваемые в нём поля не обязаны существовать в базе данных профилей и используются только в рамках самого события. В событии они отображаются в следующем виде:
"custom_data": {
"test_field": "test"
}
Важно учитывать, что поля в custom_data не связаны напрямую со структурой базы профилей. При настройке захвата событий может возникнуть ощущение, что такие поля должны существовать в базе данных, поскольку они передаются в API-запросе. Однако это не требуется. Функция "Добавить поля в custom_data" используется для дополнительной передачи данных — например, чтобы добавить в custom_data значения из профиля или других источников, даже если эти поля изначально отсутствовали в самом запросе.
Контент сообщения в захвате
Для того чтобы вместе с событиями передавать контент всех сообщений, активируйте опцию "Добавить содержимое сообщений":
Содержимое будет передаваться в поле "content". Структура поля для каждого канала описана в этой статье.
Обратите внимание, что при этом все отправленные сообщения будут помещаться в хранилище на фиксированное время, что потребует дополнительного дискового пространства. По умолчанию время хранения — 72 часа и устанавливается глобальной настройкой HOOK_CONTENT_CLEANUP_HOURS в файле main.json. По истечению этого времени события будут передаваться уже без связанного с ними контента.
Экспорт исторических событий за период
Функция позволяет выгрузить в подключение данные о событиях, которые уже произошли в платформе. Это полезно для восстановления данных, если захват событий не был настроен вовремя или произошел сбой в работе.
Для экспорта исторических событий недоступны типы событий: campaign_launch, profile_merge, profile_split
Настройка экспорта
Чтобы запустить экспорт исторических событий, активируйте и сохраните захват событий с нужными настройками, затем в блоке управления выберите опцию "Захватывать исторические события за период", укажите даты начала и окончания периода и нажмите "Запустить":
Период для экспорта исторических событий ограничен: минимальная дата — 01-01-1970, максимальная — предыдущий день. Текущая дата недоступна для выбора.
Для проверки работы экспорта используйте инструмент тестирования — система сгенерирует пример события выбранного типа.
Управление процессом
После запуска вы можете отслеживать прогресс и управлять выполнением:
- Приостановить — временно остановить выгрузку
- Возобновить — продолжить выгрузку
- Прервать — полностью отменить выгрузку
Статусы выполнения
- Выполняется —
Идет процесс экспорта исторических событий за период - На паузе —
Процесс экспорта исторических событий был приостановлен - Завершено —
Экспорт исторических событий за период выполнен - Ошибка —
Возникла ошибка при экспорте исторических событий
Если вы деактивируете захват событий во время выполнения экспорта исторических событий, процесс будет приостановлен до повто рной активации.