Setup Guide

This guide will help you set up Facebook Pixel as a destination in the RudderStack dashboard. It also lists the configuration settings required to correctly send data from the supported sources to Facebook Pixel.

Connection compatibility

Destination info
Status: Generally Available Supported sources: Android, iOS , Web, Unity, AMP , Cloud, Warehouse, React Native , Flutter, Cordova, Shopify Refer to it as FACEBOOK_PIXEL in the Integrations object.

Connection modes
Source	Cloud mode	Device mode	Hybrid mode
AMP
Android
Cloud
Cordova
Flutter
iOS
React Native
Shopify
Unity
Warehouse
Web

Supported message types
Source	Identify	Page	Track	Screen	Group	Alias
Cloud mode
Supported sources
Device mode
Web

In the web device mode integration, that is, using JavaScript SDK as a source, RudderStack loads the Facebook Pixel native SDK from the https://connect.facebook.net/ domain.

Based on your website’s content security policy, you might need to allowlist this domain to load the Facebook Pixel SDK successfully.

Get started

Once you have confirmed that the source platform supports sending events to Facebook Pixel, follow these steps:

1. From your RudderStack dashboard, add the source. Then, from the list of destinations, select Facebook Pixel.
2. Assign a name to your destination and click Continue.

Connection settings

To successfully configure Facebook Pixel as a destination, you will need to configure the following settings:

• Facebook Pixel ID: Enter your Facebook Pixel ID. This is required for sending events via both cloud and device modes.
• Business Access Token: Enter your Facebook business access token required to send the events via cloud mode.

For more information on obtaining your Facebook Pixel ID and Business Access Token, refer to the FAQ section below.

Event settings

• Enable Standard Event (PageView) for all Page and Screen Calls: If this setting is enabled, RudderStack sets pageview as a standard event for all page and screen calls.
• Map your events with Facebook Standard Events: RudderStack maps some events to the Facebook standard events by default. You can use this option to override the default mappings and map events to the Facebook standard events.
• Value Field Identifier: Set this field to properties.price or properties.value. RudderStack assigns it to the Facebook payload’s value field. You can use this setting for the Product Viewed or Product Added events.
• Enable Advanced Matching: Enable this setting to update the user information in Facebook Pixel device mode.

If you enable both the Enable Advanced Matching and Use Updated Mapping settings, RudderStack maps external_id from userId > context.traits.userId > context.traits.id > anonymousId, in the mentioned order.

PII properties settings

• Denylist PII Properties: The PII properties mentioned in this field will not be sent to Facebook if Denylist PII Hash Property is not enabled. If it is enabled, the properties will be SHA256-hashed and sent to Facebook. The properties listed below are the default denylisted properties.

  • email
  • firstName
  • lastName
  • firstname
  • lastname
  • first_name
  • last_name
  • gender
  • city
  • country
  • phone
  • state
  • zip
  • postalCode
  • birthday

If you want to send any of the above properties hashed by SHA256, you need to enter the property name in the Denylist PII Properties field and enable the Denylist PII Hash Property toggle.

• Allowlist PII Properties: The PII properties mentioned in this field will be sent to Facebook if they are present in the properties of the events. This is only necessary for properties that match the Default Denylisted PII properties listed above.

Other settings

• Limited Data Usage: If enabled, RudderStack will take the data processing information from the payload and send it to Facebook. The data in the RudderStack payload should be as shown below:

"context": {
  "dataProcessingOptions": [
    [
      "LDU"
    ],
    1,
    1000
  ],
  "fbc": "fb.1.1554763741205.AbCdEfGhIjKlMnOpQrStUvWxYz1234567890",
  "fbp": "fb.1.1554763741205.234567890",
  "fb_login_id": "fb_id",
  "lead_id": "lead_id",
  "device": {
    "id": "df16bffa-5c3d-4fbb-9bce-3bab098129a7R",
    "manufacturer": "Xiaomi",
    "model": "Redmi 6",
    "name": "xiaomi"
  },
  "network": {
    "carrier": "AirCarrier"
  },
  "os": {
    "name": "android",
    "version": "8.1.0"
  },
  "screen": {
    "height": "100",
    "density": 50
  },
  "traits": {
    "email": "john@example.com",
    "anonymousId": "c82cbdff-e5be-4009-ac78-cdeea09ab4b1"
  }
}

Here, you can send the value of fbc parameter via context.fbc as shown in the above payload. If not sent, RudderStack auto generates it using the following values:

• Fetches fbclid from context.page.url

• Uses originalTimestamp as the creation time

• Sets subdomainIndex to 1

• Sets version to fb

• Use as Test Destination: Enable this setting if you are using this destination for testing purposes and enter the Test Event Code. This code can be found in your Facebook Pixel dashboard. When enabled, you can check your events in the Facebook Pixel dashboard in real time.

The context.dataProcessingOptions will be mapped to data_processing_options in Facebook as is mentioned in the Facebook developer docs.

• Don’t send external_id for user: If enabled, RudderStack does not send either userId or anonymousId as the external_id to Facebook Pixel.

Client-side event filtering

RudderStack supports specifying which events should be discarded or allowed to flow through, when sending events via device mode. For more information, refer to the Client-side Event Filtering documentation.

Web device mode settings

• Use Updated Mapping: If this setting is disabled, RudderStack sends the user traits to Facebook Pixel without any modification. If you enable this setting, RudderStack takes the following traits:

{
  firstName: "Alex",
  lastName: "Keener",
  email: "alex@example.com",
  phone: "12345678910",
  gender: "Male",
  birthday: "01012001",
  city: "New Orleans",
  country: "USA",
  zip: "90009", // You can also send postalCode instead
  state: "Louisiana",
  foo: "bar",
}

It then sends the above traits to Facebook Pixel in the following format:

{
  fn: "Alex",
  ln: "Keener",
  em: "alex@example.com",
  ph: "12345678910",
  ge: "Male",
  db: "01012001",
  ct: "New Orleans",
  country: "USA",
  zp: "90009",
  state: "Louisiana",
  foo: "bar"
}

If you enable both the Enable Advanced Matching and Use Updated Mapping settings, RudderStack maps external_id from userId > context.traits.userId > context.traits.id > anonymousId, in the mentioned order.

• Legacy Conversion Pixel IDs: With this setting, you can send specific events to a legacy conversion Pixel by specifying the event-Pixel ID mapping. Note that this option is available only when sending events via device mode.

• Enable Automatic Configuration: Enabled by default, this setting sends button click and page metadata from your website to improve your ads delivery and measurement and automate your Pixel setup. See Meta documentation for more information.

• Use device-mode to send events: Enable this setting to send events from the JavaScript SDK to Facebook Pixel via device mode.

• Finally, click Next to complete the configuration.

FAQ

Where can I find the Pixel ID?

To get your Pixel ID, go to your Facebook Ads Manager account. On the left navigation bar, select Business Tools, and click Events Manager under Manage Business.

In the Data Sources, you should be able to see your Pixel ID underneath your site name.

Where can I find the Business Access Token?

In order to use the Facebook Conversions API, you need to generate an access token. We recommend using the Facebook Events Manager to do so, by following these steps:

• Choose the relevant Facebook Pixel and click the Settings tab.
• In the Conversions API section, click Generate access token under the Set up manually section:

For more information on how to use this access token or to generate your access token via your own app, refer to the Facebook documentation.

Can I hash my user data before sending it to RudderStack?

Yes. Facebook Pixel requires all user data, data coming from context.traits, to be hashed. This includes email, phone, birthday, address, etc. By default, RudderStack will automatically hash all of the necessary properties for you. However, if you would like to hash these traits before sending to RudderStack then you need to add this code to the event.

rudderanalytics.track(
  "some_event_name",
  { some_properties },
  {
    integrations: {
      "Facebook Pixel": {
        hashed: true,
      },
    },
  }
)

The integrations object with these key-values will tell RudderStack not to hash the traits in context.traits because they are already hashed. Otherwise, RudderStack will hash your data again and Facebook will not be able to match the traits. Please keep in mind that Facebook will not accept un-hashed data.

I can see my events being sent in the RudderStack dashboard but are not visible in the Facebook Pixel dashboard. What could be the reason?

It may take upto 24 hours for your events to reflect in the Facebook Pixel dashboard.
You can also verify if your events are flowing correctly by enabling the Use as Test Destination setting in the RudderStack dashboard. It reflects the events in the Facebook Pixel dashboard in real time.

Questions? Contact us by email or on Slack