Facebook Offline Conversions Destination
Destination Info
- Accepts Track calls.
- Refer to it as Facebook Offline Conversions in the Integrations object
Components
- Server
Facebook Offline Conversions enables offline event tracking, so marketers can run campaigns, upload transaction data, and compare in-store transactions.
Customer Information Parameters Requirements
As of Facebook Marketing API v13.0+, Facebook began enforcing new requirements for customer information parameters (match keys). To ensure your events don’t throw an error, Segment recommends that you review Facebook’s new requirements.
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 Engage |
---|---|
Facebook App Events | Yes |
Facebook Offline Conversions | Yes |
Facebook Pixel | No |
Facebook Custom Audiences | Yes |
Facebook Conversions API | Yes |
Getting Started
-
From the Segment web app, click Catalog.
-
Search for “Facebook Offline Conversions” in the Catalog, select it, and choose which of your sources to connect the destination to.
-
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.
- 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 unwantedtrack
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_id s 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 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.
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]
}
}
})
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.
Real-time to batch destination sync frequency
Real-time audience syncs to Facebook Offline Conversions may take six or more hours for the initial sync to complete. Upon completion, a sync frequency of two to three hours is expected.
Settings
Segment lets you change these destination settings from the Segment app without having to touch any code.
Setting | Description |
---|---|
Map Track Events as CompleteRegistration Conversions to Event Set IDs | text-map , defaults to {}. 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 to Event Set IDs | text-map , defaults to {}. 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. |
Map Track Events as Lead Conversions to Event Set IDs | text-map , defaults to {}. 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. |
Limited Data Use | boolean , defaults to FALSE . 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. |
oauth | oauth , defaults to {}. Authorize Segment to oauth <UPDATE> |
Value Field Identifier | select , defaults to value. 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. |
This page was last modified: 27 Oct 2023
Need support?
Questions? Problems? Need more info? Contact Segment Support for assistance!