Getting Started with App Events for Android

App Events is a feature of the Facebook SDK for Android that allows you to target, measure, and optimize the delivery of your ads to people most likely to take action. This guide shows you how to add app events from your new or existing app by integrating the Facebook SDK and then adding events to your app.

Requirements

You'll need the following before you can add app events to your app:

1. Select an App or Create a New App

Please select an app or create a new one.

Set Your App Advertising Details

After you create an app, go to your App Dashboard. Select the app you wish to view. In the left side navigation panel of the App Dashboard, click Settings > Basic to view the App Details Panel with your App ID, your App Secret, and other details about your app. To set up your app for advertising set the following details:

  • App Domains - Provide Google Play URL of your app.
  • Platform - Scroll to the bottom of the Settings page to add the Android Platform.
  • Privacy Policy URL - You must provide a Privacy Policy URL. Must be provided to take your app public.
  • Terms of Service URL - You must provide a Terms of Service URL.
See the App Development docs to add more details to your app.

To run ads and measure installs in the Ads Manager, you need to associate at least one Ad Account with your App.

  1. In the App Dashboard click Settings > Advanced.
  2. In Authorized Add Account IDs, add your Ad Account IDs. You can get your ad account IDs from your Ads Manager.
  3. If you also have a business account, in Authorized Businesses, add your Business Manager ID. You can find your business manager id in the URL of your Business Manager

3. Integrate the Facebook SDK in Your App

When you use the Facebook SDK, some events in your app are automatically logged and collected for Facebook Analytics unless you disable automatic event logging. For details about what information is collected and how to disable automatic event logging, see Automatic App Event Logging.

To add the Facebook SDK to a project, add the SDK as a build dependency.

If you're adding the SDK to an existing project, start at step 3.

  1. Go to Android Studio | Start a new Android Studio project | Application name | Minimum SDK.
  2. Select API 15: Android 4.0.3 9 (IceCreamSandwich) or higher and click Next.
  3. Click Basic Activity and then click Next, and then Finish.
  4. In your project, open <your_app> | Gradle Scripts | build.gradle (Project) and add the following to the buildscript { repositories {}} section to download the SDK from the Maven Central Repository:
    mavenCentral()
  5. In your project, open <your_app> | Gradle Scripts | build.gradle (Module: app) and add the following to the dependencies{} section to compile the latest version of the SDK:
    implementation 'com.facebook.android:facebook-android-sdk:[4,5)'
    
  6. Add a meta-data element to the application element:
    
    <application android:label="@string/app_name" ...>
        ...
        <meta-data android:name="com.facebook.sdk.ApplicationId" android:value="@string/facebook_app_id"/>
        ...
    </application>
    
    
  7. Build your project.

4. Add Your Facebook App ID

Create strings for your Facebook app ID and for those needed to enable Chrome Custom Tabs. Also, add FacebookActivity to your Android manifest.

  1. Open your /app/res/values/strings.xml file and add the following:
    <string name="facebook_app_id">[APP_ID]</string>
  2. Open the /app/manifest/AndroidManifest.xml file and add the following: user-permission element after the application element:
    <user-permission android:name="android.permission.INTERNET"/>

5. Tell Us about Your Android Project

Package Name
Your package name uniquely identifies your Android app. We use this to let people download your app from Google Play if they don't have it installed. You can find this in your Android Manifest or your app's build.gradle file.
Default Activity Class Name
This is the fully qualified class name of the activity that handles deep linking such as com.example.app.DeepLinkingActivity. We use this when we deep link into your app from the Facebook app. You can also find this in your Android Manifest.

6. Add Your Development and Release Key Hashes

To ensure the authenticity of the interactions between your app and Facebook, you need to supply us with the Android key hash for your development environment. If your app has already been published, you should add your release key hash too.
Generating a Development Key Hash
You'll have a unique development key hash for each Android development environment.
Mac OS
To generate a development key hash, open a terminal window and run the following command:
      
keytool -exportcert -alias androiddebugkey -keystore ~/.android/debug.keystore | openssl sha1 -binary | openssl base64
Windows
You will need the following: To generate a development key hash, run the following command in a command prompt in the Java SDK folder:
      
keytool -exportcert -alias androiddebugkey -keystore "C:\Users\USERNAME\.android\debug.keystore" | "PATH_TO_OPENSSL_LIBRARY\bin\openssl" sha1 -binary | "PATH_TO_OPENSSL_LIBRARY\bin\openssl" base64
      
This command will generate a 28-character key hash unique to your development environment. Copy and paste it into the field below. You will need to provide a development key hash for the development environment of each person who works on your app.
Generating a Release Key Hash
Android apps must be digitally signed with a release key before you can upload them to the store. To generate a hash of your release key, run the following command on Mac or Windows substituting your release key alias and the path to your keystore:
      
keytool -exportcert -alias YOUR_RELEASE_KEY_ALIAS -keystore YOUR_RELEASE_KEY_PATH | openssl sha1 -binary | openssl base64
This will generate a 28-character string that you should copy and paste into the field below. Also, see the Android documentation for signing your apps.
Key Hashes

6. Add App Events

There are three types of App Events: Automatically Logged Events, Pre-defined Events, popular events that Facebook has created for you, and Custom Events, events you create that are specific to your app.

You can set up pre-defined events and custom events events in two ways:

  • Use our codeless set up tool in Facebook's Events Manager: This is a simple tool for setting up events without implementing codes. You can interact with app screen elements such as such as buttons, images or links to define event names. As your users navigate through the app and interact with these UI elements, events will be sent to Facebook.

  • Install your app event codes manually: You will need to add event codes manually to your app. To learn where to place your App Event code in your app, we have example apps with a screen by screen breakdown of the different events and parameters that can be collected in our Best Practices Guide.

Automatically Logged Events

Beginning with the Facebook Android SDK v4.19, the SDK automatically logs app installs, app sessions, and in-app purchases.

Important: For the Facebook SDK for Android v4.18, and earlier, SDK initialization is a manual process that differs from the manual event logging process described below. See the Legacy SDK Initialization section to manually add an event.

After you integrate the Facebook SDK into your app, the following events are automatically logged.

EventDetails

App Install

The first time a new user activates an app or the first time an app starts on a particular device.

App Launch

When the Facebook SDK is initialized in your app for each session.

In-App Purchase

When a purchase processed by the Apple App Store or Google Play has been completed. If you use other payments platforms, you will need to add purchase event code manually.

Because these events are already in the Facebook SDK there is no need to add these events to your code.

Disable Automatically Logged Events

To disable automatic event logging, add the following line to your AndroidManifest.xml file:

<application>
  ...
  <meta-data android:name="com.facebook.sdk.AutoLogAppEventsEnabled"
           android:value="false"/>
  ...
</application>

In some cases, you may wish only to delay the collection of automatically logged events, such as to obtain user consent or fulfill legal obligations. In this case, add the same code to your manifest:

<application>
  ...
  <meta-data android:name="com.facebook.sdk.AutoLogAppEventsEnabled"
           android:value="false"/>
  ...
</application>

Then re-enable auto-logging after an end-user provides consent, by calling the setAutoLogAppEventsEnabled() method of the FacebookSDK class.

setAutoLogAppEventsEnabled(true);

To suspend logging again for any reason, set the setAutoLogAppEventsEnabled() method to false.

setAutoLogAppEventsEnabled(false);

Pre-defined Events

You can add pre-defined events, see the Event Names and Event Parameters below, to your app. Use the Code Generator to get the code for these events.

To Generate Code for a Pre-defined Event

  1. Choose the Pre-Defined Event tab.
  2. In Event Name, choose a pre-defined event.
  3. Choose Get Code.
  4. In the window, select a language to see the code to copy and paste into your app.

Take a look at our Example Apps to view some scenarios of using App Events.

Event Names

AppEventsConstants Value valueToSum Parameters

Achieved Level:

EVENT_NAME_ACHIEVED_LEVEL

LEVEL

App Launched:

EVENT_NAME_ACTIVATED_APP

Added Payment Info:

EVENT_NAME_ADDED_PAYMENT_INFO

SUCCESS

Added to Cart:

EVENT_NAME_ADDED_TO_CART

Price of item added

CONTENT_TYPE, CONTENT_ID or CONTENT, and CURRENCY

Added to Wishlist:

EVENT_NAME_ADDED_TO_WISHLIST

Price of item added

CONTENT_TYPE, CONTENT_ID or CONTENT, and CURRENCY

Completed Registration:

EVENT_NAME_COMPLETED_REGISTRATION

REGISTRATION_METHOD

Completed Tutorial:

EVENT_NAME_COMPLETED_TUTORIAL

SUCCESS, and CONTENT_ID or CONTENT

Initiated Checkout:

EVENT_NAME_INITIATED_CHECKOUT

Total price of items in cart

CONTENT_TYPE, CONTENT_ID or CONTENT,NUM_ITEMS, PAYMENT_INFO_AVAILABLE, and CURRENCY

Purchased:

EVENT_NAME_PURCHASED

purchase price

NUM_ITEMS, CONTENT_TYPE, CONTENT_ID or CONTENT, and CURRENCY

Rated:

EVENT_NAME_RATED

Rating given

CONTENT_TYPE , CONTENT_ID or CONTENT, and MAX_RATING_VALUE

Searched:

EVENT_NAME_SEARCHED

CONTENT_TYPE, SEARCH_STRING and SUCCESS

Spent Credits:

EVENT_NAME_SPENT_CREDITS

Total value of credits spent

CONTENT_TYPE, and CONTENT_ID or CONTENT

Unlocked Achievement:

EVENT_NAME_UNLOCKED_ACHIEVEMENT

DESCRIPTION

Viewed Content:

EVENT_NAME_VIEWED_CONTENT

Price of item viewed (if applicable)

CONTENT_TYPE, CONTENT_ID or CONTENT, and CURRENCY

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

If you need to remove obsolete parameters - you can deactivate parameters by following the instructions in our help center.

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

Content ID:

EVENT_PARAM_CONTENT_ID

string

International Article Number (EAN) when applicable, or other product or content identifier

Content:

EVENT_PARAM_CONTENT

string

A list of JSON object that contains the International Article Number (EAN) when applicable, or other product or content identifier(s) as well as additional information about the products. id, quantity, and item_price are the available fields. e.g. "[{\"id\": \"1234\", \"quantity\": 2, \"item_price\": 5.99}, {\"id\": \"5678\", \"quantity\": 1, \"item_price\": 9.99}]"

Content Type:

EVENT_PARAM_CONTENT_TYPE

string

'product' or 'product_group'

Currency:

EVENT_PARAM_CURRENCY

string

ISO 4217 code, e.g., "EUR", "USD", "JPY"

Description:

EVENT_PARAM_DESCRIPTION

string

A string description

Level:

EVENT_PARAM_LEVEL

string

Level of a game

Max. Rating Value:

EVENT_PARAM_MAX_RATING_VALUE

int

Upper bounds of a rating scale, for example 5 on a 5 star scale

Number of Items:

EVENT_PARAM_NUM_ITEMS

int

Number of items

Payment Info Available:

EVENT_PARAM_PAYMENT_INFO_AVAILABLE

1 or 0

1 for yes, 0 for no

Registration Method:

EVENT_PARAM_REGISTRATION_METHOD

string

Facebook, Email, Twitter, etc.

Search String:

EVENT_PARAM_SEARCH_STRING

string

The text string that was searched for

Success:

EVENT_PARAM_SUCCESS

1 or 0

1 for yes, 0 for no

Custom App Events

You can also create your own custom events. Use the Code Generator to generate code for these events.

Do not use event as the name of a parameter. Custom parameters with the name event will not be logged. Use another name or add a prefix or suffix to the name, such as my_custom_event.

To Generate Code for a Custom Event

  1. Choose the Custom Event tab.
  2. In Event Name, enter the name of your event.
  3. Click Add Event Paramter if you'd like to add parameters to your event.
  4. Click Get Code.
  5. In the window, select a language to get the code to copy and paste into your app.

To log a custom event, just pass the name of the event as a string:

logger.logEvent("battledAnOrc");

Take a look at our Example Apps to view some scenarios of using App Events.

Legacy SDK Initialization

In the Facebook Android SDK v4.18 and earlier, the SDK must be initialized and app activation events logged explicitly. The SDK provides a helper method to log the app activation event.

On Android, invoke the SDK's app activation helper once when the application is created. The following code demonstrates how to initialize the SDK and log the app activation event in the Application class:

package com.example.hellofacebook;

import android.app.Application;

import com.facebook.FacebookSdk;
import com.facebook.appevents.AppEventsLogger;

public class HelloFacebookSampleApplication extends Application {
    @Override
    public void onCreate() {
        super.onCreate();
        FacebookSdk.sdkInitialize(getApplicationContext());
        AppEventsLogger.activateApp(this);
    }
}

Example Apps

We have created some examples for different app types in order to make it easier for you to see how you can use app events. Each of the example apps provides a screen by screen breakdown of the different events and parameters that can be collected. At the end of each section there is a table listing the recommended events and parameters for each app. And, if required, you can create your own events and parameters.

It is important to note that these guides should be used as a starting point for your app and should be customized by you.

7. Test Your Events

The App Ads Helper allows you to test the app events in your app to ensure that your app is sending events to Facebook.

a. Open the App Ads Helper.

b. In Select an App, choose your app and choose Submit.

c. Go to the bottom and choose Test App Events.

d. Start your app and send an event. The event appears on the web page.

More Resources

For more information and helpful hints on App Events check out:

  • Best Practices Guide - View a wide variety of sample apps and how each handles App Events.
  • FAQ - Check out our Frequently Asked Questions