Facebook Offline Conversions Destination

Segment makes it easy to send your data to Facebook Offline Conversions (and lots of other destinations). Once you've tracked your data through our open source libraries we'll translate and route your data to Facebook Offline Conversions in the format they understand. Learn more about how to use Facebook Offline Conversions with Segment.

Getting Started

In order to send your server side .track() events as offline conversions to Facebook’s Offline Event Sets, you must first authorize Segment to send data on your behalf by connecting through our OAuth. You can do so in your destination settings page:

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.

Additional Prerequisite Configurations

Before you can activate the destination, there are a few event mappings you should set up to get your data flowing.

Since we do not want to send unwanted .track() events as conversions, 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.

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

Sending .track() Events to Offline Sets

There are three 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 NameFacebook Semantic Conversion Event Name
Products SearchedSearch
Product ViewedViewContent
Product List ViewedViewContent
Product Added to WishlistAddToWishlist
Product AddedAddToCart
Checkout StartedInitiateCheckout
Payment Info EnteredAddPaymentInfo
Order CompletedPurchase

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 PropertyFacebook Semantic Conversion Parameters
Hardcoded as "Segment"upload_tag
timestampevent_time
See event name mapping aboveevent_name
currencycurrency
value, price, or revenuevalue
Hardcoded as "product" or "product_group"content_type
products.$.product_ids or category*content_ids
Any remaining propertiescustom_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 PropertiesFacebook Match Key Parameters
emailemail
phonephone
gendergen
firstName or namefn
lastName or nameln
address.cityct
address.statest
address.postalCodezip
address.countrycountry
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 via 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.


Supported Sources and Connection Modes

WebMobileServer
📱 Device-based
☁️ Cloud-based

To learn more about about Connection Modes and what dictates which we support, see here.

Settings

Segment lets you change these destination settings via your Segment dashboard without having to touch any code.

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

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.

oauth

Authorize Segment to oauth

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.


If you have any questions or see anywhere we can improve our documentation, please let us know or kick off a conversation in the Segment Community!