Facebook App Events Destination

Facebook App Events collects required information from one of Segment’s mobile SDKs (iOS or Android) and sends it from Segment’s servers to Facebook App Events servers. This server-to-server connection will not work with our server-side libraries. The Facebook App Events Destination is open-source. You can browse the code on GitHub for iOS.

This document was last updated on October 04, 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!

Use Cases

Improve mobile app retention with Facebook Ads

Getting Started

The first step is to make sure Facebook App Events 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.

	Web	Mobile	Server
📱 Device-mode		✅
☁️ Cloud-mode		✅	✅

From your Segment UI’s Destinations page click on “Add Destination”.
Search for “Facebook App Events” within the Destinations Catalog and confirm the Source you’d like to connect to.
Drop in your Facebook App ID which can be retrieved from your Facebook Apps dashboard.
Once you turn on the Facebook App Events integration in your app’s Segment project, we’ll start sending track data to Facebook’s App Events endpoints.

Screen

If you haven’t had a chance to review our spec, please take a look to understand what the Screen method does. An example call would look like:

[[SEGAnalytics sharedAnalytics] screen:@"Photo Feed"
                            properties:@{ @"Feed Type": @"public" }];

Our integration also supports using Segment screen events as track events. For example, if you had a screen event named Confirmation you could map the invocation of this to a Facebook app event as you would with Segment track events.

To use this functionality you must opt into it via the integration setting named Use Screen Events as Track Events. Once enabled, you should start seeing screen events populate in Facebook App Events. The screen name you provide will be bookended with the words Viewed and Screen. So, if you have a screen event with the name property set to Welcome, it will show up in Facebook as an event called Viewed Welcome Screen.

Please note, the integration will not automatically translate screen events to spec’d Facebook events as our track method does. If you would like to map these events to specific Facebook events you can do this via the Map your events to Standard FB App Events setting. Please be sure to specify the event as Viewed name Screen where name is the name property of the screen event.

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:

[[SEGAnalytics sharedAnalytics] track:@"Article Completed"
                           properties:@{ @"title": @"How to Create a Tracking Plan", @"course": @"Intro to Analytics" }];

When you call track we’ll automatically send that event and it’s properties to Facebook. In the Facebook analytics interface you’ll be able to use the event properties to segment your data.

Facebook App Events doesn’t like events with periods in the name so if you send us an event with periods in the name, we’ll convert all periods to underscores. So if your event is friend.added, we’ll send that to Facebook as friend_added. We also truncate events that are longer than 40 characters long due to Facebook’s API constraints.

Facebook Parameters

We automatically translate our spec’d properties revenue and currency to the appropriate Facebook parameters (valueToSum and FBSDKAppEventParameterNameCurrency), and also send events with revenue to Facebook’s purchase logging method (logPurchase).

If you don’t provide a currency explicitly, we send USD. If any properties don’t match the below, we’ll pass them on as they were sent to us.

Revenue	_valueToSum
Currency	fb_currency
name	fb_description
product_id	fb_content_id
category	fb_content_type
query	fb_search_string
timestamp	_logTime
quantity	fb_num_items

Facebook Events

We’ll automatically translate any of your events that match one of our spec’d events that map to Facebook’s spec’d events. The below table shows the out of the box mappings in our integration:

Application Installed	MOBILE_APP_INSTALL
Application Opened	fb_mobile_activate_app
Products Searched	fb_mobile_search
Product Viewed	fb_mobile_content_view
Product Added	fb_mobile_add_to_cart
Product Added to Wishlist	fb_mobile_add_to_wishlist
Payment Info Entered	fb_mobile_add_payment_info
Checkout Started	fb_mobile_initiated_checkout
Order Completed	fb_mobile_purchase

If you send a track event that doesn’t match one of the above events, we’ll send it along to Facebook with the name you provide Segment.

Facebook Recommended Events

The most important events that can help advertisers improve campaign ROI are the conversion events or events closest to the conversion. Those events are marked with an “*” within Segment’s Facebook App Events settings page.

In addition, there are special requirements for dynamic ads. These events are marked with “m” for dynamic ads for mobile, and “t” for dynamic ads for travel within Segment’s Facebook App Events settings page.

Other Features

The integration does not automatically support Facebook Login and Facebook Dialogs out of the box (you’d need to write code here regardless!). To use these features you’ll need to set up Facebook’s app delegate hooks by accessing the Facebook SDK directly.

Packaged Integration

In addition to the integration available for both iOS and Android, there is a client-side packaged integration available on iOS. We recommend integrating with the Segment server-to-server integration, but you can use the packaged integration on iOS if you want.

Pre-defined Events and Parameters

The integration currently only supports the FBSDKAppEventNameActivatedApp pre-defined event (via the activateApp handler). All other events are forwarded as custom events. If other pre-defined events are important to you, please contact us.

Troubleshooting

Not seeing events?

You will have to be sure that the IDFA is working within your app, which involves adding the iAD framework.

Simiarly, on Android, you’ll need to include the Play Services Ads library as mentioned here in order for the advertisingId to populate.

Once you have added these, you will start to see the context.device.advertisingId populate and the context.device.adTrackingEnabled flag set to true unless the user has ad tracking limited or is using a mobile ad blocker.

Note: While the network is deprecated, the relevant iOS framework is not.

Missing custom events

Facebook will only accept custom events with alphanumeric names (you can include spaces, “-“ and “_“) that are between 2 and 40 characters in length. Otherwise, Facebook will reject the event payload with a 400 status.

Personas

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

For user-property destinations, an identify call will be sent to the destination for each user being added and removed. The property name will be the snake_cased version of the audience name you provide with a true/false value. For example, when a user first completes an order in the last 30 days, we will send an identify call with the property order_completed_last_30days: true, and when this user no longer satisfies we will set that value to false.

When the audience is first created an identify call is sent for every user in the audience. Subsequent syncs will only send updates for those users which were added or removed since the last sync.

Segment offers an optional Device-mode for Mobile data with Facebook App Events. If you’d like to use features that require client-based functionality, follow the steps above to package the Facebook App Events SDK with Segment’s.

Settings

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

Map your events to Standard FB App Events

Enter your events on the left and the Facebook standard event to map to on the right. Facebook recognizes certain standard events that can be used across Custom Audiences, custom conversions, conversion tracking, and conversion optimization. When you map an event to a standard Facebook event, we’ll send the event by that name. Any unmapped events will still be sent as Custom Events.

Facebook Recommended Events

The most important events that can help advertisers improve campaign ROI are the conversion events or events closest to the conversion. Those events are marked with an *.

In addition, there are special requirements for dynamic ads. These events are marked with “m” for dynamic ads for mobile, and “t” for dynamic ads for travel.

App ID

Your Facebook App ID can be retrieved from your Facebook Apps dashboard.

Event Parameter Whitelist

Facebook App Events limits the number of event parameters to 25. You may choose to put a whitelist of properties which we will send to Facebook instead. This whitelist will be respected exactly (or not at all, if you choose not to use it), the only exception being that we will automatically send _eventName to ensure all events are valid. Top-level properties will be mapped exactly. (For example, if you whitelist someProp then we will send someProp‘s value). We otherwise make the following conversions for Facebook-spec’d events. Use the value on the right-hand side if you wish to send these properties as we calculate them.

revenue: _valueToSum
price: _valueToSum
currency: fb_currency
name: fb_description
id: fb_content_id
product_id: fb_content_id
productId: fb_content_id
category: fb_content_type
The version of your app: _appVersion
The timestamp of the event: _logTime
query: fb_search_string
quantity: fb_num_items
number of items in products: fb_num_items
list of ids in products: fb_content_id

Use Screen Events as Track Events

This setting allows you to track your Segment screen events as though they were track events. If enabled, we will being routing screen events from this source to Facebook App Events formatted as Viewed name Screen (where name is the screen name you specify).

Adding Facebook App Events to the integrations object

To add Facebook App Events to the integrations JSON object (for example, to filter data from a specific source), use one of the 1 valid names for this integration:

Facebook App Events