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. Integrate the Facebook SDK in Your App

When you use the Facebook SDK, 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. 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: uses-permission element after the application element:
    <uses-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

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

Automatically Logged Events

After you integrate the Facebook SDK into your app, these 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.

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.

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, type your event name.
  3. Choose Get Code.
  4. In the window, select a language to see 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");

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