Facebook Pixel Cloud Mode Integration

RudderStack lets you send your event data to Facebook Pixel via cloud mode.

Find the open source transformer code for this destination in the GitHub repository.

The cloud mode integration for Facebook Pixel will be deprecated soon.

RudderStack recommends using the Facebook Conversions destination to send events in cloud mode.

Identify

In Facebook Pixel, the immediate updating of user properties via the identify call is not supported. To do so, you need to enable the Enable Advanced Matching setting in the RudderStack dashboard.

The following snippet highlights the use of the identify call:

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

Page

When you make the page call, RudderStack sends the data to Facebook Pixel with the event type as pageView. You can also pass properties to page - RudderStack automatically sends these properties along with the event ID to Pixel.

A sample page call is as shown:

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:

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.

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

String is the only valid data type for the category field. However, you can pass an array of string values which will be concatenated using a delimiter (,) before sending the events.

Standard events

This destination does not strictly adhere to the RudderStack Ecommerce Event Spec.

RudderStack maps the event name in the payload to the Facebook standard event before sending it to Facebook Pixel. The properties are sent as the standard events require them. See the Ecommerce Events Specification for more information.

RudderStack maps the following events to the Facebook standard events by default:

You can use the Map your events with Facebook Standard Events setting in the RudderStack dashboard to override the default mappings specified in the table above.

Note that:

• For the Purchase standard event (mapped to Order Completed event), properties.revenue is a required field. Also, RudderStack sends the delivery_category field along with id, item_price and quantity.

• For the Products Searched event, the query property must be a string.

• If you map an event with the ViewContent standard event using the RudderStack dashboard setting and don’t send the products array in the message.properties object:

  "properties": {
    "phone": 1-202-555-0146,
    "email": "alex@example.com",
    "category": "clothing",
    "list_id": "1234",
    "testDimension": true,
    "testMetric": true
  }
  

  Then, content_ids is mapped to properties.category value (clothing in this case) and quantity is set to 1 inside the contents object.

The below table elaborates the property mappings between RudderStack and Facebook corresponding to the RudderStack event:

In the above table, the default values for the currency and quantity properties are USD and 1 respectively.

Other standard events

If you map your event to any of the following Facebook standard events, then RudderStack treats it as a standard event as well:

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

For any properties you want to send with these events, you must specify them in the Standard Events custom properties settings field.

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.

You can set the event_id in traits , context.traits or properties object as a unique identifier.

If you don’t set the event_id, RudderStack will use messageId to map to Facebook’s eventId.

The event_name will be picked up from the name of the event. For more information regarding the logic behind the event_id deduplication, refer to the Facebook documentation.

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

For more information regarding the logic behind the fbp and external_id deduplication, refer to the Facebook documentation.

Sending custom content_type

You can send a custom content_type field by specifying it in the properties.content_type field of your event.

RudderStack sets the value of content_type in the following priority order:

1. It gives the highest priority to properties.content_type in your event.
2. If properties.content_type is absent, RudderStack sets the content_type to product by default, except in the following cases:

• If Product List Viewed event is sent:
  • with products array, then the content_type is set to product.
  • without the products array, then the content_type is set to product_group.
• If Product Viewed event is not mapped in RudderStack dashboard (default mapping is set to View Content event) but is sent:
  • with products array, then the content_type is set to product.
  • without the products array, then the content_type is set to product_group.
• If any other event is mapped to the Facebook standard event View Content in the RudderStack dashboard and is sent:
  • with products array, then the content_type is set to product.
  • without the products array, then the content_type is set to product_group.

product and product_group are the only two acceptable values for content_type.

Questions? Contact us by email or on Slack