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