Facebook Offline Conversions Destination


Facebook Offline Conversions enables offline event tracking, so marketers can run campaigns, upload transaction data, and compare in-store transactions.

This document was last updated on April 24, 2018. If you notice any gaps, outdated information or simply want to leave some feedback to help us improve our documentation, let us know!

Other Facebook Destinations Supported by Segment

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

Facebook Destination Supported by Personas
Facebook App Events Yes
Facebook Offline Conversions Yes
Facebook Pixel No
Facebook Custom Audiences Yes
Facebook Custom Audiences Website Yes

Getting Started

Before you start, make sure Facebook Offline Conversions 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 Offline Conversions” in the Catalog, select it, and choose which of your sources to connect the destination to.

  3. Authorize Segment to send data on your behalf by connecting through OAuth:

By doing so, we will ask for ads_management and public_profile access scopes which will allow Segment to have proper permissions to send offline events to your Event Sets. You can read more about Facebook’s access and authentication if you would like to know exactly what these scopes allow.

IMPORTANT: Note that the Segment user that is OAuthing MUST have admin access in your company’s Facebook Business Manager account. Otherwise, the authorization will fail.

Once you complete the OAuth flow, you should be connected.

Note: Once we retrieve your access token, they should not expire. However, if for whatever reason you are not seeing conversions come through you should check your destination settings and you should reauthorize.

  1. You MUST map the name of every Segment track event that you’d like to send and the corresponding ID of the Event Set where you want to send the conversions to. This is to avoid sending unwanted track events as conversions.

You can find Facebook Offline Event Set ID by going to your Offline Events page in your Facebook Business Manager account and clicking the desired Offline Event Set here:

Track

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({
  userId: '019mr8mf4r',
  event: 'Order Completed',
  properties: {
    revenue: 39.95,
    shippingMethod: '2-day'
  }
});

There are 3 places you can map your Segment track events:

1) Map track events to Facebook’s CompleteRegistration conversions:

2) Map track events to Facebook’s Lead conversions:

3) Map all other custom or ecommerce track events to any Event Set ID:

The following table shows how we map Segment’s semantic ecommerce or custom event names to Facebook’s semantic conversion event names:

Segment Event Name Facebook Semantic Conversion Event Name
Products Searched Search
Product Viewed ViewContent
Product List Viewed ViewContent
Product Added to Wishlist AddToWishlist
Product Added AddToCart
Checkout Started InitiateCheckout
Payment Info Entered AddPaymentInfo
Order Completed Purchase

Note: Lead and CompleteRegistration events can be mapped separately in Map Track Events as Lead Conversions to Event Set IDs and Map Track Events as CompleteRegistration Conversions to Event Set IDs destination settings respectively.

The following table shows how we map Segment raw message fields or properties to Facebook’s semantic conversion event parameters:

Segment Property Facebook Semantic Conversion Parameters
Hardcoded as "Segment" upload_tag
timestamp event_time
See event name mapping above event_name
currency currency
value, price, or revenue* value
Hardcoded as "product" or "product_group"* content_type
products.$.product_ids or category* content_ids
Any remaining properties custom_data

Note: For only Product List Viewed will we set the content_type as "product_group" and use properties.category for the content_ids. All other applicable events will use properties.$.product_id(s) and "product" respectively. Any pre-purchase events will default to map Facebook’s value parameter to Segment’s properties.value. You can override this by choosing "price" in the Value Field Identifier dropdown in your settings. Order Completed events will always use properties.revenue.

Attribution and “Match Keys”

Facebook requires that you send at least one match_key in order for them to attribute which Facebook user should be tied to a conversion. The more user information you send with your track calls, the better the accuracy of Facebook’s attribution. Once Facebook has successfully attributed a conversion for a given user, they will store the mapping between the userId to the rest of match_keys such as the email address for all future conversions.

Since track events by default do not require you to send user metadata, it is still possible for us to send a conversion as long as you send us a userId (which we map to Facebook’s extern_id). However, for better attribution results, we recommend you send as much applicable user data through context.traits as shown in the mapping table below:

Segment context.traits Properties Facebook Match Key Parameters
email email
phone phone
gender gen
firstName or name* fn
lastName or name* ln
address.city ct
address.state st
address.postalCode zip
address.country country
See Note Below * lead_id
// node.js library example

analytics.track({
  userId: 'hamsolo813',
  event: 'Product Added',
  properties: {
    cart_id: 'cart1234',
    product_id: 'product12356',
    sku: 'G-32',
    category: 'Games',
    name: 'Monopoly: 3rd Edition',
    brand: 'Hasbro',
    variant: '200 pieces',
    price: 18.99,
    quantity: 1,
    coupon: 'MAYDEALS',
    position: 3
  },
  context: {
    traits: {
      email: 'hamsolo813@hamsolo813.com',
      phone: '4011234567',
      gender: 'm',
      name: 'ham solo',
      address: {
        city: 'East Greenwich',
        state: 'RI',
        postalCode: '02818',
        country: 'USA'
      }
    }
  }
});

Note: You can choose to exlicitly send firstName or lastName separately or just send name. We will properly map to fn and ln properly. If your server has access to Facebook’s Lead IDs from their Lead Ads product, you can opt to send this using integration specific options:

// node.js library example

analytics.track({
  userId: 'hamsolo813',
  event: 'Order Completed',
  properties: {
    ...
  },
  context: {
    'Facebook Offline Conversions': { leadId: '<LEAD ADS ID>' }
  }
});

We will use SHA256 to hash all match_keys that include personally identifiable data in compliance with Facebook’s privacy requirements.

Keep in mind that Facebook’s furthest possible attribution window is 28 days. It is recommended that you send your server side track conversions within 62 days of the offline conversion occuring.

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.

The Facebook API does not accept an IP address field to determine the geolocation of a user. Instead, you would need to set the specific user geography options (Data Processing Options Country and Data Processing Options State) in the integrations object.

If the Use Limited Data Use destination setting is enabled, but you do not pass the Data Processing parameters in the integrations object, Segment sends an empty data processing object which disables LDU for this event.

The example below shows how you might set custom Data Processing parameters for a Segment server library.

// node.js library example

analytics.track({
  event: 'Membership Upgraded',
  userId: '97234974',
  integrations: {
    "Facebook Offline Conversions": {
      "dataProcessingOptions": [[], 1,1000]
    }
  }
})

Personas

You can send computed traits and audiences generated using Segment Personas to this destination as a user property. To learn more about Personas, contact us for a demo.

For user-property destinations, an identify call is sent to the destination for each user being added and removed. The property name is the snake_cased version of the audience name, with a true/false value to indicate membership. For example, when a user first completes an order in the last 30 days, Personas sends an Identify call with the property order_completed_last_30days: true. When the user no longer satisfies this condition (for example, it’s been more than 30 days since their last order), Personas sets that value to false.

When you first create an audience, Personas sends an Identify call for every user in that audience. Later audience syncs only send updates for users whose membership has changed since the last sync.

Settings

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

Limited Data Use

The Limited Data Use (LDU) setting controls whether or not Data Processing Options are sent to Facebook. When enabling LDU, you must set the user geography values in the Facebook Offline Conversions integration options under the dataProcessingOptions key. If you do not pass specific geography values, Segment will default to empty Data Processing Options.

Map Track Events as CompleteRegistration Conversions to Event Set IDs

Enter your Segment .track() event names on the left that you want to send as CompleteRegistration conversions. On the right hand side, put the ID of the Facebook Offline Event Set where you want to send these conversions.

Map Track Events as Lead Conversions to Event Set IDs

Enter your Segment .track() event names on the left that you want to send as Lead conversions. On the right hand side, put the ID of the Facebook Offline Event Set where you want to send these conversions.

Map Track Events to Event Set IDs

Enter your Segment .track() event names on the left that you want to send as conversions. On the right hand side, put the ID of the Facebook Offline Event Set where you want to send these conversions.

Value Field Identifier

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

oauth

Authorize Segment to oauth

This page was last modified: 20 Oct 2020

Get started with Segment

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