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.

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.

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

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!