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, please let us know!

Getting Started

The first step is to make sure Facebook Offline Conversions supports the source type and connection mode you’ve chosen to implement. You can learn more about what dictates the connection modes we support here.

WebMobileServer
📱 Device-based
☁️ Cloud-based
  1. From your Segment UI’s Destinations page click on “Add Destination”.

  2. Search for “Facebook Offline Conversions” within the Destinations Catalog and confirm the Source you’d like to connect 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 Facebok Business Manager account and clicking the desired Offline Event Set here:

Track

If you haven’t had a chance to review our spec, please 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 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.


If you have any questions, or see anywhere we can improve our documentation, please let us know!