События Reddit Conversions API: все поля пейлоада v3

События Reddit Conversions API уезжают одним POST на https://ads-api.reddit.com/api/v3/pixels/<pixel_id>/conversion_events, и всё событие живёт внутри одного элемента массива events. Схема компактная - таймстамп, action source, тип, опциональные объекты metadata и user, - но каждое поле несёт документированные правила, и отклоняются почти всегда те payload, которые одно из них проигнорировали.

Массив events и его обязательная рамка

Референс-сэмпл Reddit показывает рамку: объект верхнего уровня data с массивом events, где каждый элемент - одна конверсия. Запрос авторизуется conversion access token в bearer-заголовке и возвращает подтверждение об обработанных событиях. Батчинг ограничен 1,000 событий на вызов, платформенные потолки - 1,000 запросов и 10,000 событий в секунду: для одной воронки огромный запас, актуальный при разгребке бэклога трекера после простоя. Каждое событие также обязано уважать правило свежести: event_at не старше семи дней на момент отправки.

event_at, action_source и event_source_url

event_at - таймстамп конверсии; именно к нему применяется семидневное окно, поэтому задержавшийся постбек поднимается в течение недели, но не после. action_source сообщает, где случилась конверсия: WEBSITE, PHYSICAL_STORE или app-источник. Выбор не косметический: Reddit заявляет, что события PHYSICAL_STORE не должны нести device-идентификаторы - ни click ID, ни UUID, ни мобильные рекламные ID, - потому что у магазина нет устройства, которое можно опознать.

event_source_url рекомендован для WEBSITE-событий: Reddit извлекает из него домен для отчётности, а - полезный фолбэк - click ID, найденный в URL, подхватывается, когда специализированное поле click_id пусто.

type и tracking_type: имя конверсии

Объект type несёт tracking_type; сэмпл Reddit показывает значения PURCHASE, LEAD и PAGE_VISIT; всё, чего в перечислении нет, уходит как CUSTOM с custom_event_name до 64 регистрозависимых UTF-8 символов. Дашборд показывает только 20 последних кастомных событий - схема, которая постоянно ротирует имена, вымывает старые из интерфейса. Здесь же важна версионная дисциплина: tracking_type входил в поля, изменившиеся между CAPI v2 и v3, и отправка одних конверсий через обе версии удваивает их счёт.

metadata и user: выручка, идентичность, match keys

Объект metadata несёт бизнес-поля конверсии - conversion_id, currency, value - и именно conversion_id предпочитает дедупликация Reddit: уникальный идентификатор на отдельную конверсию, одинаковый у каждого канала, сообщающего об этой конверсии. В user едут match keys: ip_address, external_id, хешированные email и телефон, мобильные ID - идентификаторы, которые Reddit матчит с реальными профилями; IP-адрес и click ID настойчиво рекомендованы. Хеширование следует строгой канонизации; кроссплатформенная картина - в match keys - ключах сопоставления.

{
  "data": {
    "events": [
      {
        "click_id": "3184742045291813272",
        "event_at": 1790000000000,
        "action_source": "WEBSITE",
        "event_source_url": "https://www.example.com/checkout?rdt_cid=3184742045291813272",
        "type": { "tracking_type": "PURCHASE" },
        "metadata": { "conversion_id": "order-8842", "currency": "USD", "value": 49.9 },
        "user": { "ip_address": "192.0.2.1", "external_id": "7c73f2ae-a433-4d7b-9838-f467da98f48e" }
      }
    ]
  }
}

Пейлоад повторяет референс-сэмпл Reddit: одна конверсия, вся обязательная рамка, оба семейства идентификаторов на месте - conversion_id в metadata, click ID на верхнем уровне события и пользовательские идентификаторы в user.

Правила, которые молча ломают payload

Каждая из них приезжает с документированной ошибкой или предупреждением; ответы и фиксы - в гайде ошибки Reddit Conversions API. Контекст всей интеграции с креденшелами - в настройке Reddit Conversions API, карта кластера - в полном руководстве.

Sources