Захват событий Altcraft

Захват событий (Action Hooks) — это механизм уведомления внешних систем о событиях платформы. Это могут быть как системные действия, связанные с доставкой сообщений или импортом профилей подписчиков, так и действия клиентов, отслеженные пикселями платформы Altcraft на Вашем сайте или в приложении.

Захват событий может работать со всеми базами данных или с какой-либо конкретной. Захваченные события могут передаваться батчем в формате JSON по HTTP или отправляться в очередь брокера асинхронно.

Конфигурируется мастер-пользователем аккаунта для определенной базы данных или для всех сразу.

Чтобы начать работу, в главном меню выберите Интеграции → Захват событий:

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

Основные настройки захвата событий

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

Выбор действий для захвата

Захваты событий могут работать со всеми Базами профилей сразу или с одной конкретной. В блоке Настройки захвата выберите необходимый вариант в выпадающем меню База данных:

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

По умолчанию Захват регистрирует все события выбранных вами типов. Ограничить события так, чтобы получать более узкую выборку, можно в блоке Дополнительные фильтры:

• Ресурсы — будут захвачены события, связанные с коммуникациями в рамках определённых ресурсов.
• Рассылки — будут захвачены события определённых маркетинговых рассылок.
• Сообщения — будут захвачены события рассылок, использующих определённые шаблоны сообщений.
• Сегменты — будут захвачены события, связанные с подписчиками, входящими в определённые сегменты.
• Пиксели — будут захвачены действия подписчиков на внешних ресурсах, зарегистрированные определёнными пикселями.

Настройки обратного запроса

Доступны следующие типы запроса:

1. Отправить JSON запрос батчем. Подробнее.
2. Отправить сообщение в очередь RabbitMQ. Подробнее.
3. Отправить сообщение в exchange RabbitMQ. Подробнее.
4. Отправить сообщение в 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, максимальная — предыдущий день. Текущая дата недоступна для выбора.

Для проверки работы экспорта используйте инструмент тестирования — система сгенерирует пример события выбранного типа.

Управление процессом

После запуска вы можете отслеживать прогресс и управлять выполнением:

• Приостановить — временно остановить выгрузку
• Возобновить — продолжить выгрузку
• Прервать — полностью отменить выгрузку

Статусы выполнения

• Выполняется — Идет процесс экспорта исторических событий за период
• На паузе — Процесс экспорта исторических событий был приостановлен
• Завершено — Экспорт исторических событий за период выполнен
• Ошибка — Возникла ошибка при экспорте исторических событий

примечание

Если вы деактивируете захват событий во время выполнения экспорта исторических событий, процесс будет приостановлен до повторной активации.