If you offer Facebook Pixel setup as part of your tag management services, you may want to consider adding conversions API functionalities. Integration with the Conversions API allows your customers to send web events to Facebook directly, without having to rely on browser pixel events.
Before starting, it is important to understand the relationship between server events and the Facebook Pixel. Server events are sent via Conversions API, and used in measurement, reporting, and optimization in the same way as browser pixel events.
If sending browser pixel events is like sending mail via airmail, then sending server events is like sending mail via freight. They are both mechanisms to transport the package (data about an event) to a destination address (a Pixel ID). So, we highly recommend that you build the Conversions API integration on your platform as an extension of your current Facebook Pixel offering (instead of a separate plugin or service) for the following reasons:
Once your platform is integrated with the Conversions API, we recommend sending the same web events via browser and server. This redundancy ensures maximum signal reliability. Events that previously could have been lost on the browser side, for a variety of network reasons, are now captured via conversions API.
To send events via browser and server, you must correctly set the same event_id
for corresponding events. This allows Facebook to properly deduplicate your events.
To start offering conversions API as a platform, your app needs to go through app review. During that process, you must request following access level, feature and permissions:
ads_management
, pages_read_engagement
, and ads_read
If this is your first time using the conversions API, follow these steps to create a Business, App, Pixel, and System User. Then, you will be able to use your system user's access token to send server events via conversions API.
Step 1: Create a Business.
Step 2: Create a Facebook App under your newly created Business.
Step 3: Create a Facebook Pixel under your newly created Business:
Step 4: Generate a System User Access Token.
Step 5: Send a server event to your Pixel.
Once you have successfully sent a server event to your own Pixel, you have options on how to send events on behalf of your clients.
System users are different from normal users because they represent servers and software, instead of people. A system user access token never expires, which makes these tokens ideal for sending server events.
Follow our Get Started documentation and request a system's user token from your advertiser. Remember to use your own pixel and access token for testing.
Facebook is currently building a framework to enable our partner platforms to automatically create system users in their client's Business Manager, and then retrieve that system user's access token. Until then, have your client send you the token manually.
With the Facebook Business Extension, you can convert an advertiser’s User Access Token to a Systems User Access Token using one additional API call.
If you are already using FBE, follow our documentation to know more, or contact your Facebook representative.
partner_agent
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. Work with your Facebook Representative to agree on an identifier for your platform. Then, send it with each server event.
If your platform identifier is datapartner
, this would be a sample purchase event payload sent on behalf of your client:
{ "data": [ { "user_data": { "em": "8159ea0e33c51a774b83104ee562784f9b1836c852102046e4bd8385706fe7ca" }, "event_name": "PageView", "event_time": 1579645238 }, { "user_data": { "em": "8159ea0e33c51a774b83104ee562784f9b1836c852102046e4bd8385706fe7ca" }, "custom_data": { "currency": "USD", "value": "50" }, "event_name": "Purchase", "event_time": 1579645238 } ], "partner_agent": "datapartner" }
Sending events sent via Conversions API is just like sending events via Pixel. The only difference is that the event is sent via the server, instead of the browser. So, why make an effort to integrate with the conversions API? Here are some important use cases:
If someone uses an advertisers’ website to sign up for a credit card, they can send events such as ViewContent, Application Start, and Application Submit via the browser to the Pixel. However, the end user still needs to be approved for this credit card. The Approval event happens offline and cannot be sent via browser. To register this final step, the advertiser can send the Approval via conversions API.
Browser side events can be lost for many reasons:
These examples can all be mitigated by sending events via the conversions API.
Many advertisers have expressed concerns about sharing data via the browser when that data could be seen or inspected. This can be mitigated by sending data via conversions API.
For example, advertisers may want to send data like profit margin or lifetime value (LTV) along with a purchase
event. This way, ads can be optimized towards a specific type of customer.
Since browser events are always vulnerable to the obstacles mentioned above, we recommend that you only send events collected from conversions API sources. For example, if:
The data is open to the browser-side risks mentioned in the question above.
To take full advantage of the conversions API, no part of the data flow should be reliant on the browser.We recommend that you provide advertisers with a way to test this connection on your own platform.
One way to do this is:
200
return codeFacebook tries to deduplicate identical events sent through the Facebook Pixel and the conversions API. We determine if events are identical based on their ID and name. For more information, see Deduplicate Pixel and server events.
An External ID is a string that represents a user on an advertiser's system. These IDs help improve ads attribution and create audiences.
You can send external_id
s via browser or via conversions API, but you must be consistent across channels. For example, if you send a browser Pixel event with external_id
set to 123
, your server event for that same user should also have external_id
set to 123
.