Facebook Pixel Server-Side Destination


Facebook Pixel Server-Side API allows advertisers to send events from their servers directly to Facebook. Server-Side events are linked to a pixel and are processed like browser pixel events. This means that Server-Side events are used in measurement, reporting, and optimization in the same way as browser pixel events.

The Facebook Pixel server-side component can be used in one of two ways:

  1. In addition to the existing Client-Side (web) Pixel.
  2. As a stand-alone, Server-Side only offering.

For beta-testing, we are releasing the Server-Side component as a standalone destination.

Other Facebook Destinations Supported by Segment

This page is about the Facebook Pixel Server-Side. For documentation on other Facebook destinations, including Facebook Pixel, see the pages linked below.

Facebook Destination Supported by Personas
Facebook App Events Yes
Facebook Offline Conversions Yes
Facebook Pixel No
Facebook Custom Audiences Yes

Getting Started

Set up in Facebook Events Manager

Before you begin:

  • Make sure the advertiser has set up a business.
  • Create a pixel and assign it to that business.

Once you have configured the business and pixel:

  1. Go to your Events Manager page and navigate to the pixel settings.
  2. Select your pixel (for example, Jasper’s Market Pixel).
  3. Select the Settings tab.
  4. Scroll down to Server-Side API for Web
  5. Toggle the Segment Partner Integration ‘On’

This section only appears if you enabled the Facebook Pixel Client-side integration (Facebook automatically gives you Server-Side API access overnight once enabled), and then contacted your Facebook Account Representative to get your Pixel ID whitelisted.

Learn more about your pixel event data in Events Manager in the Facebook Ads Help Center.

Set up in Segment

  1. Go to the Facebook Pixel Server-Side Destination catalog page and click Configure Facebook Pixel Server Side.

    The server-side destination is not visible in the catalog, as it is in private beta. Instead, go to: https://app.segment.com/goto-my-workspace/destinations/catalog/facebook-pixel-server-side

  2. Configure the destination’s settings:

    • Pixel ID (Required)
    • Map Categories to FB Content Types (Optional)
    • Map Your Events to Standard FB Events (Optional)

Track

Currently, Facebook Pixel Server-Side only supports Track calls.

If you’re not familiar with the Segment Specs, take a look to understand what the Track method does. An example call would look like:

analytics.track("My Custom Event", {
  checkinDate: new Date(),
  myCoolProperty: "foobar",
});

Mapping to Facebook Standard Events

To send Standard events (as opposed to “custom events”), use the Segment destination setting labeled Map Your Events to Standard FB Events. Then, when Segment receives an event that appears in that mapping, the event is sent to Facebook as the standard event you specified. All properties included in the event are sent as event properties. You learn more about these in the Facebook pixel standard events documentation.

In addition, Segment specially handles the following event types, and sends them as Standard events:

  • Order Completed is sent as Purchase
  • Product Added is sent as AddToCart
  • Product List Viewed is sent as ViewContent
  • Product Viewed is sent as ViewContent
  • Products Searched is sent as Search
  • Checkout Started is sent as InitiateCheckout

Facebook requires a currency for “Purchase” events – if you leave it out, Segment will set a default value of “USD”.

You can also use the “Map Your Events to Standard FB Events” setting to map any other events to one of Facebook’s Standard Events. Any unmapped events are automatically sent to Facebook Pixel Server-Side as a custom event.

Segment maps the following Segment traits to Facebook properties:

Segment Property Pixel Property Notes
event event_name  
messageId event_id  
timestamp event_time  
userId external_id Any unique ID from the advertiser, such as membership IDs, user IDs, and cookie IDs. See Alternative External IDs.
context.ip user_data.client_ip_address  
context.userAgent user_data.client_user_agent  
context.traits.email user_data.em hashed
context.traits.phone user_data.ph hashed
context.traits.firstName user_data.fn hashed
context.traits.lastName user_data.ln hashed
context.traits.address.city user_data.ct hashed
context.traits.address.postalCode user_data.zp hashed
context.traits.address.state user_data.st hashed
context.traits.birthday user_data.db hashed
properties.fbp fbp  
properties.fbc fbc  
properties.revenue custom_data.value Customizable, see Alternative Value Properties
properties.currency custom_data.currency Defaults to USD if not set
properties.products custom_data.contents Must be an array. num_items is set to the length of this
properties.products[x].price custom_data.contents[x].item_price Must be an integer
properties.products[x].product_id custom_data.contents[x].id Must be a string
properties.products[x].quantity custom_data.contents[x].quantity Must be an integer
properties.query custom_data.search_string  
properties.status custom_data.status  

To access the contexts and context.traits objects in a Track call, you can use the context-traits format as in the example below.

analytics.track("Clicked Email", {
    emailCampaign: 'First Touch'
},
{
    traits: {
        name: "John Doe"
    }
});

Any properties you send that aren’t listed above are sent in the ‘Custom Data’ part of the Segment payload to Facebook.

Alternative External IDs

By default, Segment sends the userID as externalID, and if userID is absent falls back to anonymousID. To use a different field in your payload as the external ID, use the “Alternative External ID Field”. Example values for this setting include context.traits.email and properties.externalid.

Alternative “Value” Properties

For most events Segment sends revenue for the Pixel value field, but for the pre-purchase events “Product Viewed” and “Product Added”, Segment uses the value of the “Value Field Identifier” setting to determine which property to use for the “value” field. This field defaults to price.

Limited Data Use

In July 2020, Facebook released Limited Data Use feature to help businesses comply with the California Consumer Privacy Act (CCPA). This feature limits the way user data is stored and processed for all California residents who opt out of the sale of their data. You can send Limited Data Use data processing parameters to Facebook on each event so that Facebook can appropriately apply the user’s data choice. Segment recommends that you first familiarize yourself on this feature and the Data Processing Options Facebook accepts.

This destination supports the following parameters:

  • Data Processing Options
  • Data Processing Options Country
  • Data Processing Options State

You can enable the feature using the Use Limited Data Use destination setting and control it using Data Processing Initialization Parameters.

The Use Limited Data Use destination setting is disabled by default for all Facebook destinations except for Facebook Pixel. This must be enabled manually from the destination settings if you’re using other Facebook destinations.

Data Processing Destination Setting

You can change the Use Limited Data Use destination setting to enable or disable Limited Data Use. This must be enabled (set to “on”) if you want to send data processing parameters as part of the the Limited Data Use feature.

Data Processing Initialization Parameters

The Data Processing parameters you set are the Data Processing Options Segment uses when sending data to Facebook. By default, Segment uses the following Data Processing Parameters:

Data Processing Parameter Default Value What it means
Data Processing Options ["LDU"] Use Facebook’s Limited Data Use processing
Data Processing Options Country 0 Use Facebook’s geolocation to determine country
Data Processing Options State 0 Use Facebook’s geolocation to determine state

Facebook uses the context.ip to determine the geolocation if it exists on the event.

You can manually change the Data Processing parameters by adding settings to the integrations object. The example below shows how you might set custom Data Processing parameters in Node.

// node.js library example

    analytics.track({
      event: 'Membership Upgraded',
      userId: '97234974',
      integrations: {
        "Facebook Pixel Server-Side": {
          "dataProcessingOptions": [[], 1,1000]
        }
      }
    })

Verify Events in Facebook

After you start sending events, you should start seeing them in twenty minutes. You can confirm that Facebook received them:

  1. Go to the Events Manager.
  2. Click on the corresponding pixel.
  3. In the Overview tab, look for events where the “Connection Mode” is Server.

Note: It might take a few minutes before events appear in the Events Manager.

This page was last modified: 29 Jul 2020

Get started with Segment

Segment is the easiest way to integrate your websites & mobile apps data to over 300 analytics and growth tools.
or
Create free account