Setup Server-Side As A Platform

If you offer Facebook Pixel setup as part of your tag management services, you may want to consider adding server-side functionalities. Integration with the server-side API allows your customers to send web events to Facebook directly, without having to rely on browser pixel events.

Server-Side vs Browser Events

Before starting, it is important to understand the relationship between server-side events and the Facebook Pixel. Server-side events are 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-side 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 server-side 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-side events use Pixel ID as the destination
  • Server-side 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-side events can be sent alongside browser events by default.

Once your platform is integrated with the server-side 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 server-side.

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:

To start offering server-side as a functionality, your app needs to go through app review. During that process, you must request the ads_read permission.

Get Started

If this is your first time using the server-side 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 events via server-side 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: Create a non-admin system user:

  • Inside Business Manager, find Business Settings > System Users
  • Click to Add System User with a Manage App permission
  • Add Assets on your newly created system user
  • Select the App you created in Step 2

Step 5: Create Access Token with permissions on App

  • Select the system user you created in Step 4
  • Click Generate New Token
  • Select your App and add ads_read permission
  • Save the generated access token

Step 6: Send the Business, App, and Pixel IDs to your Facebook Representative. They grant these assets access to the server-side API.

Step 7: Send a server-side event to your Pixel

Send Events On Behalf of Clients

Once you have successfully sent a server-side event to your own Pixel, you have options on how to send events on behalf of your clients:

  1. Client system user access token [Recommended]
  2. Client shares Pixel to your Business Manager
  3. Use your own app's access token

Option 1: Using client system user access token [Recommended]

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-side events.

Implementation

Step 1: Ask your client to follow these steps to add a system user to their Business Manager.

Step 2: Ask your client to assign this system user to their Pixel and generate an access token.

Step 3: Ask your client to share this system user access token with you.

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: Client shares Pixel to your Business Manager

With this option, the client shares their Pixel to your Business Manager. Then, you can generate an access token to send server events.

Implementation

Step 1: Have the client share their pixel to your Business Manager.

Step 2: After Step 1 is completed, you will be able to send server-side events using the access token generated in Get Started.

Option 3: Use your own App access token

This option requires that your platform be added to the partner integration Toggle UI inside Events Manager.

Implementation

Step 1: All Pixels can see the following menu under their Pixel settings page in Events Manager. To add your Business as an option, speak with your Facebook representative.

Step 2: Once your business is added as an option, have the owner of the test Pixel use the toggle UI to turn on the integration for your business. For any pixels that turn on the integration, you can send server-side events using the access token generated in Get Started.

Testing the integration

To check that the integration is successful, make sure the following conditions are true:

  • Your platform's server-side API calls to the client Pixel using your app token return 200 HTTP response codes.
  • Your client is able to see server-side events in their Pixel dashboard inside Events Manager.

Attribute Events to Your Platform Using partner_agent

To attribute server-side 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.

Agent string format

The agent string is created by combining several components:

  • pl - Unless otherwise specified, prepend the agent string with pl to indicate the event is from a platform
  • PARTNER_NAME - Identifier for your platform
  • PLATFORM_VERSION - The runtime version of your platform
  • APP_VERSION - The version of your Facebook integration, if applicable

For example, if your platform name was "DataPartner" with a platform version of 1.0 and a Facebook App version of 2.0, the agent string should be formatted as follows:

    "pldatapartner-1.0-2.0"

Sample event payload

If your platform identifier is pldatapartner-1.0-2.0, 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": "pldatapartner-1.0-2.0"
}

Frequently Asked Questions

Sending events sent via server-side 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 server-side API? Here are some important use cases:

1. Capture offline and down-funnel events

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 server-side.

2. Signal Resiliency

Browser side events can be lost for many reasons:

  • The user might navigate away before the page has finished loading
  • Ad blockers could prevent the event from firing
  • The changing internet landscape might change the way inter-domain messages are sent

These examples can all be mitigated by sending events via the server-side API.

3. Sensitive Data

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 server-side.

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 server-side sources. For example, if:

  • One of the ways your customer ingests data into your platform is via a browser javascript tag
  • You send that data to Facebook via server-side API

The data is open to the browser-side risks mentioned in the question above.

To take full advantage of the server-side 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:

  • Send a test event via server-side API to the advertiser’s pixel
  • Look for a 200 return code
  • Update the status of the connection appropriately.

Facebook tries to deduplicate identical events sent through the Facebook Pixel and the server-side API. We determine if events are identical based on their ID and name. For more information, see Deduplicate Pixel and server-side 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_ids via browser or via Server-side 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-side event for that same user should also have external_id set to 123.