App Events for Android

Implementation

You can easily insert these app events into your Android apps by creating an AppEventsLogger and then logging your events.

If your app uses the UiLifecycleHelper class, then create your logger as such:

AppEventsLogger logger = myUiLifecycleHelper.getAppEventsLogger();

If you don't use UiLifecycleHelper, then create your logger like this:

AppEventsLogger logger = AppEventsLogger.newLogger(this);

where the this is the Activity your method is in.

You 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, "shoes");
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.

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.

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");

Purchase methods

While calls to logEvent can be made to register purchase events, there is a helper method that explicitly takes a currency indicator. A purchase of USD $4.32, for example, can be be invoked as:

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.

Logging app activations

Developers can observe how frequently users activate their app and how long they use it by logging app activation and app deactivation events. Like purchase, there is a helper for logging app activation and deactivation. For Android, app activation helper typically should be invoked in each long-lived Activity's onResume() method, as follows:

@Override
protected void onResume() { 
  super.onResume(); 
  AppEventsLogger.activateApp(this); 
}

App deactivation helper should be invoked in the onSuspend() method of each activity that calls activateApp in its onResume. This should be invoked as follows:

@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.

API reference documentation

More details about the AppEventsLogger class can be found in the reference documentation.

Verification

If you're an Admin or a Developer of an app, and want to validate that you've correctly implemented app events, go to App Insights, choose your app and then select 'App Events' from the left hand menu (this will not appear until your app starts logging events). The bottom half of this page will have a "Most recently logged events" section that looks like the following:

This table lists the last 20 events logged by your app, including the event name, app version, device type, value and parameters logged with the event. Events show up here as soon as they've been transmitted to the server from your mobile app.

You can pinpoint events coming from a version under development (vs. one that's in production) by choosing the App Version dropdown as shown in the image above. This will filter the events shown to that version. (The App Version for your app will be logged automatically based on the version identifier in the Android app itself.) You can similarly filter by Event Name.

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:

App Insights

App events reporting is also available in App Insights, which provides a measure of total app events for an app broken down by demographic. In order to view demographic insights about the users of your mobile app, 1) go to App Insights, 2) choose your app and then choose App Events from the left hand menu. You should see a graph similar to this:

This graph shows the app events that have been received by Facebook for your app. You can then drill down and get details of the different events by clicking on the event name in the table at the bottom of this graph. For instance, clicking on the "Purchase on Device" link will lead to a chart with details on Mobile Purchase events, including this table of demographics at the bottom:

By viewing this chart, you can identify the age, gender, country and locale breakdown of your app users, as well as device usage and breakdown by the parameters that were logged with your event.

You can also view the distribution of users taking action to understand what percentiles are most active or are contributing the most value. More than that, you can even choose to target a range of people within those percentiles for advertising to effectively reach them.