Facebook Pixel

Facebook Pixel is a simple JavaScript snippet that you can add to your website and track visitor activity as well as other important metrics. It allows you to measure and rudder audiences to build effective marketing and advertising campaigns.

This destination also supports the Conversions API for sending server side events.

You can now send your event data directly to Facebook Pixel through RudderStack.

Getting Started

To enable sending your event data to Facebook Pixel, you will first need to add it as a destination to the source from which you are sending your event data.

Before configuring your source and destination on the RudderStack, please verify if the source platform is supported by Facebook Pixel, by referring to the table below:

Once you have confirmed that the platform supports sending events to Facebook, perform the steps below:

• From your RudderStack dashboard, add the source. From the list of destinations, select Facebook Pixel.

• Give a name to the destination and click on Next. You should then see the following screen:

The connection settings are:

• Enter your Facebook Pixel ID (Required for both Device Mode and Cloud Mode) If you have a Business Access Token (required for Cloud Mode), enter that as well.

• Some other important settings are:

  • Value Field Identifier: You can set this field to properties.price or properties.value and will be assigned to the value field of the Facebook payload.
  • Blacklist PII Properties: The PII properties mentioned in this field will not be sent to Facebook if Blacklist PII Hash Property is not enabled. If it is enabled, the property will be hashed by SHA256 and sent to Facebook. The properties listed below are the default blacklisted properties. If you would still like to send one of these properties but instead hashed by SHA256, you will need to enter the property name in the field and enable the Blacklist PII Hash Property toggle.

  Copy
  Default Blacklisted PII
  -----------------------
  "email",
  "firstName",
  "lastName",
  "firstname",
  "lastname",
  "first_name",
  "last_name",
  "gender",
  "city",
  "country",
  "phone",
  "state",
  "zip",
  "birthday"

  • Whitelist 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 Blacklisted PII properties above.

  • Standard Events Custom Properties: For the standard events, some predefined properties are taken by Facebook. If you want to send more properties for your events, those properties should be mentioned in this setting.

  • Use as Test Destination: If you will be using this destination for testing purposes, toggle this switch on. Then, enter the Test Event Code below. This code can be found on your Facebook Pixel dashboard and is required if the Test Destination flag is turned on.

  • 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 follows:

Copy
"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": "Banglalink"
  },
  "os": {
    "name": "android",
    "version": "8.1.0"
  },
  "screen": {
    "height": "100",
    "density": 50
  },
  "traits": {
    "email": "abc@gmail.com",
    "anonymousId": "c82cbdff-e5be-4009-ac78-cdeea09ab4b1"
  }
}

• Finally, click on Next to complete the configuration.

Identify

In Facebook Pixel, the immediate updating of user properties via the identify call is not supported. If the Enable Advanced Matching is turned on in the dashboard, then the identify call will update Facebook Pixel with the user information.

The following snippet highlights the use of the identify call:

Copy
rudderanalytics.identify("userId", userVars) // userVars is a JSON object

Page

When the pagecall is made, the track event is sent as PageView to fbq('track,'PageView'). Any parameter sent to rudderanalytics.page() is ignored by RudderStack.

A sample page call is as shown:

Copy
rudderanalytics.page()

Track

The track call lets you track custom events as they occur in your web application.

A sample call looks like the following code snippet:

Copy
rudderanalytics.track("Product Added", {
  order_ID: "123",
  category: "boots",
  product_name: "yellow_cowboy_boots",
  price: 99.95,
  currency: "EUR",
  revenue: 2000,
  value: 3000,
  checkinDate: "Thu Mar 24 2018 17:46:45 GMT+0000 (UTC)",
})

In addition to the above call, a contentType in the integrations options can be available. If present, it will precede the default value or dashboard settings of contentType.

Copy
rudderanalytics.track(
  "Product Added",
  {
    order_ID: "123",
    category: "boots",
    product_name: "yellow_cowboy_boots",
    price: 99.95,
    currency: "EUR",
    revenue: 2000,
    value: 3000,
    checkinDate: "Thu Mar 24 2018 17:46:45 GMT+0000 (UTC)",
  },
  {
    "Facebook Pixel": { contentType: "mycustomtype" },
  }
)

Standard Events

In the dashboard, you have the option to map your events to standard Facebook events. RudderStack maps the events in the code and sends them to Facebook pixel as the standard event as specified. The properties will be sent according to what the standard event requires.

The mapping is done as follows in RudderStack:

In Pixel, a currency for Purchase events is required to be specified. If not provided the default will be set to USD.

Other Standard Events

If you map your event to any of the following Standard Events listed below, then RudderStack will treat it as an Other Standard Event. For any properties you would like to send with the other standard event you must specify them in the Standard Events custom properties settings field.

Copy
"AddToWishlist"
"AddPaymentInfo"
"Lead"
"CompleteRegistration"
"Contact"
"CustomizeProduct"
"Donate"
"FindLocation"
"Schedule"
"StartTrial"
"SubmitApplication"
"Subscribe"

Legacy Events

In the dashboard, the legacy conversion Pixel IDs can be filled. The events which appear in the mapping are sent to Pixel with the mapped Pixel ID. The conversion events only support currency and value as their event properties.

Custom Events

Custom events are used to send any event that does not appear in any of the mappings.

Deduplication

Facebook Pixel allows you to send events via your web browser and your server via the Conversion API. Depending on how you send your events, with this duel set-up, redundant events may be received by Facebook. Therefore, to help get accurate representation of your data, Facebook tries to deduplicate events coming in.

event_id Method (Recommended)

Facebook's (and RudderStack's) recommended form of deduplication is to leverage the event_name and event_id properties. When two events coming into Facebook meet the following criteria, they will be deduplicated.

• They are sent within 48 hours of each other
• They are received by the same Facebook Pixel ID
• They have the same event_name i.e. Purchase etc.
• They have the same event_id
  • The event_id must be unique to that specific event and the same for both of the events coming from the Pixel and Conversion API
  • For example: the event_id could be the purchase order number etc.

To set the event_id, simply include the event_id key-value pair either in the context.traits object or the properties object. The event_name will be whatever the name of the event is.

fbp and external_id Method (Not Recommended)

For this approach, it is necessary to send an event, first from the browser, then from the server. Both events must have the same event_name, and the same fbp parameter and the same external_id. If the browser event is received before the server event and both events have the same event_name and the same fbp and external_id, then the server event will be discarded. Below are a few shortcomings for this deduplication method.

• It will always discard the server event is Facebook identifies a redundant event.
• This method only works for deduplicating events sent first from the browser and then the server.
• There will be no deduplication if two consecutive browser events with the same information are sent to Facebook. The same is true if two server events with the same information is sent to Facebook

RudderStack maps the event_name from whatever the name of the event that is being sent is. The fbp parameter is taken from the context.fbp key-value pair. Finally, the external_id will just be the userId or anonymousId (if userId is not present).

Timestamps

Facebook Pixel uses ISO 8601 timestamp without the timezone information.

Facebook expects them to be sent in the following format:

"checkinDate", "checkoutDate", "departingArrivalDate", "departingDepartureDate", "returningArrivalDate", "returningDepartureDate", "travelEnd", "travelStart"

FAQs

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 on 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 on the Settings tab.
• In the Conversions API section, click on Generate access token under the Set up manually section, as shown:

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.

Copy
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.

Contact Us

If you come across any issues while configuring Facebook Pixel with RudderStack, please feel free to contact us. You can also start a conversation on our Slack channel; we will be happy to talk to you!