App Events API

Overview

Report app installs and in-app conversions through this API and send data back to Facebook Analytics. Use this on mobile devices without Facebook SDK.

The API fetches a Apple's Advertising Identifier (IDFA) or Android's Advertising ID from a mobile device and sends it to the app's server-side component. The server sends this data to Facebook and Facebook logs these app events.

Facebook does not share any app event data sent on your behalf to advertisers or other third parties, unless we have your permission or are required to do so by law.

Tracking Enabled Flag

iOS6 and Later

On iOS6 and later, you can enable ad tracking in device settings. Facebook complies with Apple policies and requires 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.

Application Opt-out

Any app can include a setting for people to turn off ad tracking in the app. You should include this option and report the user's setting to Facebook along with the install or conversion event. You must persist this setting across app launches. Facebook uses the install or conversion event for ads reporting but restricts its use in ad optimization.

App Event API, App Install

Get Apple's Advertising Identifier (IDFA) or Android’s advertising ID from the device, then send the ID to your server. From your server call the API endpoint with required parameters below.

You should report only one install per user. Deduplicate IDs on the ID level and also on the user level, if you can determine this.

POST https://graph.facebook.com/<API_VERSION>/<APP_ID>/activities

Parameters

name description example

event

Conversion event that occurred

MOBILE_APP_INSTALL

advertiser_id

Apple's Advertising Identifier (IDFA) or Google's Android’s advertising ID. See how Facebook fetches this on iOS or on Android.

1111-1111-1111-1111

attribution

Mobile_cookie from a device. Applies to Android and pre-iOS6 devices. For other devices, we suggest you use advertiser_id. Use attrbution to associate with app event. See how.

DDDECD0A-C076-4050-8CE8-C20EC3FC2BD3

advertiser_tracking_enabled

User can enable or disable ad tracking on iOS 6+, and this is stored in the phone. You should fetch it and send it to Facebook so we do not use the data for optimization. We will use the data to report a conversion. See here to see how Facebook gets this setting. For non-iOS 6+ devices, this query parameter can be defaulted to 1.

0 for disabled or 1 for enabled

application_tracking_enabled

A user can enable or disable ad tracking on an app level. SDKs should enable app developers to add a opt-out setting into an app. Use this field to specify the user's choice.

0 for disabled or 1 for enabled

bundle_id

Optional. A unique string that identifies your application to the system. See FB-iOS-SDK to see how Facebook fetches this.

com.companyDomain.appName

bundle_version

Optional. Bundle version is the internal version number of your app. See FB-iOS-SDK for an example of how Facebook fetches that variable.

2.0.0.123

bundle_short_version

Optional. Bundle Short Version is the publically visible version of your app. See FB-iOS-SDK for an example of how Facebook fetches that variable.

2.0

Example

curl \
  -F "event=MOBILE_APP_INSTALL" \
  -F "advertiser_id=1111-1111-1111-1111" \
  -F "advertiser_tracking_enabled=1" \
  -F "application_tracking_enabled=1" \
  "https://graph.facebook.com/<APP_ID>/activities"

The response is true. If you receive an error, retry the request.

App Event API, Custom Conversion Event

You can register conversion events with Facebook. App admins and developers can see conversions for organic promotion and ads in app dashboard. Facebook also displays conversions attributed to ads in the advertiser's ads manager.

POST https://graph.facebook.com/<API_VERSION>/<APP_ID>/activities

Parameters

name description example

event

Conversion event

custom_app_events

advertiser_id

Apple's Advertising Identifier (IDFA) or Android’s advertising ID. See how Facebook fetches this on iOS or on Android.

1111-1111-1111-1111

attribution

Mobile_cookie from the user's device. This is only applicable for Android and below iOS6 devices. Even though we suggest advertiser_id be used. You may choose to use attrbution to associate with app event. See [how](# )

DDDECD0A-C076-4050-8CE8-C20EC3FC2BD3

advertiser_tracking_enabled

A user can enable ad tracking on iOS 6+, and that choice is stored on the phone. You should fetch that and return it to Facebook so we know not to use the data for optimization. We will, however, use the data to report on a conversion. See here for an example of how Facebook fetches that variable. For non-iOS 6+ devices, this query parameter can be defaulted to 1.

0 for disabled or 1 for enabled

application_tracking_enabled

A user can choose to enable ad tracking on an app level. Your SDK should enable app developers to put an opt-out setting in their app. Use this field to specify the user's choice.

0 for disabled or 1 for enabled

bundle_id

Optional. Unique string that identifies your application to the system. See FB-iOS-SDK for an example of how Facebook fetches that variable.

com.companyDomain.appName

bundle_version

Optional. Bundle version is the internal version number of your app. See FB-iOS-SDK for an example of how Facebook fetches that variable.

2.0.0.123

bundle_short_version

Optional. Bundle Short Version is the publically visible version of your app. See FB-iOS-SDK for an example of how Facebook fetches that variable.

2.0

custom_events

Array of events you want to report to Facebook. Please see the list of pre-defined events and applicable parameters of each of them below. You can use your own app events as well. You can specify multiple events in the array.

'[{'_eventName':'fb_mobile_purchase',

'_valueToSum':55.22, // value of individual event

'_logTime':1367017882, // specified in unixtime

'fb_currency':'GBP', // specified in ISO-4217

}]'

App Event Schema

Each app event is a JSON dictionary that:

  • Must have an _eventName entry,
  • Should have _logTime and _appVersion entries,
  • May have a _valueToSum entry described in the table below, and
  • Can have additional parameters recommended in the third column below.

Here are some pre-defined app events you may use:

"_eventName" to use "_valueToSum" Typical Parameters Notes

fb_mobile_level_achieved

fb_level

fb_mobile_activate_app

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

fb_mobile_add_payment_info

fb_success

fb_mobile_add_to_cart

Price of item added

fb_content_type, fb_content_id, fb_content, and fb_currency

fb_mobile_add_to_wishlist

Price of item added

fb_content_type, fb_content_id, fb_content, and fb_currency

fb_mobile_complete_registration

fb_registration_method

fb_mobile_tutorial_completion

fb_success, fb_content_id, and fb_content

fb_mobile_initiated_checkout

Total price of items in cart

fb_content_type, fb_content_id, fb_content, fb_num_items, fb_payment_info_available and fb_currency

fb_mobile_purchase

purchase price

fb_num_items, fb_content_type, fb_content_id, fb_content, and fb_currency

fb_mobile_rate

Rating given

fb_content_type , fb_content_id, fb_content, and fb_max_rating_value

fb_mobile_search

fb_content_type, fb_search_string and fb_success

fb_mobile_spent_credits

Total value of credits spent

fb_content_type, fb_content_id, and fb_content

fb_mobile_achievement_unlocked

fb_description

fb_mobile_content_view

Price of item viewed (if applicable)

fb_content_type, fb_content_id, fb_content, and fb_currency

The table shows useful parameters to include with the events above, or with your own custom events. You can also use your own parameters.

Event Parameter Names Possible Values 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 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}]"

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

'1' or '0'

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

'1' or '0'

1 for yes, 0 for no

API Call Example

curl \
  -F "event=CUSTOM_APP_EVENTS" \
  -F "advertiser_id=1111-1111-1111-1111" \
  -F "advertiser_tracking_enabled=1" \
  -F "application_tracking_enabled=1" \
  -F "custom_events=[{\"_eventName\":\"fb_mobile_purchase\",
                      \"fb_content\":\"[{\"id\": \"1234\", \"quantity\": 2, \"item_price\": 5.99}, {\"id\": \"5678\", \"quantity\": 1, \"item_price\": 9.99}]\",
                      \"fb_content_type\":\"product\",
                      \"_valueToSum\":21.97,
                      \"fb_currency\":\"GBP\",
                    }]" \
  "https://graph.facebook.com/<API_VERSION>/<APP_ID>/activities"

The response is be true. If you receive an error, retry the request.

The maximum number of different event names is 1,000. No new event types will be logged once this cap is hit. If you exceed this limit you may see an 100 Invalid parameter error. However you can deactivate old events. Read about event limits in the FAQ.

Testing

App Event Testing, App Install

Do this testing to make sure Facebook servers recieve your install ping.

To test on this, install the app to track where you log the event. Then verify that your own server receives the parameters from the client. Finally, check the app details page to verify Facebook receives your API call. The field to check is "Last Mobile Install Reported". This does not appear if no API call is received. Remember the page may take ~20 minutes to refresh.

We encourage you to associate app events with advertiser_id. However, for Android devices and iOS devices earlier than iOS6, you can also use mobile cookies, see attribution.

iOS Client

Place the Facebook mobile cookie in a UIPasteboard named fb_app_attribution. Below is a code snippet to fetch this ID from the named UIPasteboard and to fetch Apple's Advertising Identifier (IDFA), both of which can be sent 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
}

The mobile cookie is created by FB iOS apps using CFUUIDCreateString and is 128-bit UUID string representation. It is not derived from any user or device attributes. This mobile cookie is not persistent and is designed to be refreshed frequently, so you cannot use this for re-targeting ads.

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

Android Client

Place the Facebook attribution ID in Android in a ContentProvider that can be accessed by other apps on the phone. The code snippet below is an example of how to retrieve this ID.

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 Android’s advertising ID, see instruction Android, Play Service ID.

The cookie is a 22-character random alphanumeric string. It is not derived from any user or device attributes. Also this mobile cookie is not persistent and is designed to be refreshed frequently, so you cannot use this for re-targeting or so.