Интеграция потоковой передачи событий

Требуется помощь разработчика

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

Обзор интеграции

Тип интеграции

Источник: Данные отправляются из Pushwoosh в вашу систему через HTTP или gRPC на основе настроенных триггеров событий.

Как работает интеграция?

Pushwoosh передает данные о событиях коммуникации (например, активность push-уведомлений/email) на конечную точку, определенную клиентом. Данные отправляются в виде пакетных потоков по расписанию или при достижении минимального размера пакета.

Данные отправляются только в том случае, если они соответствуют выбранным событиям, платформам и дополнительным фильтрам (коды кампаний/сообщений, live activity). Конечная точка клиента должна быть готова к приему и, при необходимости, к ответу со статусом.

Глоссарий

URL конечной точки: Серверная конечная точка, которая позволяет принимать запросы. Клиент может указать порт при необходимости.

Примеры:

• https://clientdomainname.com/webhook_endpoint
• https://clientdomainname.com:8081/webhook_endpoint

Список синхронизируемых сущностей

• События статистики коммуникаций (например, Push Sent, Email Delivered)
• Post events: события, которые ваше приложение отправляет в Pushwoosh через postEvent, передаются отдельно от событий статистики коммуникаций

Варианты использования

• Отслеживание вовлеченности в реальном времени

Отслеживайте взаимодействия пользователей, такие как отправка push-уведомлений, открытие email или доставка сообщений, в момент их совершения, что обеспечивает немедленную видимость эффективности кампании.

• Интеграция с внешней аналитикой

Передавайте события на сторонние аналитические платформы для централизованной отчетности и анализа.

• Автоматизированные рабочие процессы пользователей

Запускайте действия во внешних системах (таких как CRM или инструменты автоматизации маркетинга) на основе поведения пользователей, например, отправляйте последующее сообщение, когда пользователь открывает email.

• Синхронизация списка устройств

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

Настройка интеграции

Чтобы настроить интеграцию:

1. В вашем аккаунте Pushwoosh перейдите в Settings > 3rd party Integrations, найдите Event streaming integration и нажмите Configure.

2. В открывшемся окне заполните необходимые поля.

Введите URL конечной точки

В поле Endpoint URL введите полный URL, на который будут отправляться события, включая протокол и порт, если это применимо.

Пример

• https://clientdomainname.com/webhook_endpoint
• https://clientdomainname.com:8081/webhook\_endpoint

Выберите события

В выпадающем списке Events выберите хотя бы одно событие. Если ни одно событие не выбрано, проверка не будет пройдена. Список событий управляется бэкендом и может со временем меняться.

Предоставьте учетные данные для авторизации

Если это требуется вашим сервером, введите полное значение для заголовка Authorization в поле Authorization.

Примеры:

• Bearer your_token_here

• Basic base64encoded_credentials

Примечание

Значение вставляется как есть в заголовок Authorization (HTTP) или метаданные gRPC. Убедитесь, что между схемой аутентификации и токеном есть пробел.

Выберите тип транспорта

В выпадающем списке Transport type выберите протокол доставки для передачи событий: HTTP или gRPC. Каждый из них имеет свои особенности поведения и настройки.

HTTP

При использовании типа транспорта HTTP Pushwoosh отправляет данные пакетами при выполнении одного из следующих условий:

• Готово к отправке не менее 100 событий, или

• Прошел один час с момента последней передачи.

После отправки данных соединение закрывается после получения успешного ответа.

Если сервер отвечает ошибкой 5xx, Pushwoosh повторит запрос в соответствии с определенной политикой повторных попыток.

Механизм повторных попыток

Попытка	Задержка
1-я	1 секунда
2-я	3 секунды после 1-й попытки
3-я	8 секунд после 2-й попытки

Если все повторные попытки не увенчаются успехом, запрос отбрасывается. Если ваша конечная точка продолжает возвращать ошибки в течение 24 часов и не принимает ни одного события, Pushwoosh приостанавливает интеграцию. См. Приостановленная интеграция.

Тайм-аут

Тайм-аут по умолчанию для запроса составляет 30 секунд. Его можно изменить по запросу через службу поддержки.

Посмотреть пример

gRPC

Тип транспорта gRPC использует двунаправленную потоковую передачу для передачи данных. Узнайте больше в документации gRPC.

Поток открывается при выполнении одного из следующих условий:

• Готово к доставке не менее 1000 событий
• Прошел один час с момента открытия последнего потока

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

Посмотреть спецификацию protobuf

Механизм повторных попыток
Каждое событие включает уникальный uuid. Если событие не удалось обработать:

1. Ответ должен содержать status, не равный "Success"
2. Должен быть включен оригинальный uuid из запроса

Pushwoosh повторит доставку на основе этого ответа.

Настройки соединения

Расширенные опции, такие как TLS, keep-alive или политики повторных попыток, настраиваются вручную через службу поддержки и могут потребовать участия разработчиков.

Включить post events

Этот переключатель по умолчанию выключен, поэтому передаются только события статистики коммуникаций. Чтобы также передавать события, которые ваше приложение отправляет в Pushwoosh через postEvent, включите переключатель Allow post events.

В появившемся поле Post events выберите, какие из событий вашего аккаунта передавать. При включенном переключателе требуется хотя бы одно событие. Если ваш аккаунт еще не отправлял никаких событий, этот список будет пуст, пока вы не вызовете postEvent хотя бы один раз.

Примечание

Post events отправляются на тот же Endpoint URL, который был введен выше, и достигают его независимо от платформы: разделы Platforms и Advanced filters ниже применяются только к событиям статистики коммуникаций, а не к post events.

Показы и клики in-app также передаются через этот поток post events — как PW_InAppShow и PW_InAppClicked. Каждое из этих событий появляется в списке Post events только после того, как оно хотя бы раз сработало для аккаунта, как и любое другое post event.

Выберите платформы

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

Поддерживаемые платформы:

• iOS, Android, macOS, Windows, Amazon, Safari
• Chrome, Firefox, Internet Explorer, Huawei
• Email, SMS, Line, Xiaomi, WhatsApp

Настройте расширенные фильтры

В разделе Advanced filters уточните критерии доставки событий с помощью фильтров:

• Live activity events: Включите, чтобы получать события live activity. Эти события содержат только метаданные, включая live_activity_id.

• Campaign filters: Фильтрация по коду кампании. Будут доставляться только события, связанные с этими кампаниями.

• Message filters: Фильтрация по коду сообщения. Будут доставляться только события, связанные с этими сообщениями.

После заполнения всех обязательных полей нажмите кнопку Apply, чтобы сохранить и активировать интеграцию.

Примечание

Изменения конфигурации вступят в силу в течение 15 минут после отправки.

Совет

Для расширенных настроек, таких как пользовательские тайм-ауты или конфигурации gRPC, пожалуйста, свяжитесь со службой поддержки.

Детали запроса и пример

Конечная точка	https://exampleclientendpoint.com/webhook_endpoint
HTTP-запрос	POST
Аутентификация	Нет
Тип запроса	Источник
Значение запроса	Отправка запросов на конечную точку веб-хука
Заголовки	Content-Type: application/json

Пример тела запроса

{
  "event_name": "Email Opened",
  "message_code": "E682-E6D92B9A-53E24868",
  "campaign_id": 961048,
  "platform": "Email",
  "payload": "Welcome to Headway! 👋",
  "application_code": "XXXXX-XXXXX",
  "hwid": "user@example.com",
  "user_id": "USER_ID",
  "timestamp": 1723799271,
  "journey_title": "",
  "journey_point_title": "5_Welcome_ID_new",
  "attributes": null
}

Атрибуты

Среди событий статистики коммуникаций attributes заполняется только для push-событий, с контентом, специфичным для канала (Android, iOS и т.д.) для платформы, на которую было отправлено push-уведомление. События Email и SMS содержат только поля верхнего уровня (event_name, platform, payload и т.д.). Для этих событий attributes имеет значение null. Внутри заполненного объекта attributes поля, не относящиеся к платформе события, опускаются, а не отправляются как пустые значения. Полный список полей см. в webhook.proto.

Post event несет свои пары ключ/значение атрибутов в attributes.event_attributes. message_code и payload остаются пустыми, потому что post event не привязан к сообщению или кампании.

Осторожно

attributes.geozone устарел: исходное свойство является объектом, а не числом, поэтому это поле никогда не содержало реального значения. Считывайте фактическую геозону из attributes.geozone_data. Старое поле остается в контракте для клиентов с существующими gRPC-заглушками.

Ответ
Тело ответа игнорируется. При транспорте HTTP код ответа определяет, считаются ли события доставленными. Код 2xx означает, что ваша конечная точка их приняла.

Синхронизация снятых с регистрации устройств с вашей системой

Если вы храните собственную копию списка устройств, например в CRM или платформе клиентских данных, передавайте post event PW_DeviceUnregistered, чтобы находить устройства, до которых Pushwoosh больше не может достучаться. Pushwoosh отправляет это событие, когда устройство теряет push-подписку. О причинах см. PW_DeviceUnregistered.

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

1. В настройках интеграции включите Allow post events. См. Включить post events.
2. В поле Post events выберите PW_DeviceUnregistered.
3. Чтобы также узнавать об устройствах, которые получают push-токен, выберите PW_DeviceRegistered.
4. Нажмите Apply. Изменение вступит в силу в течение 15 минут.

Как и любой post event, PW_DeviceUnregistered появляется в списке Post events только после того, как это событие хотя бы раз сработало для аккаунта. См. Включить post events.

При обработке событий учитывайте следующие ограничения:

• Сопоставляйте устройства по hwid или user_id, а не по push-токену. Событие содержит hwid, user_id и платформу устройства, но не содержит ни push-токена, ни причины снятия с регистрации. Истекший токен и снятие с регистрации через SDK выглядят одинаково.
• Новый токен для того же устройства не порождает событий. PW_DeviceRegistered срабатывает, только когда устройство без push-токена получает его. Список, в котором устройства хранятся по push-токену, сохраняет нерабочие токены, потому что, когда устройство получает новый токен, не срабатывает ни одно из событий.
• Отписка от email не удаляет устройство. Для email адрес остается на устройстве, а Pushwoosh только помечает его как отписанный. Если пользователь отписался по ссылке в письме, attributes.event_attributes также содержит message_code и campaign_id этого письма.

Некоторые события могут так и не дойти до вашей конечной точки, потому что пакет, для которого исчерпаны все повторные попытки HTTP, отбрасывается. Чтобы найти такие устройства, периодически экспортируйте сегмент устройств, на которые вы ориентируетесь, в CSV и сравнивайте его со своим списком устройств. Для экспорта сегмента в вашей роли нужно разрешение Personal data. Если ваша конечная точка продолжает возвращать ошибки в течение 24 часов, интеграция приостанавливается и события перестают поступать. См. Приостановленная интеграция.

Приостановленная интеграция

Если доставка на вашу конечную точку HTTP продолжает завершаться ошибкой в течение 24 часов и за это время конечная точка не принимает ни одного события, Pushwoosh приостанавливает интеграцию:

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

Событие считается принятым, когда ваша конечная точка возвращает код ответа 2xx. Частичные сбои не приостанавливают интеграцию: любое принятое событие запускает отсчет 24 часов заново. Интеграции с транспортом gRPC не приостанавливаются.

Чтобы возобновить передачу событий:

1. Убедитесь, что ваша конечная точка доступна и возвращает код ответа 2xx.
2. Перейдите в Settings > 3rd party Integrations, найдите Event streaming integration и нажмите Configure.
3. Нажмите Apply. Менять настройки не нужно. Передача событий возобновится в течение 15 минут.

Как узнать, что интеграция работает?

Вы начнете получать запросы от Pushwoosh на вашу настроенную конечную точку.