Что такое api conversions
Conversions API
The Conversions API creates a connection between an advertiser’s marketing data and the Facebook systems that optimize ad targeting, decrease cost per action and measure results. In the case of direct integrations, this entails establishing a connection between an advertiser’s server and Facebook.
Server events are linked to a Facebook pixel ID and are processed like web events sent via pixel. This means that web server events are used in measurement, reporting, and optimization in a similar way as browser pixel events.
For optimal ad performance, we recommend that advertisers implement the Conversions API alongside their Facebook pixel and follow other best practices.
Recommended Steps
Documentation
API Parameters
Required and optional parameters you can use to improve ads attribution and delivery optimization.
Payload Helper
See how your payload should be structured when it is sent to Facebook from your server.
Troubleshooting
Learn how to handle error codes returned by the Conversions API.
Subscription Lifecycle Events
For subscription advertisers. Prerequisites, required parameters, and reporting metrics for subscription events.
Resources
Facebook Pixel Events
Learn more about the Facebook pixel’s Standard Events and Custom Events.
Business Help Center
Playbook and Webinar
Data Processing Options
Learn more about the Limited Data Use feature and how to implement it for Conversions API.
Facebook Conversions API: настройка и использование
Facebook Conversions API – что это такое?
Conversions API (раньше называемое Server-Side API) – это функционал Facebook, который позволяет передавать данные напрямую со своего сервера на сервер Facebook.
Conversions API представляет собой в некотором роде альтернативу более привычному client-side подходу, при котором для отправки данных о событиях, совершенных пользователями на сайте, используется размещение на страницах сайта js-кода пикселя Facebook.
С помощью Conversions API можно настроить отслеживание события, которое происходит за пределами сайта, например, звонок. Также, используя Conversions API, можно отправлять в Facebook данные о переводе заявки из лида в клиента на основании этапов воронки в CRM-системе или факт реальной оплаты покупки, а не отправки транзакции на сайте.
На основании событий Conversions API, так же как и событий пикселя, можно проводить дальнейшую оптимизацию рекламных кампаний.
Особенно актуальным становится освоение Conversions API сейчас, когда ужесточается политика отслеживания данных пользователей (наверняка, уже все, кто работает в рекламном кабинете Facebook, столкнулись с оповещением об изменениях подхода Apple в отношении сбора данных пользователей устройств с iOS 14).
Подготовка к настройке Conversions API
Перед тем, как приступить к настройке, убедитесь, что у вас есть бизнес-менеджер (Business Manager) и пиксель Facebook.
Business Manager – это инструмент Facebook, позволяющий централизованно управлять различными рекламными объектами: кабинетами, страницами, каталогами и др. Если бизнес-менеджера нет, создайте его (инструкция).
Пиксель Facebook (Facebook Pixel) – это код отслеживания (фрагмент кода JavaScript), с помощью которого можно собирать информацию о посетителях сайта и использовать ее для создания аудиторий ремаркетинга и оптимизации рекламы в Facebook/Instagram. Если пикселя нет, необходимо его создать и установить на сайт (инструкция).
Настройка Conversions API
В разделе Events Manager
нужно добавить новое событие, выбрав в выпадающем списке «Использование API Conversions».
Далее появится окно с выбором способа настройки Conversions API – вручную или с использованием партнерской интеграции:
Проверить, доступна ли интеграция для нужной вам платформы, можно по этой ссылке. Если такой нет, выбираем «Внедрение API вручную». Далее пошагово нужно указать, какие события и какие параметры с этими событиями вы хотите отправлять в Facebook.
На последнем шаге вы можете выбрать отправить инструкции разработчику либо выполнить настройку самостоятельно.
При выборе самостоятельной настройки откроется руководство по реализации:
Генерация маркера доступа
Для реализации API запросов нам понадобится сгенерировать маркер доступа. Маркер доступа предоставляет доступ к Conversions API. Его нужно использовать при каждом вызове API.
Сгенерируйте маркер доступа, а затем скопируйте его и сохраните, так как маркер доступа в Facebook не сохраняется.
Если вдруг вы закрыли руководство или не сохранили маркер, ничего страшного, в меню генерации маркера можно перейти также в разделе «Events Manager» – «Настройки» – блок «API Conversions».
Отправка событий через API
Чтобы отправить свое первое тестовое событие, перейдите в Facebook Graph API Explorer.
Graph API Explorer – это инструмент Facebook, с помощью которого можно выполнять API запросы и проверять ответы на них. Руководство по работе с Graph API Explorer
Для отправки события нужно создать новый POST запрос.
Далее следует указать актуальную версию API (обычно она уже выбрана по умолчанию).
После версии API добавляем идентификатор пикселя и после него сегмент /events:
Идентификатор пикселя можно посмотреть в разделе настроек.
В поле «Маркер доступа» вставляем сгенерированный на прошлом шаге маркер:
Чтобы сформировать тело запроса, нужно переключиться на JSON
и в поле для ввода текста вставить свои данные. Чтобы не ошибиться при составлении тела запроса, удобно использовать Payload Helper. В меню слева можно указывать необходимые для вашего события параметры, а в меню справа автоматически будет формироваться нужный код в формате JSON.
Кроме того, в Payload Helper очень удобно, что при клике на «Получить код» открываются сгенерированные варианты кода на разных языках.
Сформированный JSON нужно скопировать в поле Graph API Explorer.
И, чтобы информация об отправленном событии отобразилась в режиме тестирования в Events Manager, после закрывающей квадратной скобки нужно добавить параметр «test_event_code» со значением, которое сгенерировано на вкладке тестирования серверных событий в Events Manager.
Кликаем на «Отправить».
Если запрос составлен корректно, то в окошке посредине появится информация о том, что событие получено.
Также тестовое событие появится на вкладке «Тестирование событий» в Events Manager
После того, как вы создали и протестировали отправку нужного события, вы можете реализовать отправку данных на реальном проекте сами либо составить ТЗ для разработчика, который поддерживает ваш проект.
Важно: для событий на сайте, передаваемых через API Conversions, обязательно указывать параметры client_user_agent, action_source и event_source_url. Для остальных типов событий достаточно указания параметра action_source.
С примерами отправки события покупки, реализованными на разных серверных языках, можно ознакомиться в этом разделе developers.
Полезные ссылки со справочной информацией по событиям и параметрам:
Дедупликация событий
Если с помощью пикселя Facebook и с помощью Conversions API отправляются одинаковые события, системой выполняется дедупликация, то есть удаление дубликатов. То, что события являются совпадающими, определяется на основании параметров «название события» и «ID события», поэтому во избежание дублирования данных, следует передавать эти параметры.
При отправке события, идентичного тому, что уже было отправлено, дубль будет удален, в режиме тестирования вы можете увидеть такое оповещение:
Get Started
This page describes the process of implementing the Conversions API and details implementation prerequisites. If you are a third-party partner offering Conversions API functionalities for advertisers, there are different requirements to get started
If your business has a firewall for outbound requests, see Crawler IPs and User Agents to get Facebook’s IP addresses. Be aware that the list of addresses changes often.
Process Overview
The process of setting up a Conversions API integration consists of the following high-level steps:
Integration Methods
There are several methods for integrating with the Conversions API, and they vary by level of effort, cost, and the features they enable. See this article for an overview of Conversions API setup options.
The primary focus of this developer documentation is building direct integrations
Requirements
Pixel ID
You must obtain a pixel ID to use the Conversions API. If you’ve already set up a pixel for your website, we recommend that you use the same pixel ID for your browser and server events.
Business Manager
You also need a Business Manager to use the API. Business Manager helps advertisers integrate Facebook marketing efforts across their business and with external partners. If you don’t have a Business Manager yet, see the Help Center article on how to Create a Business Manager.
Access Token
To use the Conversions API, you need an access token. There are two ways of getting your access token:
Via Events Manager (Recommended)
To use the Conversions API, you need to generate an access token, which is passed as a parameter in each API call. Inside Events Manager, follow these steps:
Step 3. Find the Conversions API section and click on the Generate access token link under Set up manually, and follow the instructions pop-up:
Note: The Generate access token link is only visible to users with developer privileges for the business. The link is hidden from other users.
Once you have your token, click on the Manage Integrations button in the Overview tab in Events Manager. In the pop-up screen, click the Manage button next to Conversions API. This will automatically create a Conversions API app and Conversions API system user for you. There is no need to go through App Review or request any permissions.
Using Your Own App
If you already have your own app and your own system user, you can generate your token inside Business Manager. To do that:
Your app does not need to go through App Review. You do not need to request any permissions.
Access tokens generated under the Conversions API settings tab in Events Manager are no longer restricted to using the newest Graph API version that was available at the time of token generation. Starting with v12.0, newly created access tokens can be used with all available Graph API versions.
Conversions API End-to-End Implementation
The Conversions API supports advertisers’ efforts to provide consumers with appropriate data transparency and control while also helping them to continue providing personal experiences. With the API, you can share data directly from your server, rather than through a browser.
Benefits of Integration
Deeper-Funnel Visibility: The Conversions API allows you to share a wider array of data when compared to the Facebook pixel. With the API, you can make decisions taking into account more information, such as CRM data, lower funnel events (including qualified leads), and multi-site conversion paths across a website and a physical location.
Data Control: When used via a Server-Only implementation (for example, without the Facebook pixel), the Conversions API gives you added control over what data you share. You can choose to append insights to your events, providing data such as product margins or historical information, like customer value scores.
Signal Reliability and Resiliency: Data sharing through the Conversions API may be more reliable than browser-based methods alone, like the Facebook pixel. The API is designed to be less susceptible to issues like a browser crash or connectivity problems. New industry data transmission restrictions may limit the efficacy of cookies and pixel tracking, so the Conversions API helps you have control on sharing signals that may no longer be captured by the pixel.
Overview
You can think about your Conversions API integration in two main stages:
The following is a snapshot of the complete integration process:
Select events to share with Facebook with user consent (if any).
Set up your business’ assets: Facebook pixel, Facebook Application, Business Manager, Server Connection, System User.
Once you are fully integrated, send enough automated funnel events to be considered fully onboarded. Then, optimize your match rate based on guidance from Event Match Quality.
Existing Pixel Users
If you have an existing Facebook pixel integration, the Conversion API integration should be built as an extension of the pixel integration, instead of as an entirely different connection.
General Consent
If you have logic for controlling consent with respect to sharing pixel data, use the same logic with respect to sharing data via Conversions API.
Alternatives
Preparation
Pick Your Integration Type
To start, select the integration option you would like to implement:
Redundant Setup (Recommended)
Send all events via both pixel and Conversions API. This is the recommended setup for those who would like to keep the pixel on their website, and are able to fully adopt the Conversions API.
To succeed, you must be able to generate a persistent event_id for both pixel and Conversions API events. This means sending the same event_name and event_id on both the pixel and the Conversions API event, in order to deduplicate identical events.
This setup provides performance on par or better than using only the browser pixel. The server can capture events that may not be tracked by the browser, such as purchases that occur on a separate website, lead conversions, or phone calls.
Split Setup
Send different types of events via pixel and Conversions API. For example, you could send PageView and ViewContent via pixel, and Lead or Purchase via Conversions API.
While this option is not as optimal as a redundant setup, you may consider it if you do not want to use a fully redundant setup. Take into consideration that you may need to complete additional work as browser changes are implemented.
Server-Only Implementation
Only send events through the Conversions API, instead of through the browser. We recommend implementing either a redundant setup or a split setup before switching to this approach.
Define Events to Send
Once you have chosen your integration approach, you can define which events you want to send. Signals are most useful if they are matched to Facebook user IDs, so it is important to think through what parameters you are sending us with an event and how often you would like to send them.
Event Options
Send events that are most relevant to your business. See a full list of supported standard and custom Facebook events.
Event Parameters
You can send multiple parameters inside each event. See parameters used by Conversions API to learn more about those fields.
Your unique ID for a specific customer.
A unique ID for a given event.
Used on event deduplication. This field is very important if you are sending events via both browser pixel and conversions API.
This implementation is limited to select Facebook partners. Contact your Facebook representative for access.
Used on purchase event deduplication, if you send events via both browser pixel and conversions API.
You can deduplicate purchase events within two windows: 48 hours (recommended) or 28 days. This is the window between the first and second instances of the same event.
Data Freshness
We recommend that you send events in real time or in batches based on a specific timeline via the Conversions API. Sending your events in real time or within 1 hour helps ensure that they can be used for attribution and optimized for ad delivery.
Sending your events more than 2 hours after they occurred can cause a significant decrease in performance for ads optimized for those events. Events sent with a delay of 24 hours or more may experience significant issues with attribution and optimized ad delivery.
If you’re sending events with long conversion windows, send the event as close to real time as possible from the point at which the full conversion is completed.
Move on to the next step once you have:
Available Optimization Types
The Conversions API offers the following optimization types:
Optimize ad delivery to show ads to people most likely to make a conversion.
Value Optimization (also known as Return on Ads Spend Optimization)
Dynamic Product Ads
Optimize ad delivery to show ads for specific products to people most likely to purchase those specific products.
Execution
There are two ways to implement your integration:
Advertisers using conversions API through one of our marketing partners should follow our partner’s implementation guidelines.
Direct Integration
Step 1: Set Up Requirements
Prior to using the Conversions API, set up the following assets:
When you send events through the Conversions API, they’re processed and stored in the same way as the events you send through your pixel. When you implement the Conversions API, you select which pixel you want to send your events to.
Sending your Conversions API events to a pixel lets you use your Conversions API events in the same way you use your browser-based pixel events for measurement, attribution, and ad delivery optimization. We recommend sending events from the browser and your server to the same Facebook pixel ID.
You need a Business Manager to use the API. Business Manager helps advertisers integrate Facebook marketing efforts across their business and with external partners. If you don’t have a Business Manager, see the Help Center article on how to Create a Business Manager.
To use the Conversions API, you need an access token. There are two ways of getting your access token:
Move on to Implement the API once you have the assets ready. Remember to save IDs for your assets, since you use those on your API calls.
Step 2: Implement the API
Once you are done with the requirements, start the implementation process. While building on the Conversions API, always check the developer documentation.
Test Calls (Optional)
If this is your first time using the API, start with a test call. To do that, you need a payload and a method for making API calls. After the call is completed, check Events Manager to verify the call worked as expected.
Use the Payload Helper to generate a sample payload to be sent with your call. Follow the instructions listed on the tool. Your payload should look something like this:
If you want to test your payload from the Payload Helper, add your pixel ID under Test this Payload and click on Send to Test Events. You should be able to see the event on Events Manager > Your Pixel > Test Events. Learn more about the Test Events Tool.
Once you are satisfied with your payload, decide how you want to make your call. You can use our Graph API Explorer (see Guide) or your own servers. If you are using your servers, you can use CURL or the Facebook SDK—We highly recommend using the SDK.
Independently on your call method, you should call the /
After you complete your first call, verify your events on Events Manager > Your Pixel > Overview.
Move on to Send and Verify Events once you have checked your test events in Events Manager.
Send and Verify Events
To start sending events, make a POST request to the API’s /events edge. Attach a payload to your call —if you need help generating your payload, visit the Payload Helper. See the following resources for more information and code samples:
After you start sending events, go to Events Manager and confirm that we have received the events you sent. Learn how to Verify Your Events.
If your implementation is complementary to a browser pixel, move on to deduplication settings. Otherwise, you are all set! Check Support if you still have questions.
Step 3: Add Parameters for Deduplication
If you’re sending identical events from your pixel and through the Conversions API, you need to set up deduplication for your events sent via both channels. First, read developer documentation to understand the deduplication logic.
Event-based deduplication
To help ensure your events are deduplicated:
Alternative to event-based deduplication
While Event ID will always be the best way to deduplicate events, it’s a fairly complex implementation. You can leverage alternative solutions by using external_id or fbp parameters. If you have configured the external_id or fbp parameters to be passed via both browser and server, we will deduplicate events automatically if we see the same event with same external_id or fbp parameters within 48 hours.
Optional Step 4: Explore Business SDK Features
The Facebook Business SDK has advanced features designed especially for Conversions API users:
Integration as a Platform
The following instructions are for partners offering conversions API as a service to advertisers.
Step 1: Set Up Requirements
Your app should get the following features and permissions:
Step 2: Send Events on Behalf of Clients
First, follow the direct integration steps and test your integration. Then, you can request authorization to send events on behalf of your clients. You have the following authentication options:
Facebook Business Extension (FBE) Approach (Recommended)
FBE returns all the necessary information needed to send events on behalf of the client via the following process. FBE provides an endpoint to retrieve system user access tokens created in the client’s Business Manager. This process includes permissions to send server events and is done automatically and in a secured way.
The endpoint requires an user access token as input parameter. For new FBE users, call this endpoint the endpoint to fetch the system user access token after you finish setting up FBE. Existing users need to ask for re-authentication before calling the new API endpoint.
Client system user access token
Have your client manually create a System User Access Token via Conversions API inside the Pixel Settings. Then, send events to the advertiser’s Pixel with that token.
A system user or an admin system user must install the app that will be used to generate the access token. With this setup, your app is allowed to call APIs on behalf of this system user or admin system user.
Client shares pixel to partner’s Business Manager
With this option, the client shares their pixel to partner via Business Manager settings or via API, then you can assign the partner system user to the client pixel and you can generate an access token to send server events.
Step 3: Attribute Events to Your Platform
To attribute conversions API events to your platform, use the partner_agent field. This allows you to set your own platform identifier when sending events on behalf of a client. If you are a managed partner, work with your Facebook Representative to agree on an identifier for your platform. This value should be in a format that is less than 23 characters and includes at least two alphabetical characters. Then, send it with each server event.
Always provide an up-to-date setup guide for advertisers looking to activate the integration on your platform.