# Facebook Pixel Destination ## Destination Info * Accepts [Page](/docs/segment/connections/spec/page), [Identify](/docs/segment/connections/spec/identify), [Track](/docs/segment/connections/spec/track) calls. * Refer to it as **Facebook Pixel** in the [Integrations object.](/docs/segment/guides/filtering-data/#filtering-with-the-integrations-object) ### Components * Browser ## Connection Modes [Learn more about connection modes.](/docs/segment/connections/destinations/#connection-modes) ### Device-Mode * web: yes * mobile: no * server: no ### Cloud-Mode * web: no * mobile: no * server: no [Facebook Pixel](https://developers.facebook.com/docs/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](https://github.com/segment-integrations/analytics.js-integration-facebook-pixel). > \[!WARNING] > > Facebook deprecated the modular Ads For Websites suite, which previously comprised Facebook Custom Audiences and Facebook Conversion Tracking. Segment consolidated those two destinations into this new and improved Facebook Pixel destination. **Use cases** * [Increase conversions by retargeting shopping cart abandoners on Facebook](https://segment.com/recipes/abandon-cart-retargeting-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. | **Facebook Destination** | Supported by Engage | | ------------------------------------------------------------------------------------------------------------------- | ------------------- | | **[Facebook App Events](/docs/segment/connections/destinations/catalog/facebook-app-events/)** | Yes | | **[Facebook Offline Conversions](/docs/segment/connections/destinations/catalog/facebook-offline-conversions/)** | Yes | | **[Facebook Pixel](/docs/segment/connections/destinations/catalog/facebook-pixel/)** | No | | **[Facebook Custom Audiences](/docs/segment/connections/destinations/catalog/personas-facebook-custom-audiences/)** | Yes | | **[Facebook Conversions API](/docs/segment/connections/destinations/catalog/actions-facebook-conversions-api/)** | Yes | ## 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](https://www.facebook.com/ads/manager/pixel/facebook_pixel). 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 Spec, take a look to understand what the [Page method](/docs/segment/connections/spec/page/) does. An example call would look like: ```javascript 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 Spec, take a look to understand what the [Identify method](/docs/segment/connections/spec/identify/) does. An example call would look like: ```javascript 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 updates 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 updates in Facebook Pixel using their Advanced Matching feature. ## Track If you're not familiar with the Segment Spec, take a look to understand what the [Track method](/docs/segment/connections/spec/track/) does. An example call would look like: ```javascript analytics.track("My Custom Event", { checkinDate: new Date(), myCoolProperty: "foobar", }); ``` Segment's analytics.js client-side integration supports all three [documented](https://developers.facebook.com/docs/facebook-pixel/api-reference#events) 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. ```javascript 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's 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](https://developers.facebook.com/docs/facebook-pixel/implementation/conversion-tracking/#standard-events). 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 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's how you'd specify standard events in the settings view: ![Event mapping.](https://docs-resources.prod.twilio.com/61783c625a405421116266c3e5e22d242a3c70fb5a34c32c430d6bc76b0cfd78.png) 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](https://developers.facebook.com/docs/facebook-pixel/advanced/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](/docs/segment/connections/spec/identify/#traits), 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](https://developers.facebook.com/docs/marketing-apis/data-processing-options) 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](https://developers.facebook.com/docs/marketing-apis/data-processing-options). 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. > \[!NOTE] > > The **Use Limited Data Use** destination setting is disabled by default for all Facebook destinations except for Facebook Pixel. You must enable the setting 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 `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](/docs/segment/connections/sources/catalog/libraries/website/javascript/#load-options) 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. ```javascript 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](https://developers.facebook.com/docs/marketing-api/advantage-catalog-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](https://developers.facebook.com/docs/marketing-api/dynamic-ad). 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_ids` 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](https://www.facebook.com/business/help/606577526529702?id=1205376682832142) 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](/docs/segment/connections/sources/catalog/libraries/website/javascript#track-link). You can extend the delay by [setting the timeout to 500ms](/docs/segment/connections/sources/catalog/libraries/website/javascript#extending-timeout). ### 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](/docs/segment/connections/destinations/catalog/actions-google-analytics-4#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](https://www.facebook.com/business/help/147965221941551) 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](/docs/segment/connections/destinations/destination-filters/) to drop those properties before they are sent downstream. ### Mapping `revenue` to `value` Segment pre-maps `revenue` or `total` to `value` for purchase events, like "Order Completed". If you have a custom `value` property, it's overwritten with the value from `revenue` or `total`, or, if those two properties aren't present, it appears as '0.00'. If you have a `value` property, you can use a [destination middleware](/docs/segment/connections/sources/catalog/libraries/website/javascript/middleware/#using-destination-middlewares) or [destination plugin](/docs/segment/connections/sources/catalog/libraries/website/javascript/#advanced-plugin-api) to transform the name before it is sent downstream to avoid any data loss. If there are events that are not purchase events, but that you'd like to track `value` data about, use the Value Field Identifier setting to specify which existing field should map to Facebook's `value` field. ### 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](/docs/segment/connections/sources/catalog/libraries/website/javascript#how-do-i-open-the-javascript-console-in-your-debugger) and go to the network tab when the page is loading. ![Checking network tab to see if script loads.](https://docs-resources.prod.twilio.com/8a2cd023e90dc07c18494061e6013d19469548d2b7a40f6f4dba91417b7d6b39.gif) If the script isn't loading, check that any form of ad blocker is disabled. ### Why am I seeing a "Mismatched IP Address" warning in Facebook after enabling both Facebook Conversions API and Facebook Pixel? When both Facebook Pixel and Facebook Conversions API are enabled, you may see a "Mismatched IP Address" warning in Facebook reports. This happens because the two sources may send different IP versions (IPv4 vs. IPv6) for the same event: * Facebook Pixel collects the user's IP address directly from the browser, [including IPv6 addresses when available](https://developers.facebook.com/docs/marketing-api/conversions-api/parameters/customer-information-parameters#). This happens independently of Segment. Even though Segment's Analytics.js defaults to collecting only IPv4, the Facebook Pixel automatically collects and sends IPv6 if it's available. * Facebook Conversions API sends events to Facebook using data collected by Segment, which typically includes only an IPv4 address. Since the IP addresses from these two sources don't always match, Facebook may flag the event with a "Mismatched IP Address" warning. To resolve this, you can manually collect and send the IPv6 address (when available) in your event payload and send it to Segment. Then, map this data to the Facebook Conversions API destination. This ensures that Facebook receives the same IP version from both sources, preventing mismatches. ## Settings Segment lets you change these destination settings from the Segment app without having to touch any code. | Field | Description | Required | Type | | ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | -------- | | Automatic Configuration | 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]\(https://developers.facebook.com/docs/facebook-pixel/advanced/#automatic-configuration). You can disable this functionality by unchecking this setting. | No | boolean | | Blocklist PII Properties | 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]\(/docs/segment/connections/destinations/catalog/facebook-pixel/#pii-blocklisting) 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. | No | mixed | | Map Categories to FB Content Types | 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. | No | text-map | | Enable Advanced Matching | If enabled, we will initialize Facebook Pixel with any user traits that have been cached in the Segment cookies from your previous \`.identify()\` calls. | No | boolean | | Advanced Match Trait Key for External ID | 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. | No | string | | Legacy Conversion Pixel IDs | These are your \*\*\[deprecated]\(https://developers.facebook.com/docs/ads-for-websites)\*\* 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. | No | text-map | | Limited Data Use | 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\`. | No | boolean | | Pixel ID | Your Pixel ID from the snippet created on the \[Facebook Pixel creation page]\(https://www.facebook.com/ads/manager/pixel/facebook\_pixel/). | Yes | string | | Map Your Events to Standard FB Events | Enter your event on the left, and the Facebook standard event to map to on the right. Facebook recognizes certain \[standard events]\(https://developers.facebook.com/docs/marketing-api/facebook-pixel/v2.5#standardevents) 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. | No | map | | Standard Events custom properties | Add here all the custom properties you want to send as part of your Standard Events (Order Completed, Checkout Started, etc) as \`property name\`. | No | array | | Use User ID or Anonymous ID as External ID | 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. | No | boolean | | Value Field Identifier | 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. | No | select | | Allowed PII Properties | 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]\(/docs/segment/connections/destinations/catalog/facebook-pixel/#pii-blocklisting) for the exact property names we filter out.\*\* | No | array |