Facebook Pixel Destination

Destination Info

• Accepts Page, Identify, and Track calls
• Refer to it as Facebook Pixel in the Integrations object

Components

• Browser

Connection Modes

Device-mode	Cloud-mode
Web	Web
Mobile	Mobile
Server	Server

Facebook Pixel lets you measure and optimize the performance of your Facebook Ads, making conversion tracking, optimization and remarketing easier than ever. The Facebook Pixel Destination is open-source. You can browse the code on GitHub.

Use cases

• Increase conversions by retargeting shopping cart abandoners on Facebook

Other Facebook Destinations supported by Segment

This page is about the Facebook Pixel destination. For documentation on other Facebook destinations, see the pages linked below.

Getting started

1. From the Segment web app, click Catalog.
2. Search for “Facebook Pixel” in the Catalog, select it, and choose which of your sources to connect the destination to.
3. In the destination settings, enter your pixelId from the Pixels tab in Facebook Ads Manager.

When you enable Facebook Pixel as a destination in your Segment workspace, Segment automatically initializes Facebook’s pixel with your pixelId upon loading analytics.js. This means you should remove the native Facebook script from your page.

Page

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

analytics.page();

Segment maps analytics.page() to Facebook’s fbq('track', "PageView") method and will forward all page views accordingly. The integration will ignore any parameters you pass to analytics.page().

Identify

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

analytics.identify('ze8rt1u89', {
  name: 'Zaphod Kim',
  gender: 'Male',
  email: 'jane.kim@example.com',
  phone: '1-401-555-4421',
  address: {
    city: 'San Francisco',
    state: 'Ca',
    postalCode: '94107'
  }
});

When you make an Identify call with Segment, it will update Facebook Pixel the next time the user loads a page on your website. Facebook Pixel does not support immediately updating user properties using Identify. When you perform an Identify call in Segment, it will update in Facebook Pixel using their Advanced Matching feature.

Track

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",
});

Segment’s analytics.js client-side integration supports all three documented methods of sending events to Facebook.

At any time, you can define a custom contentType on the integration options. If the value is present, it takes precedence over any other setting or default value.

analytics.track('Checkout Started', {
    revenue: 2,
    products: [{
      id: "FB_product_1234",
      currency: "USD",
      category: "tshirts",
      quantity: 1,
      price: 2
    }]
  },
  { 'Facebook Pixel': { contentType: 'mycustomtype' } }
);

Standard events

To send Standard events, use the Segment destination setting labeled “Map Your Events to Standard FB Events”. Then, any time Segment receives one of the events in that mapping, it will be sent to Facebook as the standard event you specified. All properties you included in the event will be sent as event properties. For more information, view Meta’s conversion tracking documentation.

In addition, Segment sends the following event types as Standard events:

• Order Completed, which Segment sends as Purchase
• Product Added, which Segment sends as AddToCart
• Product List Viewed, which Segment sends as ViewContent
• Product Viewed, which Segment sends as ViewContent
• Products Searched, which Segment sends as Search
• Checkout Started, which Segment sends as InitiateCheckout

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

You can set custom properties for the events listed above. Use the setting “Standard Events custom properties” to list all the properties you want to send.

Here is how you’d specify standard events in the settings view:

You can map more than one Track event to the same Facebook standard event.

Legacy events

To send Legacy Conversion events, use the Segment setting called “Legacy Conversion Pixel IDs”. Any events that appear in that mapping will be sent to Facebook with the specified Pixel ID used as the Facebook Pixel eventName. Conversion events only support currency and value as event properties, so only these will be associated with the event. currency will default to USD if left out.

Custom events

To send Custom events, send any event that does not appear in either mapping. All properties you include in the event are included as event properties. Segment sends any events you don’t add to the “Map Your Events to Standard FB Events” setting to Facebook as a custom event. There is no setting to add custom events in the Facebook Pixel Destination configuration.

Timestamps

Facebook Pixel uses a custom timestamp format: an ISO 8601 timestamp without timezone information. For the following event fields, if you pass in a JavaScript Date object, it will be converted to this custom format. If you pass in a string, Segment assumes that the string is already formatted as Facebook expects:

• checkinDate
• checkoutDate
• departingArrivalDate
• departingDepartureDate
• returningArrivalDate
• returningDepartureDate
• travelEnd
• travelStart

Advanced matching

The Segment Facebook Pixel integration supports Advanced Matching, which enables you to send your customer data through the pixel to match more website actions with Facebook users. With this additional data, you can report and optimize your ads for more conversions and build larger re-marketing audiences. When the page loads, and before Segment fires off the pixels, Segment checks for traits that the user has been previously identified with and sends that along with each call.

Facebook accepts the following properties:

• First name
• Last name
• Email
• Phone number
• Gender
• Birthday
• City
• State
• Zip code

If you follow Segment’s spec, these properties send in the correct format.

When you use Advanced Matching, Facebook also accepts an external_id. This can be any unique ID from the advertiser, like loyalty membership IDs, user IDs, and external cookie IDs. To send an external_id to Facebook you can either:

• Send the Segment userId or anonymousId as external_id using the Use User ID or Anonymous ID as External ID setting
• Indicate which user trait you would like Segment to map to external_id using the Advanced Match Trait Key for External ID setting

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.

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:

Facebook uses context.ip to determine event geolocation.

You can manually change the Data Processing parameters by adding settings to the integrations object. For Facebook Pixel, you must store these settings in the Load object so that Segment can set them before it calls init. The following example shows how you might set custom Data Processing parameters in Analytics.js.

analytics.load("replace_with_your_write_key", {
  integrations: {
    'Facebook Pixel': {
      dataProcessingOptions: [['LDU'], 1, 1000]
    }
  }
});

Map categories to Facebook content types

If you’re using real estate, travel, or automotive Dynamic Ads you can map category values to content_type values. For example, you might map the category “cars” to the “vehicle” content type so Facebook promotes relevant vehicles from your catalog. To understand which content types you can map to, consult the Facebook Dynamic Ads documentation.

For most implementations, Segment recommends leaving these mappings blank. By default, Segment sets content_type to “product”.

The same mapping can be used to change the content_id from the default value (product_id or the sku) to anything specific for Meta Pixel. For more information about required Meta Pixel events, see Meta’s Required Meta Pixel events and parameters for Advantage+ catalog ads documentation.

Troubleshooting

PII blocklisting

Facebook enforces strict guidelines around sending Personally Identifiable Information (PII) as properties of Pixel events. To adhere to these guidelines, Segment automatically scans track event properties for PII and removes any that get flagged from the event to Facebook. The following keys are currently filtered:

• email
• firstName
• lastName
• gender
• city
• country
• phone
• state
• zip
• birthday

Any track events with properties containing those keys will be sent to Facebook with those properties omitted.

If you have events that use any of those keys for non-PII properties, you can manually allowlist them using the Allowlist PII Properties setting. You may also add to this list and/or optionally hash blocklisted properties with the Blocklist PII Properties setting.

Inconsistent or missing conversions

Facebook conversion pixels can fire inconsistently due to page redirects or reloads before the pixel has finished loading on the page. Make sure your page doesn’t redirect or reload for at least 300ms after the conversion event happens. In some cases a delay of 500ms is necessary.

Segment recommends using the trackLink or trackForm helpers to delay the page redirect. For more on these methods, view the track link documentation. You can extend the delay by setting the timeout to 500ms.

Extra or duplicate conversions

This may be due to conversion events being sent from your development, staging, or testing environments. Segment recommends setting up separate sources for each environment, which will let you either point events to test conversion pixels in Facebook Conversion Tracking or turn off Facebook Conversion Tracking completely in non-production environments.

Double check that your mapped conversion events aren’t happening anywhere else on your site. If the user reloads the conversion page or re-triggers the tracked event, they may be double counted.

Facebook’s conversion reports count view-through conversions as well as click-through conversions by default. You can change that setting inside Facebook Conversion Tracking in the report attribution settings.

Facebook conversions not matching Google Analytics

Facebook counts conversions per person, as opposed to Google Analytics which counts per browser cookie session (unless you’re using Google Analytics User-ID).

If someone saw or clicked on your ad on a mobile phone then later came back directly to purchase on a desktop machine, Google Analytics wouldn’t know that this was the same person, but Facebook would. In that scenario, Google Analytics would count two unique visits with a conversion last attributed to a direct visit on desktop. Facebook would count one conversion with the conversion properly attributed to the last ad click/view on mobile.

Are Facebook Pixel events reflected in Facebook Ads Manager in real-time?

Facebook Pixel events typically don’t display in real-time within the Facebook Ads Manager or other reporting interfaces. While Facebook Pixel events are tracked in near real-time, there might be some delay before you see them in your reporting. Visit Facebook’s documentation to learn more.

Blocklisting nested properties

Segment does not handle nested properties that need to be blocklisted, including the standard PII properties. If you have properties you would like to blocklist, you can use destination filters to drop those properties before they are sent downstream.

Mapping revenue to value

Segment pre-maps revenue or total to value. If you have a custom value property, it’s overwritten with the value from revenue or total, or it appears as ‘0.00’ if those two properties aren’t present. If you have a value property, you can use a destination middleware or destination plugin to transform the name before it is sent downstream to avoid any data loss.

Script unverified or undetected by third-party tool

Many times this is a limitation on the tool’s detection process, where the detector is looking for a specific HTML element on your page. Our client side analytics.js library asynchronously loads the tool’s library or pixel onto the page. As such, the detection fails.

In order to confirm that the tool’s library or pixel is actually loaded onto the page, you can open up the JavaScript console and go to the network tab when the page is loading.

If the script isn’t loading, check that any form of ad blocker is disabled.

Settings

Segment lets you change these destination settings from the Segment app without having to touch any code.