# Facebook App Events Destination ## Destination Info * Accepts [Track](/docs/segment/connections/spec/track) calls. * Refer to it as **Facebook App Events** in the [Integrations object.](/docs/segment/guides/filtering-data/#filtering-with-the-integrations-object) ### Components * [iOS](https://github.com/segment-integrations/analytics-ios-integration-facebook-app-events) * Server ## Connection Modes [Learn more about connection modes.](/docs/segment/connections/destinations/#connection-modes) ### Device-Mode * web: no * mobile: yes * server: no ### Cloud-Mode * web: no * mobile: yes * server: yes > \[!WARNING] > > For new implementations, [Facebook no longer recommends using App Events](https://developers.facebook.com/docs/marketing-api/app-event-api/). Instead, they suggest switching to [Facebook Conversions API (Actions)](/docs/segment/connections/destinations/catalog/actions-facebook-conversions-api/) for all server-side data tracking needs. [Facebook App Events](https://developers.facebook.com/docs/app-events) collects required information from one of Segment's mobile SDKs ([iOS](/docs/segment/connections/sources/catalog/libraries/mobile/ios/), [Android](/docs/segment/connections/sources/catalog/libraries/mobile/android/), or [Swift](/docs/segment/connections/sources/catalog/libraries/mobile/apple/)) and sends it from Segment's servers to Facebook App Events servers. The iOS device-mode connection for the Facebook App Events destination is open source and [available on GitHub](https://github.com/segment-integrations/analytics-ios-integration-facebook-app-events). Segment also has an [Analytics Swift Facebook App Events Plugin](/docs/segment/connections/sources/catalog/libraries/mobile/apple/destination-plugins/facebook-app-events-swift/) for the Facebook App Events device-mode connection available. You can view the [open-source integration code on GitHub](https://github.com/segment-integrations/analytics-swift-facebook-app-events). ## Other Facebook Destinations Supported by Segment This page is about the **Facebook App Events**. For documentation on other Facebook destinations, see the pages linked below. | **Facebook Destination** | Supported by Engage | | ------------------------------------------------------------------------------------------------------------------- | ------------------- | | **[Facebook App Events](/docs/segment/connections/destinations/catalog/facebook-app-events/)** | Yes | | **[Facebook Offline Conversions](/docs/segment/connections/destinations/catalog/facebook-offline-conversions/)** | Yes | | **[Facebook Pixel](/docs/segment/connections/destinations/catalog/facebook-pixel/)** | No | | **[Facebook Custom Audiences](/docs/segment/connections/destinations/catalog/personas-facebook-custom-audiences/)** | Yes | | **[Facebook Conversions API](/docs/segment/connections/destinations/catalog/actions-facebook-conversions-api/)** | Yes | ## Getting Started 1. From the Segment web app, click **Catalog**. 2. Search for "Facebook App Events" in the Catalog, select it, and choose which of your sources to connect the destination to. 3. In the destination settings, enter your Facebook App ID which can be retrieved from your [Facebook Apps dashboard](https://developers.facebook.com/apps/). 4. After 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're not familiar with the Segment Specs, take a look to understand what the [Screen method](/docs/segment/connections/spec/screen/) does. An example call would look like: ```objc [[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 using the integration setting named **Use Screen Events as Track Events**. After enabling, 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**. 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 using the **Map your events to Standard FB App Events** setting. Be sure to specify the event as **Viewed** `name` **Screen** where `name` is the name property of the `screen` event. ## Track If you're not familiar with the Segment Specs, take a look to understand what the [Track method](/docs/segment/connections/spec/track/) does. An example call would look like: ```objc [[SEGAnalytics sharedAnalytics] track:@"Article Completed" properties:@{ @"title": @"How to Create a Tracking Plan", @"course": @"Intro to Analytics" }]; ``` When you call `track` Segment automatically sends 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](/docs/segment/connections/spec/track/#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 Segment automatically translates any of your events that match one of our [spec'd events](/docs/segment/connections/spec/) 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. ## Limited Data Use In July 2020, Facebook released [Limited Data Use feature](https://developers.facebook.com/docs/marketing-apis/data-processing-options) to help businesses comply with the California Consumer Privacy Act (CCPA). This feature limits the way user data is stored and processed for all California residents who opt out of the sale of their data. You can send Limited Data Use data processing parameters to Facebook on each event so that Facebook can appropriately apply the user's data choice. Segment recommends that you first familiarize yourself on this feature and the [Data Processing Options Facebook accepts](https://developers.facebook.com/docs/marketing-apis/data-processing-options). This destination supports the following parameters: * **Data Processing Options** * **Data Processing Options Country** * **Data Processing Options State** You can enable the feature using the **Use Limited Data Use** destination setting and control it using Data Processing Initialization Parameters. > \[!NOTE] > > The **Use Limited Data Use** destination setting is disabled by default for all Facebook destinations except for Facebook Pixel. This must be enabled manually from the destination settings if you're using other Facebook destinations. ### Data Processing Destination Setting You can change the **Use Limited Data Use** destination setting to enable or disable Limited Data Use. This must be enabled (set to "on") if you want to send data processing parameters as part of the the Limited Data Use feature. ### Data Processing Initialization Parameters The Data Processing parameters you set are the Data Processing Options Segment uses when sending data to Facebook. By default, Segment uses the following Data Processing Parameters: | **Data Processing Parameter** | **Default Value** | **What it means** | | ----------------------------------- | ----------------- | ----------------------------------------------- | | **Data Processing Options** | `["LDU"]` | Use Facebook's Limited Data Use processing | | **Data Processing Options Country** | `0` | Use Facebook's geolocation to determine country | | **Data Processing Options State** | `0` | Use Facebook's geolocation to determine state | Facebook uses the `context.ip` to determine the geolocation of the event. You can manually change the Data Processing parameters by adding settings to the `integrations` object. #### Server-side library The example below shows how you might set custom Data Processing parameters for a Segment server library. ```javascript // node library example analytics.track({ event: 'Membership Upgraded', userId: '97234974', integrations: { "Facebook App Events": { "dataProcessingOptions": [[], 1,1000] } } }) ``` #### iOS Device Mode You must use the Facebook App Events integration SDK version `2.0.0` or later to call `setDataProcessingOptions` when you enable the **Use Limited Data Use** destination setting. Events sent from earlier versions of the Facebook App Events integration SDK cannot call `setDataProcessingOptions`, but Facebook still has access to the IP address in the events to process LDU based on geolocation. When you use Segment's mobile libraries, you must set the Data Processing Options when you declare the destination in your app delegate's instance. The example below shows how you might set custom Data Processing parameters in an iOS project. ```objc // Add the bundle FB integration SDK // Set data processing values. SEGFacebookAppEventsIntegrationFactory *fb = [SEGFacebookAppEventsIntegrationFactory instance]; [fb setDataProcessingOptions:@[ @"LDU" ] forCountry:1 forState: 1000]; [config use:fb]; ``` #### Android and iOS Cloud Mode To send the Data Processing Parameters in cloud mode on iOS or Android, you can set them in the integrations object. The example below shows how you might set custom Data Processing parameters in Android. ```java Object[] dataProcessingOptions = new Object[3] dataProcessingOptions[0] = {'LDU'} // options dataProcessOptions[1] = 1 // country dataProcessingOptions[2] = 1000 // state Analytics.with(context).track( "Purchased Item", new Properties(), new Options().setIntegrationOptions( "Facebook App Events", new ImmutableMap.Builder().put("dateProcessingOptions", dataProcessingOptions).build()); ) ``` #### Additional iOS Cloud Mode Set up for iOS 14 With the release of Segment's latest Analytics-iOS SDK, which includes support for upcoming iOS 14 tracking changes, you must decide if you *need* to collect the user's IDFA or not. If you do not need to collect IDFA, you can update your Analytics-iOS SDK to the next version, and Segment sets `device.adTrackingEnabled` to `false`, and starts deleting the `device.advertisingId` from the context object in your payloads. If you *do* need to collect the IDFA, you must import the IDFA closure as a config to the library, or import the Ad Tracking Transparency framework from Apple. Facebook returns a 4xx error due to lack of required parameters if the `device.advertisingId` key does not appear in the payload. To work around this, enable the **Fallback to Zeroed IDFA when advertisingId key not present** destination setting for Facebook App Events from the Segment web app. When you enable this setting, Segment checks for the `device.advertisingId` key, and if none is present, sets the `advertiser_id` in the outbound payload to `'00000000-0000-0000-0000-000000000000'`. ## Other Features ### Facebook Login and Facebook Dialogs 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](https://developers.facebook.com/docs/ios/getting-started#delegate) by accessing [the Facebook SDK directly](/docs/segment/connections/sources/catalog/libraries/mobile/ios/#faq). ### 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](https://developers.facebook.com/docs/app-events/getting-started-app-events-ios). If other pre-defined events are important to you, [contact us](https://segment.com/help/contact/). ## Troubleshooting ### Not seeing events? You will have to be sure that the [IDFA](/docs/segment/connections/sources/catalog/libraries/mobile/ios/#idfa) is working within your app, which involves adding the [AdSupport and App Tracking Transparency frameworks](/docs/segment/connections/sources/catalog/libraries/mobile/ios/#ad-tracking-and-idfa). Similarly, on Android, you'll need to include the Play Services Ads library as [mentioned here](/docs/segment/connections/sources/catalog/libraries/mobile/android/#how-do-you-handle-unique-identifiers-) in order for the `advertisingId` to populate. After you've 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. Facebook requires that payloads include the following: * `context.device.id` * `context.device.type` * `context.os.version` > \[!NOTE] > > The value of `context.device.type` must be either `ios` or `android`. For example: ```json { "anonymousId": "507f191e810c19729de860ea", "event": "Event Name", ​ "context": { "device": { "id": "B5372DB0-C21E-11E4-8DFC-AA07A5B093DB", "type": "ios" }, "os": { "version": "8.1.3" } },​ "messageId": "bbac-11e4-8dfc-aa07a53436b09b45567i8245237824", "type": "track", "userId": "97980cfea0067" } ``` ### 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. ## Engage You can send computed traits and audiences generated using [Engage](/docs/segment/engage) to this destination as a **user property**. To learn more about Engage, schedule a [demo](https://segment.com/contact/demo). For user-property destinations, an [identify](/docs/segment/connections/spec/identify/) call is sent to the destination for each user being added and removed. The property name is the snake\_cased version of the audience name, with a true/false value to indicate membership. For example, when a user first completes an order in the last 30 days, Engage sends an Identify call with the property `order_completed_last_30days: true`. When the user no longer satisfies this condition (for example, it's been more than 30 days since their last order), Engage sets that value to `false`. When you first create an audience, Engage sends an Identify call for every user in that audience. Later audience syncs only send updates for users whose membership has changed since the last sync. > \[!NOTE] > > Real-time audience syncs to Facebook App Events may take six or more hours for the initial sync to complete. Upon completion, a sync frequency of two to three hours is expected. ## Settings Segment lets you change these destination settings from the Segment app without having to touch any code. | Field | Description | Required | Type | | ----------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------- | | 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]\(https://developers.facebook.com/docs/marketing-api/app-event-api/v2.6) 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. | No | map | | App ID | Your Facebook App ID can be retrieved from your \[Facebook Apps dashboard]\(https://developers.facebook.com/apps/). | Yes | string | | Event Parameter Allowlist | Facebook App Events limits the number of event parameters to 25. You may choose to put an allowlist of properties which we will send to Facebook instead. This allowlist 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 allowlist \`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 \`\`\` | No | array | | Limited Data Use | The Limited Data Use (LDU) setting controls whether or not Limited Data Use mode is set in Facebook's Data Processing Options. When enabling LDU, Segment will send default user geography options to request that Facebook geolocate the event. To override the default geography options set the values in the \`Facebook App Events\` integrations object under the \`dataProcessingOptions\` key. | No | boolean | | 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]\(/docs/segment/spec/screen/) you specify). | No | boolean | | Fallback to Zeroed IDFA when advertisingId key not present (Server-Side Only) | With the update to use analytics-ios v4.x SDK if adTrackingEnabled is set to false, the advertisingId key will be deleted from the event. These events will fail when sent to Facebook App Events API. To prevent these event failures in this scenario enable this setting to default to set the IDFA to be zero'd out (ie. '00000000-0000-0000-0000-000000000000') when sent to Facebook App Events. | No | boolean |