Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 80 Next »

В этой статье:

Описание

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

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

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

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

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

Настройки захвата событий

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

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

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

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

Типы событий для захвата
В интерфейсеВ запросеОписание
События Email канала
Send send Email сообщение отправлено для доставки подписчику.
Reply reply Ответ подписчика на полученное Email сообщение.
Unique Open uopen Уникальное открытие email сообщения.
Open open Неуникальное открытие email сообщения.
Unique Click uclick

Уникальный клик по ссылке в email сообщении.
Cоздаёт также события open и uopen, если событие
open не было получено

Click click Неуникальный клик по ссылке в email сообщении.
Confirm confirm

Клик по ссылке подтверждения в обычном сообщении.
Клик по confirm ссылке создаёт также событие click и
uclick, если это первый клик в сообщениию.

Confirm Subscription confirmsub Клик по ссылке подтверждения подписки в double opt-in сообщении.
Unsubscribe unsub
              Подписчик перешел по ссылке отписки в письме и 
              был отписан 
( {unsubscribe} или {globalunsubscribe} ).
Complain complain Подписчик пожаловался на сообщение.
SoftBounce sbounce Событие ответа о временной невозможности доставки сообщения.
HardBounce hbounce Ответ о невозможности доставки сообщения.
Suppression suppress Сообщение не было отправлено подписчику по причине нахождения в стоп-листе.
Delivered deliv Отправщик доставил email сообщение подписчику.
Undelivered undeliv Отправщик не смог доставить сообщение подписчику.
Read Message read Сообщение открыто пользователем в течении 12 и более секунд.
Glanced Message glanced Сообщение открыто до двух секунд.
Skimmed Message skimmed Сообщение открыто до 8 секунд.
События импорта профилей подписчиков
Manual Import import_manual Подписчик был добавлен через интерфейс системы.
File Import import_file Подписчик был добавлен через интерфейс системы, из файла.
API Import import_api Подписчик был добавлен через API.
События для SMS канала
Send SMS send_sms SMS сообщение отправлено для доставки подписчику.
Click SMS click_sms Не уникальный клик по ссылке в SMS сообщении
Unique Click SMS uclick_sms Уникальный клик по ссылке в SMS сообщении
Delivered SMS deliv_sms SMS сообщение доставлено
Undelivered SMS undeliv_sms SMS сообщение не доставлено
События для Push канала
Unique Open Push uopen_push Уникальное открытие push сообщения.
Open Push open_push Не уникальное открытие push сообщения.
Send Push send_push Push сообщение отправлено для доставки подписчику.
Click Push click_push Не уникальный клик по ссылке в push сообщении
Unique Click Push uclick_push Уникальный клик по ссылке в psush сообщении
Delivered Push deliv_push Push сообщение доставлено
Кастомная (API) отписка от рассылок
API unsubscribe unsub_api Подписчик отписан от рассылок через API.
Запуск кампании
Campaign launch campaign_launch Запущена кампания (имеет особую структуру hook-сообщения)
События, захваченные Пикселями на внешних ресурсах
Pixel Open pixel_open Открыт AK-Pixel на сайте
События, связанные с промокодами
Promocode Attach promocode_attach Подписчику назначен промокод.
Promocode Detach promocode_detach Промокод отвязан от профиля подписчика.
Promocode Activate promocode_activate Промокод активирован.
События, связанные с автоматическим созданием статического сегмента на импорте
Static Segment Added segs_add Профиль вошел в статический сегмент.
Static Segment Removed segs_remove Профиль вышел из статического сегмента.


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

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

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

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

  1. Отправть JSON запрос батчем
  2. Отправить сообщение в очередь RabbitMQ
  3. Отправить сообщение в exchange RabbitMQ
  4. Отправить сообщение в Kafka broker

Функция повторной отправки

Если во время отправки сообщения по каким-то причинам произошла ошибка (например, сбой сети), через определенное время сообщение будет отправлено снова. Количество повторных отправок и их периодчиность устанавливаются в конфигурационном файле системы "main.json":

"HOOK_RETRY_TIMES":  устанавливает максимальное количество попыток отправки (default 4)

"HOOK_RETRY_PERIOD_SEC":  Периоды между попытками отправки, в секундах (default 15)

Отправить JSON запрос батчем

Batch-запросы позволяют объединить множество HTTP-запросов в один, указав в теле каждый запрос как отдельный объект. Сервер возвращает один HTTP-ответ, внутри которого находятся ответы на каждый переданный запрос.

Когда мы выбираем этот тип запроса, мы отправляем полученные события в формате JSON в теле POST запроса к внешнему API. При отправке будет сгенерирован JSON массив с событиями.

В настройках запроса необходимо указать:

  • URL сервиса, принимающего данные. 
  • Максимальный размер батча: ограничение количества событий в JSON массиве. POST запрос будет послан, как только наберётся достаточно событий.
[{"event": "send", ... }, { }, ... ]
  • Таймаут секунд: время ожидания набора пачки сообщений для отправки на сервер. Если максимальный размер батча не достигнут, отправится столько сообщения, сколько есть.
  • Успех если найдена строка: ответ от сервера должен попасть в этот Regex, только тогда запрос на сервер будет признан успешным. Например:
.*OK.*

Если оставить поле "Успех если найдена строка" пустым, то любой ответ со статусом (status code) 200 будет считаться правильным.

Пример запроса для двух событий доставки
[
  {
    "event_type": "deliv",
    "list_id": 50,
    "account_id": 161,
    "_xxh": "5ada5e6ea3c6da5f",
    "_md5": "a5656dc1e3f603063a1918d582a10f58",
    "event_data": {
      "message_id": 5,
      "segment_id": 0,
      "campaign_id": 130
    },
    "event_date": "2016-11-15T09:12:28.514388956Z",
    "custom_data": {
      "email": "eddie@test-ukr.net",
      "_fname": "Eddie"
    },
    "is_test": false
  },
  {
    "event_type": "deliv",
    "list_id": 50,
    "account_id": 161,
    "_xxh": "bb42e541c7267fa6",
    "_md5": "593b250db256a764da8d2da4be694b31",
    "event_data": {
      "message_id": 5,
      "segment_id": 0,
      "campaign_id": 130
    },
    "event_date": "2016-11-15T09:12:28.569124547Z",
    "custom_data": {
      "email": "simon@test-gmail.com",
      "_fname": "Simon"
    },
    "is_test": false
  }
]

Отправить сообщение в очередь RabbitMQ

Каждое единичное событие будет отправлено немедленно в очередь брокера сообщений. Может использоваться как локальный RabbitMQ, входящий в состав платформы, так и расположенный на внешнем хосте брокер. В настройках укажите хост и порт брокера, имя и пароль пользователя для авторизации, имя виртуального хоста и название очереди, в которую будут попадать сообщения о событиях.

RabbitMQ пользователь должен иметь доступ к выбранному виртуальному хосту. Создать Виртуальный хост (virtual host) и дать пользователю RabbitMQ право его использовать нужно в самой RabbitMQ.

При отправке в RMQ можно указывать или не указывать имя очереди. Если имя очереди не будет передано, то оно будет установлено в соответствии с именем события (см. таблицу Типы событий для захвата).
Пример сообщения о клике на ссылку в Email
{
  "event_type": "click",
  "event_date": "2018-03-04T13:13:19.034315796Z",
  "list_id": 111,
  "_xxh": "ad1850e0d1d9481e",
  "_md5": "145bb30f7ddf1184cb560bc4b7705646",
  "is_test": false,
  "event_data": {
    "browser": "Firefox",
    "campaign_id": 973,
    "city": "",
    "country": "",
    "device": "web",
    "ip": "10.9.0.14",
    "lat": 0,
    "launch_id": "00000017000003cd5a9bf01a",
    "link_url": "http://www.ford.com",
    "lon": 0,
    "message_id": 17,
    "os": "Linux x86_64",
    "postal_code": "",
    "region": "",
    "segment_id": 0,
    "send_message_id": "5a9bf01a17_3cd_11_6f_0_2.5a8c045fc1dde44cbf718f78",
    "tz": "",
    "user_agent": "Mozilla/5.0 (X11; Linux x86_64; rv:59.0) Gecko/20100101 Firefox/59.0"
  },
  "custom_data": {
    "email": "alice@example.org"
  },
  "account_id": 23
}

Отправить сообщение в exchange RabbitMQ

Exchange - это точка обмена, другими словами, еще один игрок между отправителем сообщения и очередью. Эта точка обмена распределяет сообщения в одну или несколько очередей.

Для настройки отправки сообщения в exchange RabbitMQ укажите хост, порт, имя пользователя, пароль и имя виртуально хоста.

При отправке в RMQ можно указывать или не указывать имя exchange. Если имя exchange не будет передано, то оно будет установлено в соответствии с именем события (см. таблицу Типы событий для захвата).

Далее нас просят выбрать тип exchange:

  1. Тип direct позволяет отправлять сообщения только одной очереди. Причем в ту очередь, имя которой совпадает с ключом маршрутизации (routing key).
  2. Тип topic отправляет сообщения в несколько очередей, у которых совпадает ключ маршрутизации.

По умолчанию активирована опция durable. Это означает, что точка обмена будет постоянно храниться на диске и сможет пережить перезапуск сервера. Если убрать галочку с этого поля, то exchange станет временным и в случае перезапуска сервера удалится.

Также стоит обратить внимание на поле Auto delete (автоудаление). Если активирвоать это поле, то exchange будет удален, как только будут удалены все связанные с ним очереди.

Пример сообщения об уникальном клике в Email
{
"event_type": "uclick",
"event_date": "2021-03-05T14:08:47.18953529+03:00",
"list_id": 123456,
"profile_id": "000000000000000000000000",
"_xxh": "61be4d0b871502d4",
"_md5": "a42c44fc77533b43ffd569ed4c83e377",
"is_test": true,
"event_data": {
	"browser": "Firefox",
	"campaign_id": 286,
	"city": "",
	"country": "",
	"device": "web",
	"ip": "192.168.0.58",
	"lat": 0,
	"launch_id": "2_5W_4HECAgq2o6H",
	"link_url": "https://emailtemplate.ga/?utm_source=email&utm_medium=&utm_campaign=286&utm_term=kirk.mckinney83@example.com&utm_content=9",
	"lon": 0,
	"message_id": 9,
	"os": "Ubuntu",
	"postal_code": "",
	"region": "",
	"segment_id": 0,
	"send_message_id": "w4HECAgxdpsf_2_5W_a_6__3_.2MpNdKgZFnZxJbCiJ",
	"tz": "",
	"user_agent": "Mozilla/5.0 (X11; Ubuntu; Linux x86_64; rv:81.0) Gecko/20100101 Firefox/81.0"
	},
"custom_data": {
	"email": "kirk.mckinney83@example.com"
	},
"account_id": 1,
"sends_trying_num": 1,
"is_static": false
}

Отправить сообщение в Kafka broker

Для настройки отправки событий в Apache Kafka, укажите:

  • хост
  • порт,
  • название темы
  • идентефикатор раздела (partition).

Активируйте TLS, если это необходимо. При применении самоподписанного сертификата, если он не внесен в доверенные, укажите цепочку CA сертификатов в PEM формате. При этом также учитывается глобальная опция ALLOW_INSECURE_REQUESTS в файле конфигурации main.json. Если она установлена, валидность сертификатов не проверяется. Если применяется авторизация с клиентским сертификатом, то необходимо указать приватный ключ клиента и сертификат в PEM формате.

Поддержка SASL аутентификации в данный момент недоступна.

Данные профиля клиента в захвате событий

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


Для того, чтобы передавать содержимое всех сообщений вместе с событиями, активируйте опцию:

Обратите внимание, что при этом все отправленные сообщения будут помещаться в хранилище на фиксированное время, что потребует дополнительного дискового пространства. По умолчанию время хранения - 72 часа и устанавливается глобальной настройкой HOOK_CONTENT_CLEANUP_HOURS в файле main.json. По истечению этого времени события будут передаваться уже без связанного с ними контента.

Пример передачи контента для Push сообщений
{
  ...
  "content": {
     "title": "Push title"
     "body": "Push body"
     "icon": "Push icon"
     "click_url": "https://google.com/?q=push%20click%20url"
 }
}

Структуры сообщений захвата событий

Информация об отправленном клиенту сообщении записывается send_message_id.

Параметр имеет вид: 5a9bf01a17_3cd_11_6f_0_2.5a8c045fc1dde44cbf718f78

Часть слева от . состоит из hex чисел

  • 5a9bf01a UTC Timestamp времени отправки сообщения
  • 17 - ID аккаунта
  • 3cd - ID кампании
  • 11 - ID сообщения
  • 6f - ID базы данных
  • - ID сегмента
  • - ID сендера

Часть справа от . это ID профиля в базе данных 5a8c045fc1dde44cbf718f78.


Для всех типов событий:

Общая структура hook-сообщения
ПараметрТипПримерОписание
event_typestringclickНазвание события как в таблице типы событий.
event_datestring2018-03-04T13:13:19.034315796ZДата возникновения события в формате ISO-8601.
_xxhstringad1850e0d1d9481eХеш от email подписчика, используемый для идентификации в ALTCRAFT.
_md5string145bb30f7ddf1184cb560bc4b7705646MD5 хеш от email подписчика.
list_idint111ID Базы данных (листа), в рамках которого возникло событие.
account_idint23ID Аккаунта, в рамках которого возникло событие.
is_testboolfalseБыло ли событие вызвано тестовой отправкой сообщения.
custom_dataJSON object
{"email": "alice@example.org"}
Набор данных о подписчике, настраиваемый в интерфейсе редактирования Action Hook.
event_data JSON object
{"browser": "Firefox"}
Набор данных, зависящий от типа события (есть два типа - событие в трекинге и возникающее в процессе доставки).


Для событий следующих типов:

  • uopen, open, uclick, click, confirm, confirmsub, unsub, read, glanced, skimmed,
  • uclick_sms, click_sms, uclick_sms,
  • uopen_push, open_push, click_push, uclick_push.
Структура event_data для событий, возникающих в системе трекинга
ПараметрТипПримерОписание
message_idint17ID сообщения в системе ALTCRAFT
campaign_idint973ID кампании в системе ALTCRAFT
segment_idint0ID сегмента, если доступно
resource_idint3ID ресурса
ipstring10.9.0.14IPv4 адрес подписчика
countrystring
Страна в TLD виде
citystring
Город подписчика
postal_codestring
Почтовый код подписчика
regionstring
Регион подписчика
tzstringEurope/VaduzВременная зона подписчика
latfloat
Географическая широта
lonfloat
Географическая долгота
user_agentstringMozilla/5.0 (X11; Linux x86_64; rv:59.0) Gecko/20100101 Firefox/59.0Строка в заголовке User-Agent
osstringLinux x86_64Операционная система
browserstringFirefoxБраузер, версия
devicestringwebУстройство
link_urlstring http://www.ford.com HTTP ссылка, на которую был осуществлен редирект
launch_idstring00000017000003cd5a9bf01aID запуска. Состоит из трёх hex чисел:
ID Аккаунта - 00000017
ID кампании - 000003cd
UTC Timestamp времени отправки - 5a9bf01a
send_message_idstring5a9bf01a17_3cd_11_6f_0_2.5a8c045fc1dde44cbf718f78ID отправленного сообщения

Для событий следующих типов:

  • send, deliv, undeliv, suppress, sbounce, hbounce, complain,
  • send_sms, deliv_sms, undeliv_sms,
  • send_push, deliv_push.
Структура event_data для событий, возникающих в процессе отправки сообщений
ПараметрТипПримерОписание
message_idInteger17ID сообщения в системе ALTCRAFT
campaign_idInteger973ID кампании в системе ALTCRAFT
segment_idInteger0ID сегмента, если доступно
resource_idInteger3ID ресурса в системе ALTCRAFT
bounce_codeInteger500Код ответа от мейл сервера для событий sbounce, hbounce
bounce_messageStringNo such emailОтвет от мейл сервера, для событий sbounce, hbounce
launch_idString00000017000003cd5a9bf01aID запуска. Состоит из трёх hex чисел:
ID Аккаунта - 00000017
ID кампании - 000003cd
UTC Timestamp времени отправки - 5a9bf01a
send_message_idString5a9bf01a17_3cd_11_6f_0_2.5a8c045fc1dde44cbf718f78ID отправленного сообщения


Для событий типа pixel_open:

Структура event_data для событий пикселей
ПараметрТипПримерОписание
ipstring10.9.0.14IPv4 адрес подписчика
countrystring
Страна в TLD виде
citystring
Город подписчика
pixel_idint41ID пикселя
postal_codestring
Почтовый код подписчика
regionstring
Регион подписчика
tzstringEurope/VaduzВременная зона подписчика
latfloat
Географическая широта
lonfloat
Географическая долгота
user_agentstringMozilla/5.0 (X11; Linux x86_64; rv:59.0) Gecko/20100101 Firefox/59.0Строка в заголовке User-Agent
osstringLinux x86_64Операционная система
browserstringFirefoxБраузер, версия
devicestringwebУстройство


Для событий типа promocode_attach, promocode_detach, promocode_activate:

Структура event_data для событий, связанных с промокодами
ПараметрТипПримерОписание
attachedstring"2020-10-02T13:28:52Z"Дата и время прикрепления промокода к профилю
detachedstring"2020-10-02T13:28:52Z"Дата и время отсоединения промокода
activatedstring"2020-10-02T13:28:52Z"Дата активации промокода
codestring"TEST-XOUH-KBJM-J5K9-24I1"Промокод
db_idint123456Идентификатор базы профиля
loyalty_idint9Идентификатор программы лояльности
profile_idstring"000000000000000000000000"Идентификатор профиля


Для событий типа segs_add, segs_remove:

Структура event_data для событий, связанных с автоматических созданием статического сегмента при импорте
ПараметрТипПримерОписание
campaign_idint9ID кампании в системе ALTCRAFT
launch_idstring""ID запуска. Состоит из трёх hex чисел:
ID Аккаунта - 00000017
ID кампании - 000003cd
UTC Timestamp времени отправки - 5a9bf01a
message_idint0ID сообщения в системе ALTCRAFT
segment_idint80ID сегмента, если доступно
send_message_idstring""ID отправленного сообщения


Для событий типа campaign_launch:

Общая структура события campaign_launch
ПараметрТипПримерОписание
event_typestringcampaign_launchТип события
event_datestring2018-03-04T13:13:19.034315796ZДата события в формате ISO-8601
account_idint23ID аккаунта платформы
is_testboolfalseПризнак тестовой отправки события
event_dataJSON object{}

Обект с данными о кампании

Структура event_data для campaign_launch
ПараметрТипПримерОписание
campaign_idint42Идентификатор кампании
campaign_typestringbroadcastТип кампании
campaign_namestringnameНазвание кампании
campaign_sub_idstringx11
data_typestringsegmentТип источника данных
data_idint3Идентификатор источника данных
launch_idstring00000017000003cd5a9bf01aID запуска. Состоит из трёх hex чисел:
ID Аккаунта - 00000017
ID кампании - 000003cd
UTC Timestamp времени отправки - 5a9bf01a
contentJSON object{}Информация о шаблонах сообщений кампании
Пример события запуска кампании
{
  "event_type": "campaign_launch",
  "event_date": "2016-12-09T10:11:24.934079204Z",
  "is_test": false,
  "account_id": 161,
  "event_data": {
    "campaign_id": 1472,
    "campaign_type": "broadcast",
    "campaign_name": "Campaugn Launch Hook",
    "campaign_sub_id": "x11"
    "data_type": "segment",
    "data_id": 1221,
    "launch_id": "000000a1000005c0584a834c",
    "content": [
      {
        "message_name": "Hello",
        "message_id": 1412,
        "suppress_id": 271,
        "replyto_email": "",
        "replyto_name": "",
        "text": "текстовая версия письма",
        "html": "<html> html версия письма </html>",
        "from_name": "",
        "from_email": "",
        "attach_links": [],
        "subject": "Hello, {your_name}!"
      },
      {
        "message_name": "Hi",
        "message_id": 1413,
        "suppress_id": 272,
        "replyto_email": "monty@altcraft.com",
        "replyto_name": "Monty",
        "text": "текстовая версия письма",
        "html": "<html> html версия письма </html>",
        "from_name": "",
        "from_email": "",
        "attach_links": [
          {
            "name": "text_file.txt",
            "url": "http://test.altcraft.com/api/attach/link/text_file.txt?token=eyJh..."
          }, 
          {
            "name": "picture_file.png",
            "url": "http://test.altcraft.com/api/attach/link/picture_file.png?token=eyJh..."
          }
        ],
        "subject": "Hi, {your_name}!"
      }
    ]
  }
}

Предварительное тестирование события

При работе с захватом событий есть возможность тестирования любого события непосредственно из интерфейса платформы. Для этого необходимо нажать на иконку в виде колбы в верхней панели.

В новом окне укажите тип события, которое вы хотите протестировать:

Автоматически будет сгенерирован  пример структуры выбранного события. В данную структуру можно вносить изменения.

Нажмите кнопку Отправить, чтобы протестировать событие.

Если сообщение было успешно отправлено посредством HTTP запросом, то вы увидите код резутата: 200, а также данные ответа.

Если же сообщение было успешно отправлено в очередь или exchange RabbitMQ или в Kafka broker, то вы увидете текст: "Тест был успешно отправлен".

В противном случае, внизу появится красное поле, где вы сможете узнать код ошибки (в случае HTTP запроса) и ее причину.


Тип запросаСообщение отправлено успешноОшибка при отправке сообщения

JSON запрос батчем

В очередь / exchange RabbitMQ


В Kafka broker

  • No labels