Meta Conversions API (CAPI): практическое руководство

Meta Conversions API (CAPI) позволяет вашему серверу отправлять события вроде Purchase прямо в Meta. Пиксель Meta отправляет те же события из браузера покупателя. CAPI отправляет их с вашего сервера, поэтому они доходят, даже когда блокировщик рекламы останавливает пиксель, cookie уже нет или страница благодарности не загрузилась.

В этом руководстве рассказано, что содержит событие Conversions API, как запускать его рядом с пикселем с одним event_id, какие параметры Meta требует и рекомендует, как тестировать через Test events и какие ошибки встречаются чаще всего.

Что такое Meta Conversions API?

Conversions API — часть Graph API Meta. Ваш сервер отправляет HTTPS POST-запрос на graph.facebook.com/VERSION/PIXEL_ID/events с токеном доступа и списком data из не более чем 1,000 событий. Каждое событие описывает одно действие, например покупку, в трёх частях: что произошло, кто это сделал и подробности.

Сокращённое событие Purchase выглядит так:

{
  "data": [{
    "event_name": "Purchase",
    "event_time": 1792929600,
    "event_id": "order-1042",
    "action_source": "website",
    "event_source_url": "https://yourstore.com/checkouts/thank-you",
    "user_data": {
      "em": ["<SHA-256 of the normalized email>"],
      "ph": ["<SHA-256 of the normalized phone>"],
      "client_ip_address": "203.0.113.24",
      "client_user_agent": "Mozilla/5.0 (iPhone; ...)",
      "fbp": "fb.1.1792928400000.1234567890",
      "fbc": "fb.1.1792928400000.AbCdEf123"
    },
    "custom_data": { "value": 74.00, "currency": "USD" }
  }]
}

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

Зачем запускать Conversions API рядом с пикселем?

Meta рекомендует запускать Conversions API вместе с пикселем и отправлять одни и те же события по обоим каналам. Каждая сторона видит то, чего не видит другая, а вместе они дают Meta более полные данные.

Цена работы обоих каналов в том, что Meta теперь получает по две копии каждого события. В следующем разделе показано, как Meta оставляет только одну.

Как работает дедупликация с одним event_id?

Meta считает событие из браузера и серверное событие одним и тем же событием, когда совпадают две вещи: название события и id события. В пикселе id передаётся в опции eventID. В Conversions API то же значение передаётся в event_id.

fbq('track', 'Purchase', { value: 74.00, currency: 'USD' }, { eventID: 'order-1042' });

Meta дедуплицирует совпадающую пару, только если две копии пришли с разницей не более 48 часов. На практике это обеспечивают несколько правил:

• Создавайте id один раз. Стройте его из того, что известно обеим сторонам, например из номера заказа, и передавайте и в браузер, и на сервер. Две системы, каждая из которых создаёт свой id, не совпадут.
• Используйте один формат. order-1042 и 1042 — это разные id.
• Точно совпадайте по имени события. Purchase и purchase — разные события.
• Отправляйте серверное событие вовремя. Серверное событие, которое пришло позже чем через 48 часов после события из браузера, засчитывается второй раз.

Meta описывает и второй метод, который сопоставляет события по fbp или external_id. По словам Meta, он, как правило, работает только когда событие из браузера приходит раньше серверного, поэтому общий event_id надёжнее. Если Meta всё равно показывает больше покупок, чем было в вашем магазине, в нашем руководстве о дублирующихся событиях покупки перечислены типичные причины.

Какие параметры обязательны, а какие рекомендуются?

Обязательные поля делают событие валидным. Рекомендуемые поля определяют, сколько ваших событий Meta сможет сопоставить с человеком, а для атрибуции и показа рекламы можно использовать только сопоставленные события.

Три детали вызывают большинство проблем:

• Нормализуйте до хеширования. Meta ожидает email без пробелов по краям и в нижнем регистре, а телефонные номера в виде цифр с кодом страны. Anna@Example.com и anna@example.com дают разные хеши, и совпасть может только второй.
• Не хешируйте идентификаторы браузера. fbp, fbc, IP-адрес и user agent передаются как есть.
• Сохраняйте click id в точности как есть. Значение fbc состоит из fb.1., времени создания в миллисекундах, точки и fbclid из URL лендинга. fbclid чувствителен к регистру. Сохраните его, когда посетитель попадает на сайт, потому что при оформлении заказа его в URL уже нет.

Насколько хорошо совпадают эти поля, измеряет оценка Event Match Quality в Meta. Наше руководство по Event Match Quality разбирает каждый параметр, правила хеширования и оценку, к которой стоит стремиться.

Как проверить события с помощью Test events?

В Events Manager есть вкладка Test events, которая показывает события по мере их поступления. Используйте её, прежде чем полагаться на новую настройку.

1. Откройте Test events

   В Events Manager выберите свой датасет (пиксель) и откройте вкладку Test events. Скопируйте тестовый код, который она показывает.

2. Добавьте код в серверные события

   Отправьте его как test_event_code в запросе. В ROASaurus вставьте его в поле Test event code пикселя Meta.

3. Оформите тестовый заказ

   Зайдите в магазин, добавьте товар и оплатите его, чтобы и пиксель, и сервер отправили Purchase.

4. Сравните две копии

   У обеих копий должны совпадать название события, id события, сумма и валюта.

5. Проверьте информацию о клиенте

   Серверное событие должно содержать хешированные email и телефон, IP-адрес, user agent и fbp, а также fbc, если визит начался с клика по рекламе.

6. Удалите тестовый код

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

Частые ошибки Conversions API и как их исправить

После нескольких дней живого трафика откройте вкладку Diagnostics в Events Manager. Meta перечисляет там проблемы и рекомендации по их исправлению. Затем сравните ежедневное число Purchase в Events Manager с числом оплаченных заказов в вашем магазине за те же дни. Если в Meta заметно больше, в нашей справочной статье о предотвращении двойного подсчёта перечислены настройки, которые нужно проверить.

Как настроить Conversions API с ROASaurus

ROASaurus отправляет события Conversions API из данных заказов вашего магазина, поэтому серверную часть не нужно создавать самим. В разделе Tracking & platforms нажмите Connect with Facebook и выберите свой рекламный аккаунт и пиксель либо вставьте id пикселя (датасета) и токен Conversions API. В руководстве по настройке Meta разобраны оба варианта, а на странице интеграции с Meta перечислены все отправляемые поля.

• Один id с обеих сторон. События браузера и сервера используют один id события. Для покупки это order- и следующий за ним id заказа.
• Короткая задержка перед покупкой. Серверный Purchase ждёт короткое время после поступления заказа, чтобы можно было сначала присоединить событие покупки из браузера. Тогда его IP-адрес, user agent и URL страницы уходят вместе с серверным событием, а также fbp и fbc, сохранённые для посетителя.
• Информация о клиенте из заказа. Email, телефон, имя и адрес нормализуются и хешируются с помощью SHA-256. Id клиента в магазине и id посетителя ROASaurus передаются в хешированном виде как external_id.
• События, которые Meta не сможет сопоставить, пропускаются. Событие, в котором нет ни fbc, ни fbp, ни email, ни телефона, ни IP-адреса, не отправляется.

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

Источники

1. Meta for Developers: Handling Duplicate Pixel and Conversions API Events
2. Meta for Developers: Server Event Parameters
3. Meta for Developers: Customer Information Parameters
4. Meta for Developers: Using the API - Conversions API
5. Meta for Developers: ClickID and the fbp and fbc Parameters

В ROASaurus

• Интеграция с Meta
• Справка: подключение Meta
• Справка: как избежать двойного учёта
• Серверный трекинг

Читайте дальше