App Events API

Overview

App Events allows you to track actions that occur in your mobile app or web page such as app installs and purchase events. By tracking these events you can view analytics, measure ad performance, and build audiences for ad targeting.

How It Works

There are three types of App Events:

  • Automatically Logged Events - The Facebook SDK automatically logs app installs, app sessions, and in-app purchases.
  • Standard Events - Popular events that Facebook has created for you.
  • Custom Events - Events you create that are specific to your app.

An app event has three parts:

  1. name - A required string that describes the event. The name appears in the Event log when the app event is sent to Analytics.
  2. valueToSum - An optional value that Analytics adds to other Value To Sum values from app events with the same name.
  3. parameters - Optional values included with your app event.

The maximum number of different event names is 1,000. Note: No new event types will be logged once this cap is hit and if you exceed this limit you may see an 100 Invalid parameter error when logging. However it is possible to deactivate obsolete events. Read more about event limits in the FAQ.

App Installs

Before You Start

You will need:

  • Your advertiser ID, the advertising ID from an Android device or the Advertising Identifier (IDFA) from an Apple device
  • An app access token for Facebook to authenticate.

Caveats

  • You should report only one install per user. Deduplicate IDs on the ID and user levels if possible.
  • Do not store your app access token on the client

Send a POST request from your server to the /{app-id}/activities endpoint with the application_tracking_enabled and advertiser_tracking_enabled parameters:

Formatted for readability.
curl -i -X POST "https://graph.facebook.com/{app-id}/activities
   ?event=MOBILE_APP_INSTALL
   &application_tracking_enabled=0      
   &advertiser_tracking_enabled=0       
   &advertiser_id=1111-1111-1111-1111
   &{app-access-token}"

On success, your app receives the following response:

{
  "success": true
}

Visit our Application Reference Guide for a list of available parameters.

Conversion Events

Tracking Events

Send a POST request to the /{app-id}/activities endpoint with the event set to CUSTOM_APP_EVENTS. The advertiser_id or attribution parameter is required.

Formatted for readability.
curl -i -X POST "https://graph.facebook.com/{app-id}/activities
   ?event=CUSTOM_APP_EVENTS" 
   &advertiser_id=1111-1111-1111-1111
   &advertiser_tracking_enabled=1 
   &application_tracking_enabled=1
   &custom_events=[
      {"_eventName":"fb_mobile_purchase",
       "fb_content":"[
            {"id": "1234", "quantity": 2,}, 
            {"id": "5678", "quantity": 1,}
        ]",
       "fb_content_type":"product",
       "_valueToSum":21.97,
       "fb_currency":"GBP",
      }
    ]
   &{app-access-token}" 

On success, your app receives the following response:

{
  "success": true
}

Standard Event Names

Event Name Event Parameters _valueToSum

AdClick

fb_ad_type

AdImpression

fb_ad_type

Contact

CustomizeProduct

Donate

fb_mobile_achievement_unlocked

fb_description

fb_mobile_activate_app *

fb_mobile_add_payment_info

fb_success

fb_mobile_add_to_cart

fb_content_type, fb_content_id and fb_currency

Price of item added

fb_mobile_add_to_wishlist

fb_content_type, fb_content_id and fb_currency

Price of item added

fb_mobile_complete_registration

fb_registration_method

fb_mobile_content_view

fb_content_type, fb_content_id and fb_currency

Price of item viewed (if applicable)

fb_mobile_initiated_checkout

fb_content_type, fb_content_id, fb_num_items, fb_payment_info_available and fb_currency

Total price of items in cart

fb_mobile_level_achieved

fb_level

fb_mobile_purchase

fb_num_items, fb_content_type, fb_content_id and fb_currency

Purchase price

fb_mobile_rate

fb_content_type, fb_content_id and fb_max_rating_value

Rating given

fb_mobile_search

fb_content_type, fb_search_string and fb_success

fb_mobile_spent_credits

fb_content_type and fb_content_id

Total value of credits spent

fb_mobile_tutorial_completion

fb_success and fb_content_id

FindLocation

Schedule

StartTrial

fb_order_id and fb_currency

Price of subscription

SubmitApplication

Subscribe

fb_order_id and fb_currency

Price of subscription

*Use fb_mobile_activate_app event in addition to install reporting to exclude users from seeing ads for this app. Do not use this event if you have automatic event logging enabled.

Standard Event Parameters

Event Parameter Name Value Description

_logTime

int

Recommend parameter to specify the time of event, specified in unixtime

_valueToSum

float

Numeric value of individual event to be summed in reporting, see above for recommended events to attach to

fb_content_id

string

International Article Number (EAN) when applicable, or other product or content identifier(s). For multiple product ids: e.g. "[\"1234\",\"5678\"]"

fb_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 quantities and prices of the products. Required:id, quantity. e.g. "[{\"id\": \"1234\", \"quantity\": 2,}, {\"id\": \"5678\", \"quantity\": 1,}]".

fb_content_type

string

For example music, video, or product description

fb_currency

string

ISO 4217 code, e.g., "EUR", "USD", "JPY". Required when passing _valueToSum as a price or a purchase amount.

fb_description

string

A string description

fb_level

string

Level of a game

fb_max_rating_value

int

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

fb_num_items

int

Number of items

fb_payment_info_available

boolean

1 for yes, 0 for no

fb_registration_method

string

Facebook, Email, Twitter, etc.

fb_search_string

string

The text string that was searched for

fb_success

boolean

1 for yes,0 for no

Advanced Matching

Advanced matching allows you to send customer data to Facebook where we use this data to more accurately determine which people took action in response to your ad. With this data, Facebook can match conversion events to your customers to optimize your ads and build larger re-marketing audiences.

Send a POST request to the /{app-id}/activities endpoint with the ud parameter set to customer data such as customer email or phone number. All customer data must be hashed or Facebook will ignore it.

Formatted for readability.
curl -i -X POST "https://graph.facebook.com/{app-id}/activities
   ?event=CUSTOM_APP_EVENTS
   &advertiser_id=1111-1111-1111-1111
   &advertiser_tracking_enabled=1 
   &application_tracking_enabled=1
   &custom_events=[
      {"_eventName":"fb_mobile_purchase",
       "fb_content":"[
            {"id": "1234", "quantity": 2,}, 
            {"id": "5678", "quantity": 1,}
        ]",
       "fb_content_type":"product",
       "_valueToSum":21.97,
       "fb_currency":"GBP",
      }
    ]
   &ud[em]={sha256-hashed-email}
   &{app-access-token}"

On success, your app receives the following response:

{
  "success": true
}

User Data

The following table shows parameters and formats you can use to send user data. All user data must be SHA256 hashed before you send it to Facebook. We will ignore data that is not hashed.

Customer Information Data Parameters

DataParameterFormatExample

Email

em

jsmith@example.com

First Name

fn

Lowercase letters

john

Last Name

ln

Lowercase letters

smith

Phone

ph

Digits only including country code and area code

16505554444

External ID

external_id

Any unique ID from the advertiser, such as loyalty membership ID, user ID, and external cookie ID.

a@example.com

Gender

ge

Single lowercase letter, f or m, if unknown, leave blank

f

Birthdate

db

Digits only with birth year, month, then day

19910526 for May 26, 1991.

City

ct

Lowercase with any spaces removed

menlopark

State or Province

st

Lowercase two-letter state or province code

ca

Zip or Postal Code

zp

Digits only

94025

Country

cn

Lowercase two-letter country code

us

Extended Device Information

The /{app-id}/activities?extinfo is an object that allows you to send device information, such as screen width and height, in your app event call. Values are separated by commas and must be in the ordered indexed in the /application/activites reference guide. When using extinfo all values are required.

Android

The extended information version value, indexed at 0, for Android must be a2. Visit the Android Developer Documentation for more information on display metrics and external storage.

iOS

The extended information version value, indexed at 0, for iOS must be i2. Visit the Apple Developer Documentation for more information on display metrics and screen size, and external storage.

Enable Ad Tracking

On iOS 6 and later, you can enable ad tracking in device settings. Facebook complies with Apple policies and requires that you report install and conversion events and the tracking-enabled flag. Facebook uses these app events for organic ad analytics and reporting, but restricts its use in ad optimization. See Apple, AdSuppport Reference to get this setting.

The following code snippet illustrates how to fetch the value of the tracking enabled flag.

(FBAdvertisingTrackingStatus)advertisingTrackingStatus {
    FBAdvertisingTrackingStatus status = AdvertisingTrackingUnspecified;
    Class ASIdentifierManagerClass = [FBDynamicFrameworkLoader loadClass:@"ASIdentifierManager" withFramework:@"AdSupport"];
    if ([ASIdentifierManagerClass class]) {
        ASIdentifierManager *manager = [ASIdentifierManagerClass sharedManager];
        if (manager) {
            status = [manager isAdvertisingTrackingEnabled] ? AdvertisingTrackingAllowed : AdvertisingTrackingDisallowed;
        }
    }
    return status;
}

Disable Ad Tracking

Any application can choose to include a setting for users to turn off ad tracking within that app. Facebook asks partners to include this option in their SDK and report back the user's choice to Facebook along with the install or conversion event. Facebook uses the install or conversion event for ad reporting, but restricts it from being used in ad optimization. The user's setting must persist across app launches.

Get Mobile Cookies

We encourage you to associate app events with an advertiser_id. However, for Android devices and iOS devices earlier than iOS 6, you can also use the attribution parameter set to the mobile cookie of the device.

Note: Mobile cookies are not derived from any user or device attributes. These cookies are not persistent and are designed to be refreshed frequently. Do not use mobile cookies for re-targeting ads.

Android

The cookie is a random 22-character alphanumeric string.

Get the Facebook attribution ID using ContentProvider:

public static final Uri ATTRIBUTION_ID_CONTENT_URI = Uri.parse("content://com.facebook.katana.provider.AttributionIdProvider");

public static final String ATTRIBUTION_ID_COLUMN_NAME = "aid";

public static String getAttributionId(ContentResolver contentResolver) {
        String [] projection = {ATTRIBUTION_ID_COLUMN_NAME};
        Cursor c = contentResolver.query(ATTRIBUTION_ID_CONTENT_URI, projection, null, null, null);
        if (c == null || !c.moveToFirst()) {
            return null;
        }
        String attributionId = c.getString(c.getColumnIndex(ATTRIBUTION_ID_COLUMN_NAME));
        c.close();
        return attributionId;
    }

You should also fetch the advertising ID of your Android app.

iOS

The mobile cookie is created by Facebook iOS apps using CFUUIDCreateString and is 128-bit UUID string representation.

As of iOS 7, the UIPasteboard value will always be nil, but the IDFA is always available.

Place the Facebook mobile cookie in a UIPasteboard named fb_app_attribution.

Get both the cookie ID and the IDFA and send them to Facebook as an identifier:

UIPasteboard *pb = [UIPasteboard
     pasteboardWithName:@"fb_app_attribution"
     create:NO];
ASIdentifierManager *manager = [ASIdentifierManager sharedManager];
NSString *advertiserID = [[manager advertisingIdentifier] UUIDString];

if (pb || advertiserID) {
  // do stuff
}

X-Forwarded-For HTTP Header

If POST requests are done from a central place such as a server or proxy, basically, a server-to-server call, then X-Forwarded-For HTTP header is required to ensure accurate location and device information. Send the device's IP address, IPv4 or IPv6 format, via the X-Forwarded-For HTTP header parameter in each of the app event requests you send. By doing so, it allows us to pair the advertiser_id to the correct IP address, which we can then use in our platform.

IPv6 Example

curl ...
  -H "X-Forwarded-For: fd45:f238:3b40:23b1:ffff:ffff:ffff:abcd" \
  https://graph.facebook.com/<APP_ID>/activities/

IPv4 Example

curl ...
  -H "X-Forwarded-For: 192.168.0.99" \
  https://graph.facebook.com/<APP_ID>/activities

Testing

App Install

Check that Facebook servers are receiving your install ping.

Step 1: Run the app you want to track in a situation where the pingback code is called.

Step 2: Verify that your own servers received the attribution_id from the client.

Step 3: In the App Dashboard, scroll down to the Last Mobile Install Reported card. If install ping has been received, the date and time of the install and device type will be displayed. There may be a delay of about 20 minutes between app installation and display in the dashboard.

Install End-to-End Testing

Check that the entire flow, from ad serving to app install, is working properly.

Step 1: Create an ad to test on your app, using custom audiences to limit the targeting.

Step 2: On your test device, start the test build. This sends the attribution ID to your servers.

Step 3: Your server receives the attribution ID and records the app ID.

Step 4: Your server sends the attribution ID, app ID, and FB analytics app ID to the FB servers.

curl -i -X POST "https://graph.facebook.com/{app-id}/activities 
     ?access_token=<analytics_app_id>|<rest_of_token>
     &event=MOBILE_APP_INSTALL
     &attribution={attribution-id}"

On success, your server receives the following response:

  {
  "success": true
}

Attribution

When using this endpoint, Facebook returns installs and conversions based on clicks that happened on an ad within 28 days. This is different than the insights clients see in Ads Manager. Within Ads Manager, Facebook uses a 1-day view through a 28-day click-through attribution model. Additionally, on Ads Manager, insights are surfaced based on impression or click time, not install or conversion time. This is important when comparing your reporting to Facebook Ads Manager reports. In addition to the standard ad click app event claims, you should also keep the following scenarios in mind:

View-Through Attribution Claims

When you request app install data, you can add a flag to retrieve view-through attributions. Setting consider_views=TRUE returns attribution data for installs that occurred within 1 day of an ad impression, provided the person did not click on an ad within 28 days.The response returned will be is_view_through=TRUE and view_time will replace click_time. All other attributions are the same as with ad click attribution data.

Cross-Campaign Claims

Advertisers are able to track the performance of all ads that have led to an app event. Facebook sends claims for events from ad campaigns where the as long as the campaign objective is not set to mobile app install or mobile app engagement. This data is surfaced only if the advertiser has added the app to “Mobile App Events Tracking” field in their ad.

  • User Case — If your client wants to track the installs generated by a Page post ad or website ad clicks that sends users to a mobile site, they can do this in ads manager and Facebook will claim the relevant app installs.

Cross-Device Claims

Advertisers with apps on multiple platform can see data for app installs being driven from ads across these multiple platforms.

  • Use Case — A user clicks an iPhone ad for an app and then installs the same app on their iPad. We can then attribute the iPad app installation to the iPhone ad regardless of the ad targeting.

Discrepancies

In the event a client compares a mobile measurement partner's reports with Facebook reports and sees discrepancies, here are some items to check:

If Facebook is reporting fewer installs than MMP:

  • Is the FB SDK integrated properly?
  • Is the client using the wrong app ID?

If Facebook is reporting more installs than MMP:

  • Are the attribution windows the same? Facebook generally has a larger attribution window than most mobile measurement partners.
  • Is the MMP SDK integrated properly?
  • Is the client using the wrong app ID?
  • Is the discrepancy iOS7 only? Is the MMP receiving Apple's Advertising Identifier (IDFA) from the device and passing it properly to FB?