Meta Conversions API: как настроить и избежать дублей событий

Коротко: как это работает

Meta Conversions API (CAPI) — это передача событий (заявка, покупка, регистрация) в Meta не из браузера, а с сервера. Обычно CAPI работает вместе с пикселем:

• пиксель ловит события в браузере и даёт данные о поведении на сайте;
• CAPI отправляет те же события с сервера и доставляет их, даже когда браузерный запрос заблокирован или потерян;
• Meta дедуплицирует пары событий и считает каждое один раз — если вы передали одинаковые идентификаторы.

Плюс сервер может отправлять события, которых в браузере нет вовсе: например, оплату, подтверждённую в CRM.

Варианты подключения

Дедупликация через event_id

Meta считает два события дублями, если у них совпадают event_name и event_id и они пришли с одного пикселя. Значит, ID нужно сгенерировать один раз и передать в оба канала.

В браузере:

const eventId = crypto.randomUUID();
fbq('track', 'Lead', { value: 0, currency: 'USD' }, { eventID: eventId });
// тот же eventId отправляется на ваш сервер вместе с данными формы

На сервере то же значение уходит в поле event_id:

{
  "data": [{
    "event_name": "Lead",
    "event_time": 1760000000,
    "event_id": "тот-же-uuid",
    "action_source": "website",
    "event_source_url": "https://example.com/contacts",
    "user_data": {
      "em": ["<sha256 email>"],
      "ph": ["<sha256 phone>"],
      "client_ip_address": "203.0.113.10",
      "client_user_agent": "Mozilla/5.0 ...",
      "fbp": "fb.1.1700000000000.123456789",
      "fbc": "fb.1.1700000000000.AbCdEf"
    }
  }]
}

Частые причины дублей: разное написание имени события (Lead и lead), event_id генерируется отдельно в браузере и на сервере, серверное событие уходит со слишком большой задержкой.

Event Match Quality

Event Match Quality (EMQ) — оценка в Events Manager, которая показывает, насколько хорошо Meta может сопоставить ваши серверные события с аккаунтами пользователей. Чем она выше, тем точнее атрибуция и оптимизация.

Как улучшить:

• передавайте email и телефон, когда пользователь их оставил;
• передавайте fbp (cookie _fbp) и fbc (cookie _fbc или параметр fbclid из URL);
• добавляйте IP-адрес и user agent клиента, а не вашего сервера;
• используйте external_id — ваш внутренний ID пользователя, одинаковый в пикселе и CAPI.

Хеширование данных клиента

Персональные данные (email, телефон, имя, город и др.) нужно нормализовать и захешировать SHA-256 перед отправкой. Не хешируются: IP, user agent, fbp, fbc.

import { createHash } from 'node:crypto';

const sha256 = (v) => createHash('sha256').update(v).digest('hex');

const em = sha256(' User@Example.com '.trim().toLowerCase());
const ph = sha256('+998 90 123-45-67'.replace(/\D/g, '')); // только цифры с кодом страны

Ошибка нормализации (пробел, заглавная буква, плюс в номере) даёт другой хеш, и совпадения не будет.

Проверка в Events Manager

1. Откройте Test Events, возьмите test_event_code и добавьте его в серверный запрос на время отладки.
2. Совершите действие на сайте и убедитесь, что событие пришло и от браузера, и от сервера.
3. В деталях события проверьте статус дедупликации: пара должна быть отмечена как обработанная.
4. Через некоторое время посмотрите EMQ и вкладку Diagnostics с ошибками и рекомендациями.
5. Уберите test_event_code перед запуском в продакшен.

Подробности формата запроса — в документации Meta.