Facebook Offline Conversions Destination

Destination Info

• Accepts Track calls.
• Refer to it as Facebook Offline Conversions in the Integrations object

Components

• Server

Connection Modes

Device-mode	Cloud-mode
Web	Web
Mobile	Mobile
Server	Server

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

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.

Getting Started

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:

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:

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:

// 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 explicitly 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 occurring.

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.

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.

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]
    }
  }
})

Engage

You can send computed traits and audiences generated using Engage to this destination as a user property. To learn more about Engage, schedule 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, Engage 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), Engage sets that value to false.

When you first create an audience, Engage 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.