Segment makes it easy to send your data to Facebook App Events (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 App Events in the format they understand. Learn more about how to use Facebook App Events with Segment.
Segment SDK Destination
Simply integrate one of Segment’s latest mobile SDKs into your app and we can send all of the data to Facebook via our servers so you don’t need to add another SDK to your app. This is the recommended method for sending your app event data to Facebook and it doesn’t require adding any additional SDKs.
Once you turn on the Facebook App Events destination in your app’s Segment project, we’ll start sending track data to Facebook’s App Events endpoints.
Track
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.
We’ll automatically translate any of your events that match on 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 destination.
| 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_initated_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 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 trunacte events that are longer than 40 characters long due to Facebook’s API constraints.
If you have specific mappings in Segment’s Facebook App Events integration console, we’ll map from your track event to the specified method name before sending it to Facebook.
We’ll also map the following Segment spec’d properties to Facebook’s equivalents as follows. 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 |
Screen
Our destination 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 destination 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 destination 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.
Packaged Destination
In addition to a serverside destination available for both iOS and Android, there is a client side packaged destination available on iOS. We recommend integrating with the serverside destination, but you can use the packaged destination on iOS if you want.
Track
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. We also 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. We’ll also truncate the event name to 40 characters to conform to Facebook’s identifer requirements.
Other Features
Facebook Login and Facebook Dialogs
The destination 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.
Pre-defined Events and Parameters
The destination 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.
Similarly, 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.
Supported Sources and Connection Modes
| Web | Mobile | Server | |
|---|---|---|---|
| 📱 Device-based | ✅ | ||
| ☁️ Cloud-based | ✅ |
To learn more about about Connection Modes and what dictates which we support, see here.
Segment offers an optional Device-based Connection Mode for Mobile data with Facebook App Events. If you’d like to use those features that require client-based functionality, follow the steps above to ensure you have packaged 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.
App ID
Your Facebook App ID can be retrieved from your Facebook Apps dashboard.
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).
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!