Analytics React Native Facebook App Events Plugin
Getting Started
- From the Segment web app, click Catalog.
- Search for “Facebook App Events” in the Catalog, select it, and choose which of your sources to connect the destination to.
- In the destination settings, enter your Facebook App ID which can be retrieved from your Facebook Apps dashboard.
- Add the Plugin to your project.
Adding the dependency
You need to install the @segment/analytics-react-native-plugin-facebook-app-events
and the react-native-fbsdk-next
dependency.
Using NPM:
npm install --save @segment/analytics-react-native-plugin-facebook-app-events react-native-fbsdk-next
Using Yarn:
yarn add @segment/analytics-react-native-plugin-facebook-app-events react-native-fbsdk-next
Run pod install
after the installation to autolink the Facebook SDK.
Follow the instructions in Configure projects of React-Native-fbsdk-next to finish the setup of FBSDK.
See React Native FBSDK Next for more details of this dependency. The plugin automatically calls the Settings.initializeSDK();
method, so you do not need to explictly add that code to your app. Adding the method again may result in an error.
Using the Plugin in your App
Follow the instructions for adding plugins on the main Analytics client:
In your code where you initialize the analytics client call the .add(plugin)
method with an FacebookAppEventsPlugin
instance:
import { createClient } from '@segment/analytics-react-native';
import { FacebookAppEventsPlugin } from '@segment/analytics-react-native-plugin-facebook-app-events';
const segmentClient = createClient({
writeKey: 'SEGMENT_KEY'
});
segmentClient.add({ plugin: new FacebookAppEventsPlugin() });
Screen
If you’re not familiar with the Segment Specs, take a look to understand what the Screen method does. An example call would look like:
const { screen } = useAnalytics();
screen('ScreenName', {
productSlug: 'example-product-123',
});
This 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. Once enabled, you should start seeing screen
events populate in Facebook App Events. The screen name you provide will be surrounded 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.
Track
If you’re not familiar with the Segment Specs, take a look to understand what the Track method does. An example call would look like:
const { track } = useAnalytics();
track('View Product', {
productId: 123,
productName: 'Striped trousers',
});
When you call track
Segment 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 an event with periods in the name, Segment converts all periods to underscores. So if your event is friend.added
, Segment sends that to Facebook as friend_added
. Segment also truncates events that are longer than 40 characters long due to Facebook’s API constraints.
Facebook Parameters
Segment translates spec-matching 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, Segment sends USD
. If any properties don’t match the below, Segment passes them on as they were sent.
Revenue | _valueToSum |
Currency | fb_currency |
Limited Data Use
In July 2020, Facebook released Limited Data Use feature 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.
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.
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.
Troubleshooting
Not seeing events?
Verify that the IDFA is working within your app, which involves adding the AdSupport and App Tracking Transparency frameworks.
Once 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
The value of context.device.type
must be either ios
or android
.
For example:
{
"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.
This page was last modified: 08 Apr 2024
Need support?
Questions? Problems? Need more info? Contact Segment Support for assistance!