Meta CAPI батчинг: пакетная отправка событий и лимиты

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

Требования к отдельным событиям - обязательные параметры, данные пользователя, хеширование - одинаковы независимо от того, отправляется событие поштучно или в пачке. Они подробно описаны в полном гайде по Meta CAPI. Здесь мы сосредоточимся именно на работе с группой событий.

Массив data: несколько событий в одном запросе

Тело запроса к Conversions API содержит параметр data - массив, в котором каждый элемент представляет событие со своими полями: event_name, event_time, event_id, user_data и custom_data. API принимает события в виде массива, даже если в запросе только одно событие.

Использование массива влияет на обработку ошибок. Если HTTP-запрос содержит несколько событий, правила проверки применяются ко всему запросу. Самое важное связано со временем: event_time не может отставать от момента отправки больше чем на 7 дней. Если хотя бы одно событие старше этого срока, Meta отклонит весь запрос и не сохранит ни одной записи (документация Using the API). Поэтому одна такая запись из повторного импорта CRM заблокирует отправку свежих конверсий.

Поэтому при пакетной отправке важно контролировать состав запроса и актуальность временных меток: от этого зависит, примет ли Meta события.

Правила приёма и проверки пакета

Каждый элемент внутри массива data проходит индивидуальную и групповую проверку:

1. Обязательные поля для каждого события. Для событий веб-сайта необходимы параметры action_source, event_source_url и client_user_agent. Эти поля задаются для каждого события индивидуально, а не на уровне всего запроса (параметры Conversions API).
2. Идентификация пользователя. Хешированные контакты, куки fbp/fbc (если они доступны) и неизменный event_id передаются в каждом событии отдельно для корректного сопоставления.
3. Временное окно для всего пакета. Ограничение в 7 дней для event_time критично для батчинга: весь пакет будет принят только в том случае, если валидна каждая входящая в него запись.

Представьте массив как конверт с несколькими письмами: Meta принимает или отклоняет его целиком, поэтому достаточно одного некорректного события, чтобы отклонили весь пакет.

Обработка ошибок: порядок повторной отправки

Ошибка при отправке пакета указывает на проблему в теле запроса, а код ответа Meta помогает найти причину. Если повторить тот же запрос без изменений, ошибка повторится. Действуйте так:

1. Разделите пакет пополам. Разбейте массив на две части и отправьте их отдельными запросами. Метод деления пополам позволяет изолировать проблемное событие за несколько шагов.
2. Исправьте или отправьте в карантин. Устаревший таймстамп не станет валидным при повторе: скорректируйте данные в источнике или переместите запись в карантинную очередь. Подробнее о причинах задержек читайте в руководстве по задержкам событий CAPI.
3. Повторно отправьте валидные события. Корректные события сохраняют свои уникальные идентификаторы event_id, поэтому повторная доставка не приведёт к их дублированию в Meta.
4. Устраните первопричину на стороне источника. Если пакеты регулярно отклоняются из-за старых событий, ищите причину выше по цепочке, например в загрузке исторических данных CRM или повторной синхронизации трекера. Используйте чек-лист поиска неисправностей постбеков вместо бесконечных повторных отправок.

Экспоненциальная задержка (backoff) эффективна при временных сетевых неполадках, тогда как повтор заведомо невалидного пакета лишь генерирует лишние отказы.

Контроль нагрузки: как соблюдать ограничения частоты

В документации Conversions API о пакетной отправке Meta не приводит точных числовых лимитов частоты. Поэтому надёжность доставки зависит от настройки процесса:

1. Формируйте пакеты по времени поступления событий. Группируйте события, которые поступают одновременно естественным образом (очередь постбеков, цикл синхронизации CRM). Не стоит искусственно копить огромные пакеты, где одна устаревшая запись заблокирует доставку свежих конверсий.
2. Сохраняйте неизменные идентификаторы между попытками. При повторной отправке после сбоя передавайте исходные значения event_id. Корректность учёта конверсий определяется правилами дедупликации Meta, а не количеством ваших попыток.
3. Контролируйте отправку на обоих уровнях. Журнал сервиса фиксирует исходящие запросы, а Events Manager показывает принятые данные в пределах документированного окна видимости (документация Get Started). Если расхождение между показателями растёт, возможно, Meta ограничивает частоту запросов.

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

Meta CAPI: вопросы о пакетной отправке

Источники