Setup Conversions API As A Platform

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.

Server Events vs Browser 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:

• Server events use Pixel ID as the destination
• Server events are processed the same way browser Pixel events are once sent to Facebook
• Deduplication will be easier to implement
• Ease of use for clients. For example, server events can be sent alongside browser events by default.

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.

Prerequisites

1. A web platform able to share events to Facebook with user consent. For example, website builder, tag manager, or AdTech platform.
2. A Facebook representative
3. All of the same prerequisites for a direct server-side integration:
   • Business Manager
   • Facebook App
   • Facebook Pixel
   • Server Connection

Get Started

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:

• Go to Events Manager.
• Select Add New Data Source.

Step 4: Generate a System User Access Token.

Step 5: Send a server event to your Pixel.

Send Events On Behalf of Clients

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.

For pixels owned or managed by the partner's Business Manager

1. On Business Manager, go to the Users section and select the System User tab. Click on the specific system user you are using for Conversions API.
2. Go to the Assign Asset dialog and choose Pixels. Then, select the pixels for which you want to send events on behalf of.
3. For each pixel, select the Manage Pixel permission and click Save Changes.
4. Go back to your system user's details page. Verify that the selected pixels are visible there.

For pixels not managed by the partner

1. Option 1: Client system user access token [Manual approach, if you do not use FBE]
2. Option 2: Facebook Business Extension (FBE)

Option 1: Using client system user access token

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.

Implementation

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.

Option 2: Facebook Business Extension (FBE)

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.

Attribute Events to Your Platform Using 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.

Sample event payload

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"
}

Frequently Asked Questions