Полное руководство по внедрению Conversions API

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

Преимущества интеграции

• Видимость более глубоких уровней воронки. С Conversions API вы можете обмениваться более крупными массивами данных (по сравнению с пикселем Meta), а также принимать решения на основании дополнительной информации, такой как данные CRM, события из нижней части воронки (в том числе качественные лиды) и пути конверсии (как на сайте, так и в физической точке).

• Контроль данных. При использовании Conversions API только для сервера (без пикселя Meta) вы получаете дополнительный контроль над данными, которыми делитесь. Вы можете дополнять события аналитическими (такими как маржа товара) или историческими данными (например, информацией о ценности клиентов).

• Надежность и устойчивость сигнала. Обмен данными через Conversions API происходит надежнее, чем через браузерные инструменты (такие как пиксель Meta). Благодаря своей структуре этот API меньше подвержен таким неполадкам, как сбои браузера или проблемы с подключением. Новые отраслевые ограничения на передачу данных снижают эффективность отслеживания с помощью пикселя и файлов cookie. В свете этого Conversions API позволяет контролировать обмен сигналами, которые пиксель не регистрирует.

Обзор

Интеграция Conversions API проводится в два основных этапа:

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

• Выполнение. Внедрите API, следуя инструкции. На этом этапе также можно использовать партнерскую интеграцию.

Краткий обзор процесса интеграции:

Существующие пользователи пикселя

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

Общее согласие

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

Другие варианты

• Чтобы оптимизировать рекламу для событий в приложении, воспользуйтесь App Events API.

Подготовка

Выбор варианта интеграции

Для начала выберите подходящий вариант интеграции.

Определение событий для отправки

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

Варианты событий

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

Параметры событий

В каждое событие можно добавить несколько параметров. Подробную информацию о параметрах для Conversions API см. в этой статье.

В события можно добавлять ID разных типов, в том числе event_id, external_id и order_id. Очень важно знать разницу между этими параметрами.

Регулярность обновления данных

События через Conversions API лучше отправлять в режиме реального времени либо формировать из них группы по определенным временным периодам. Советуем отправлять события в режиме реального времени или в течение 1 часа после их регистрации. Так вы сможете использовать их для атрибуции и создания оптимизированной рекламы.

Отправка событий с задержкой на 2 часа и более может снизить результативность оптимизированной рекламы. Отправка событий с задержкой на 24 часа и более может привести к серьезным проблемам с атрибуцией и оптимизацией показа рекламы.

Отправлять события с продолжительными окнами конверсии нужно как можно скорее после полного завершения конверсии.

Переходите к следующему шагу, только если:

• у вас готов список событий для отправки;
• у вас готов список полей для отправки с событиями;
• вы определили, с какой частотой будете отправлять события.

Возможные типы оптимизации

Conversions API предлагает следующие типы оптимизации:

Выполнение

Существует два способа внедрения интеграции:

• прямая интеграция (если вы рекламодатель и внедряете Conversions API напрямую);
• интеграция в качестве платформы (если вы партнер по маркетингу и предлагаете сервис Conversions API своим клиентам).

Прямая интеграция

Шаг 1. Предварительные действия

Перед использованием Conversions API нужно настроить следующие объекты:

Переходите к шагу Внедрение API, только когда подготовите все необходимые объекты. Сохраните ID объектов: они понадобятся при выполнении вызовов API.

Шаг 2. Внедрение API

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

Тестовые вызовы (необязательно)

Начинать знакомство с API лучше с тестового вызова. Подготовьте полезные данные и выберите способ его выполнения. После завершения вызова перейдите в Events Manager и убедитесь, что он прошел успешно.

{
  "data": [
   {
    "event_name": "Purchase",
    "event_time": 1601673450,
    "user_data": {
      "em": "7b17fb0bd173f625b58636fb796407c22b3d16fc78302d79f0fd30c2fc2fc068",
      "ph": null
     },
    "custom_data": {
      "currency": "USD",
      "value": "142.52"
    }
   }
  ]
}

{
  "events_received": 1,
  "messages": [],
  "fbtrace_id": <FB-TRACE-ID>
}

Выполнив первый вызов, изучите события в разделе Events Manager > Мой пиксель > Обзор.

Переходите к шагу Отправка и проверка событий, только когда проверите тестовые события в Events Manager.

Отправка и проверка событий

Чтобы начать отправлять события, выполните запрос POST к границе контекста /events API. Прикрепите к вызову полезные данные (сгенерировать их можно в помощнике). Ресурсы с дополнительной информацией и примерами кода:

• Использование API > Отправка запросов
• Отброшенные события
• Время загрузки и время транзакции события
• Пакетные запросы
• Хэширование

После отправки событий перейдите в Events Manager и проверьте, получили ли мы их. Подробную информацию о проверке событий см. в этом разделе.

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

Шаг 3. Добавление параметров для дедупликации

Если вы отправляете идентичные события через пиксель и Conversions API, для них необходимо настроить дедупликацию. Чтобы понять логику дедупликации, ознакомьтесь с документацией для разработчиков.

Дедупликация на основании событий

Если в течение 48 часов на один и тот же ID пикселя будут отправлены события с одинаковыми значениями параметров сервера (event_id, event_name) и браузера (eventID, event), более поздние из таких событий будут сброшены.

Чтобы гарантировать дедупликацию событий, следуйте этим инструкциям.

• Убедитесь, что для следующих параметров установлено одно и то же значение:

  • event_id в серверном событии и eventID в браузерном;
  • event_name в серверном и браузерном событиях.
• Завершив дедупликацию, перейдите в Events Manager и проверьте, правильно ли сброшены события.
• Убедитесь, что у каждого уникального события, отправленного через пиксель и Conversions API, есть собственное значение event_id. Это значение не должно использоваться в других событиях.

Другие способы дедупликации на основании событий

Использование ID событий — самый эффективный способ дедупликации, но реализовать его довольно сложно. Вы можете использовать альтернативные решения, а также параметры external_id или fbp. Если в течение 48 часов после получения первого события мы обнаружим другое, параметры external_id или fbp которого соответствуют параметрам первого, то автоматически дедуплицируем их.

Шаг 4. Знакомство с функциями Business SDK (необязательно)

В Meta Business SDK имеются расширенные функции специально для пользователей Conversions API:

• Асинхронные запросы позволяют предотвратить блокировку программ во время ожидания обработки запросов. При таком подходе вы получаете сигнал от сервера сразу после завершения обработки запроса. В ожидании ответа программа может продолжать работу.
• Одновременная пакетная отправка позволяет использовать асинхронные запросы, чтобы увеличить пропускную способность за счет более эффективного расходования ресурсов. Создавайте пакетные запросы для запросов событий, cron-заданий и не только.
• Интерфейс HTTP-сервиса позволяет отказаться от HTTP-сервиса, предлагаемого Business SDK по умолчанию, и внедрить собственный, используя библиотеку или любой другой нужный способ.

Интеграция в качестве платформы

Ниже приведены инструкции для партнеров, которые предлагают сервис Conversions API рекламодателям.

Шаг 1. Предварительные действия

Ваше приложение должно получить следующие разрешения и доступ к функциям:

• расширенный доступ;
• функция стандартного доступа к управлению рекламой;
• разрешения ads_management, pages_read_engagement и ads_read.

Шаг 2. Отправка событий от имени клиентов

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

Расширение Meta Business (рекомендуется)

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

В качестве входного параметра конечная точка запрашивает маркер доступа пользователя. После завершения настройки расширения Meta Business новые пользователи должны выполнить вызов к этой конечной точке, чтобы получить маркер доступа системного пользователя. Чтобы вызвать новую конечную точку API, существующие пользователи должны запросить разрешение повторно.

Маркер доступа пользователя клиентской системы

Попросите клиента создать маркер доступа системного пользователя вручную (через Conversions API в настройках пикселя). Затем отправьте события с этим маркером пикселю рекламодателя.

Системный пользователь или администратор должен установить приложение, которое будет использоваться для создания маркера доступа. Тем самым вы разрешите приложению вызывать API от имени этого человека.

Передача пикселя клиента в аккаунт Business Manager партнера

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

Шаг 3. Атрибуция событий на платформе

Для атрибуции событий API на платформе можно использовать поле partner_agent. При отправке событий от имени клиента в нем можно указать уникальный идентификатор платформы. Управляемым партнерам рекомендуем согласовать идентификатор платформы со своим представителем Meta. Это значение должно содержать не более 23 символов, среди них минимум две буквы. Его нужно отправлять с каждым событием сервера.

Поддержка

Для всех партнеров

Информация об отладке и статьи Справочного центра для бизнеса.

Для управляемых партнеров

Чтобы ваш представитель Meta помог вам протестировать интеграцию и устранить неполадки, предоставьте ему ID Business Manager, ID приложения и ID пикселя.

Документация по API

• Начало работы: тестирование API в аккаунте Business Manager
• Использование API
• Рекомендации: Conversions API
• Настройка Conversions API в качестве платформы
• Стандартные события Meta
• Пользовательские события Meta
• Параметры
• Помощник по полезным данным
• Параметры обработки данных Conversions API и Offline Conversions API
• Использование App Events API для оптимизации событий в приложении
• Использование Offline Conversions API для получения событий продаж в точках (для офлайн-событий, не относящихся к продажам в точках, можно использовать Conversions API)