Facebook Pixel Destination

Destination Info
  • 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. It makes conversion tracking, optimization and remarketing easier than ever. The Facebook Pixel Destination is open-source. You can browse the code on GitHub.

Facebook has deprecated the modular “Ads For Websites” suite, which previously comprised Facebook Custom Audiences and Facebook Conversion Tracking. We’ve consolidated those two destinations into this new and improved “Facebook Pixel” destination.

Use Cases

Other Facebook Destinations Supported by Segment

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

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

Getting Started

Before you start, make sure Facebook Pixel supports the source type and connection mode you’ve chosen to implement. You can learn more about connection modes here.

Web Mobile Server
📱 Device-mode ⬜️ ⬜️
☁️ Cloud-mode ⬜️ ⬜️ ⬜️
  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.

Segment automatically initializes Facebook’s pixel with your pixelId upon loading analytics.js.


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:


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


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.


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

On our analytics.js client-side integration we support 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 will take 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. You can find documentation on these events here.

In addition, Segment will specially handle the following event types and send them as Standard events:

  • “Order Completed” will be sent as “Purchase”
  • “Product Added” will be sent as “AddToCart”
  • “Product List Viewed” will be sent as “ViewContent”
  • “Product Viewed” will be sent as “ViewContent”
  • “Products Searched” will be sent as “Search”
  • “Checkout Started” will be 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 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:

event mapping

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 included in the event will be included as event properties.


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, it is assumed 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, before we fire off the pixels, we’ll check for traits that the user has been previously identified with and send 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.

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 of the event.

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 example below 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 FB 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 we recommend leaving these mappings blank. By default, we’ll set content_type to “product”.


PII Blocklisting

Facebook enforces strict guidelines around sending Personally Identifiable Information (PII) as properties of Pixel events. In order to adhere to these guidelines, Segment will automatically scan track event properties for PII and remove 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

The most common reason for Facebook conversion pixels to fire inconsistently is that the page redirects or reloads before the pixel has time to be loaded on the page. Make sure your page does not redirect or reload for at least 300ms after the conversion event happens. In some cases a delay of 500ms is necessary.

We recommend using our trackLink or trackForm helpers to delay the page redirect. Documentation here. 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. We recommend setting up separate source for each environment. That way you can 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 counts 2 unique visits with a conversion last attributed to a direct visit on desktop. Facebook counts one conversion with the conversion properly attributed to the last ad click/view on mobile.

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.

Checking network tab to see if script loads

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


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

Setting Description
Automatic Configuration boolean, defaults to TRUE .

The Facebook Pixel will, by default, send button click and page metadata from your website to improve your ads delivery and measurement and automate your pixel setup. You can learn more about this here. You can disable this functionality by unchecking this setting.
Blocklist PII Properties
mixed, defaults to .

Facebook has a strict policy prohibiting any personally identifiable information (PII) from being sent as properties of events to their API. By default, this integration will scan track events for these properties and strip them from the payload that gets sent to Facebook. If your events contain other properties with PII values, you can use this setting to append to this default list. You can also use this setting to optionally hash any PII values instead of dropping them.
Map Categories to FB Content Types
text-map, defaults to {}.

Enter your category value on the left, and the Facebook content type to map to on the right. Facebook recognizes certain event types that can help deliver relevant ads. If no category values are mapped we’ll default to product and product_group, depending on the event.
Enable Advanced Matching boolean, defaults to FALSE .

If enabled, we will initialize Facebook Pixel with any user traits that have been cached in the Segment cookies from your previous .identify() calls.
Advanced Match Trait Key for External ID string. Please indicate a user trait key which you would like Segment to use to send an external_id to Facebook Pixel using advanced matching. Segment will use the value of this trait to map it to Facebook Pixel’s external_id. Note: Enable Advanced Matching must be enabled to use this setting.
Legacy Conversion Pixel IDs text-map, defaults to {}.

These are your deprecated Conversion Pixel IDs from Facebook Conversion Tracking. Facebook will still accept data in this format, though it’s no longer possible to create conversion Pixel IDs. Now you create conversions based on standard and custom events inside their interface. Enter your event name in the left column and your pixel ID in the right column.
Limited Data Use
boolean, defaults to TRUE .

The Limited Data Use (LDU) setting controls whether or not Limited Data Use mode is set in the FB Pixel SDK. When enabling LDU, Segment will send default user geography options to request that Facebook geolocate the event. To override the default geography options set the values in the analytics.js Load Options under the key dataProcessingOptions.
Pixel ID
string. Your Pixel ID from the snippet created on the Facebook Pixel creation page.
Map Your Events to Standard FB Events
map, defaults to {}.

Enter your event on the left, and the Facebook standard event to map to on the right. Facebook recognizes certain standard events that can be used across Custom Audiences, custom conversions, conversion tracking, and conversion optimization. When you map an event to a standard Facebook event, we’ll send the event by that name. Any unmapped events will still be sent as Custom Events.
Standard Events custom properties
array, defaults to .

Add here all the custom properties you want to send as part of your Standard Events (Order Completed, Checkout Started, etc) as property name.
Use User ID or Anonymous ID as External ID boolean, defaults to FALSE .

Enable this setting if you want to send userId (or anonymousId if not present) as external_id to Facebook when using advanced matching. Note: Enable Advanced Matching must be enabled to use this setting.
Value Field Identifier
select, defaults to value.

For pre-purchase events such as Product Viewed and Product Added, choose which Segment property you would like to map to Facebook’s value property.
Allowed PII Properties array, defaults to .

By default, Segment will strip any PII from the properties of track events that get sent to Facebook. If you would like to override this functionality, you can input each property you would like to allow as a line item in this setting. Please reference our documentation for the exact property names we filter out.

This page was last modified: 27 Sep 2022

Get started with Segment

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