App Events for Android
App Events help you understand the makeup of people who engage with your app and measure and reach specific sets of your users with Facebook mobile app ads. This is done by logging events from your app via Facebook's Android SDK. The event can be one of 14 predefined events such as 'added to cart' in a commerce app or 'level achieved' in a game, or any custom events you can define.
Prerequisites
Before including the code to measure events, you'll need to register your app with Facebook and download and configure the Facebook SDK. See our getting started guide to learn more.
Implementation
Facebook's SDK provides two helper methods for app activation and purchases, the two most common types of events.
Logging app activations
Logging app activations as an App Event enables almost all other functionality and should be the first thing that you add to your app. The SDK provides a helper method to log app activation. By logging an activation event, you can observe how frequently users activate your app, how much time they spend using it, and view other demographic information through Facebook Analytics for Apps.
On Android, the SDK's app activation helper should typically be invoked in each long-lived Activity's onResume() method:
@Override
protected void onResume() {
super.onResume();
AppEventsLogger.activateApp(this);
}
The app deactivation helper should be invoked in the onSuspend() method of each activity that calls activateApp in its onResume:
@Override
protected void onPause() {
super.onPause();
AppEventsLogger.deactivateApp(this);
}
The motivation for 'long-lived Activities' is that when an app is backgrounded and returns to the foreground, one would typically want to log another activateApp. Putting the logging in onResume() on the large-scale Activities will typically result in that desired behavior.
Purchase methods
Much like logging app activations, the Facebook SDK provides a helper method to log purchases with a single line of code. For example, a purchase of USD $4.32, can be be logged with:
logger.logPurchase(BigDecimal.valueOf(4.32), Currency.getInstance("USD"));
The currency specification is expected to be an ISO 4217 currency code. This is used to determine a uniform value for use in ads optimization.
The maximum number of different event names is 300. Note that events can’t be removed and no new event types will be logged once this cap is hit. Read more about event limits in the FAQ.
Logging Events Manually
For all other types of events create an AppEventsLogger
and then log your events. To create a AppEventsLogger
:
AppEventsLogger logger = AppEventsLogger.newLogger(this);
where this
is the Activity your method is in.
You can then log your event to logger
:
logger.logEvent(AppEventsConstants.EVENT_NAME_{XXXXX});
Where AppEventConstants.EVENT_NAME_{XXXX}
is one of the constants shown in the Events table below.
You can also specify a set of parameters in a Bundle
and a valueToSum
property which is an arbitrary number that can represent any value (e.g., a price or a quantity). When reported, all of the valueToSum
properties will be summed together. For example, if 10 people each purchased one item that cost $10 (and passed in valueToSum
) then they would be summed to report a number of $100.
Bundle parameters = new Bundle();
parameters.putString(AppEventsConstants.EVENT_PARAM_CURRENCY, "USD");
parameters.putString(AppEventsConstants.EVENT_PARAM_CONTENT_TYPE, "product");
parameters.putString(AppEventsConstants.EVENT_PARAM_CONTENT_ID, "HDFU-8452");
logger.logEvent(AppEventsConstants.EVENT_NAME_ADDED_TO_CART,
54.23,
parameters);
Note that both the valueToSum
and parameters
arguments are optional.
The full list of pre-defined events and pre-defined parameters are listed below.
Events
Each of these events can be logged with a valueToSum
and a set of parameters (up to 25 parameters). The table below shows the recommended events and what are typically useful parameters for each event (the common parameter names are defined in the next table). You should include the events that make sense based on the user actions in your app.
AppEventsConstants::EVENT_NAME_* | valueToSum | Parameters |
---|---|---|
|
| |
| ||
|
| |
| Price of item added |
|
| Price of item added |
|
|
| |
|
| |
| Total price of items in cart |
|
| purchase price |
|
| Rating given |
|
|
| |
| Total value of credits spent |
|
|
| |
| Price of item viewed (if applicable) |
|
Parameters
The table below are typically useful parameters for inclusion with the events shown above or with your own custom events. Future enhancements to our insights product will use the recommended parameters, but note that you can provide your own parameters as well.
These pre-defined parameters are intended to provide guidance on typically useful logging patterns, and may have a more readable form in reporting and other UI. Your app should log the set of parameters that it's interested in seeing breakdowns on in insights. The recommended description for these are guidance only - you can use these parameters for whatever makes sense for your app.
The parameters are passed via a Bundle
where the key holds the parameter name and the value either a String
or an int
, as shown below. If you provide another type of value that is not compliant such as a boolean
, the SDK logs a warning to LogginBehavior.APP_EVENT
.
AppEventConstants::EVENT_PARAM_* | Possible Values | Description |
---|---|---|
| string | International Article Number (EAN) when applicable, or other product or content identifier |
| string | 'product' or 'product_group' |
| string | ISO 4217 code, e.g., "EUR", "USD", "JPY" |
| string | A string description |
| string | Level of a game |
| int | Upper bounds of a rating scale, for example 5 on a 5 star scale |
| int | Number of items |
| '1' or '0' | 1 for yes, 0 for no |
| string | Facebook, Email, Twitter, etc. |
| string | The text string that was searched for |
| '1' or '0' | 1 for yes, 0 for no |
Custom App Events
You can also choose to create your own custom events, which is done simply by specifying their name as a string:
logger.logEvent("battledAnOrc");
API reference documentation
More details about the AppEventsLogger
class can be found in the reference documentation.
Verifying Event Logging in Facebook Analytics for Apps
If you're an Admin or a Developer of an app, you can validate that you've correctly implemented app events in Facebook Analytics for Apps. Please see our documentation on debugging events in Facebook Analytics for Apps to learn how to verify that events are being logged.
Analytics for Apps
Enabling App Events means that you can automatically start using Facebook Analytics for Apps. This analytics channel provides demographic info about the people using your app, offers tools for better understanding the flows people follow in your app, and lets you compare cohorts of different kids of people performing the same actions.
See our documentation for Facebook Analytics for Apps for more information.

Facebook Ads
Mobile App Ad Performance
You can use app events to better understand the engagement and ROI coming from your mobile ads on Facebook. If you've set up app events, they will be reported as different types of actions in Ads Manager so you can see which ads and campaigns resulted in what actions within your app. For example, you may see that a particular ad resulted in 10 total actions. Those actions could be 8 checkouts and 2 registrations, which will be specified in Ads Manager.
Mobile App Ad Targeting
Measuring app events also opens up an easier way to reach your existing app users for mobile app ads. After integrating app events, you will be able to reach your existing users, specific subsets of users based on what actions they have taken within your app, or even percentages of your most active users. For instance you can run ads to bring recent purchasers back into your app to complete more purchases or to your top 25% of purchasers. You can choose an audience to reach based on the app events you are measuring in your app.
To learn more about our mobile app ads, go to our tutorial on mobile app ads for installs or mobile app ads for engagement.
Ads Attribution
Once you've implemented app events into your Android app, the app events you've added will automatically be tracked when you run Facebook mobile app ads. Initially, we will only track the 14 predefined events described above.
If using Power Editor to set up your ad, please ensure you use the default tracking settings, or if you manually configure tracking settings that the following tracking_spec is present, with <app_id> replaced with your app's Facebook App Id.
{"action.type" : ["app_custom_event"],
"application" : [<app_id>]}
What's reported:
If you have set up app events, they will be reported as different types of actions in Ads Manager. For example, you may see that a particular ad resulted in 10 total actions. Those actions could be 8 checkouts and 2 registrations, which will be specified in Ads Manager.
We offer a range of different attribution windows to choose from. Here's a breakdown of the various sources of Facebook app events reporting available to developers and the attribution methodology used across each:
- In the default Campaign Report, Ads Manager reports on app events based on a 1 day view and 28 day click attribution window. This represents the count of events that took place within 24 hours of someone viewing the ad or 28 days after clicking on it.
- In the full Actions by Impression Time Report we offer advertisers a range of attribution windows to select from when tracking app events, based on what is most meaningful for their business. Advertisers can see a count of events that happen within 1 day, 7 days, and 28 days after a person clicks on an ad, and 1 day, 7 days, and 28 days after viewing an ad when they export the Actions by Impression time report to Excel.
In order to view actions attributed to ads, go to Ads Manager and choose your specific campaign and ad group. You should see a chart similar to this:
Data Control
The Facebook SDK offers a tool to give your users control over how app events data is used by the Facebook ads system. Platform Policy requires that you provide users with an option to opt-out when sharing this information with Facebook. We recommend that you use our SDK tools to offer the opt-out. The tool is described below.
setLimitEventUsage behavior
If the user has set the limitEventUsage flag to true
, your app will continue to send this data to Facebook, but Facebook will not use the data to serve targeted ads. Facebook may continue to use the information for other purposes, including frequency capping, conversion events, estimating the number of unique users, security and fraud detection, and debugging.
AppEventsLogger.setLimitEventUsage(this, true);
where this
may be the Activity
your in, or another Context
in the app.
The limitEventUsage
setting will persist across app sessions. To use this property, you can match your opt-out's UI to the value of the limitEventUsage flag.
Data Sharing
App Event data shared by you with Facebook will not be shared with advertisers or other third parties, unless we have your permission or are required to do so by law.