We no longer recommend App Events API for new integrations. The Conversions API now supports web, app, and offline events, so we recommend that advertisers use the Conversions API instead of App Events API. Existing App Events API users can continue to use it, but we will discontinue development of this API. Future innovation will be developed on the Conversions API. Learn more about Conversions API for App Events.
App Events allow 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 measure ad performance and build audiences for ad targeting.
For information on tracking App Events for Business Messaging, please see the App Events API for Business Messaging in our Messenger Platform documentation.
There are three types of App Events:
An app event has three parts:
name
- A required string that describes the event. The name appears in the Event log when the app event is sent to Analytics.valueToSum
- An optional value that Analytics adds to other Value To Sum values from app events with the same name.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.
You will need:
Send a POST
request from your server to the /{app-id}/activities
endpoint with the application_tracking_enabled
and advertiser_tracking_enabled
parameters:
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={advertiser-tracking-id} &{app-access-token}"
On success, your app receives the following response:
{ "success": true }
Visit our Application Activities Reference guide for a list of available parameters.
The advertiser_tracking_enabled
field specifies whether a person has enabled advertising tracking on their device. Set to 0 for disabled or 1 for enabled. You should fetch this data and return it to Facebook to determine if ad tracking can be used for optimization or conversions.
Meta will use the event data (from partners about user activities off Meta) pursuant to its Data Policy, including for ad reporting, fraud detection and to build and improve our products (including our ads delivery products), but will restrict use of data about that individual to personalize that user’s ads. For devices running earlier versions than iOS 6, this parameter should default to 1.
Visit Apple, AdSuppport Reference to get tracking status of a user.
The following code snippet illustrates how to fetch the value of the tracking enabled flag.
You can get the current setting of the tracking enabled flag from the Settings.shared.isAdvertiserTrackingEnabled
property.
print("isAdvertiserTrackingEnabled: \(Settings.shared.isAdvertiserTrackingEnabled)")
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.
Send a POST
request to the /{app-id}/activities
endpoint with the event
set to CUSTOM_APP_EVENTS
and set advertiser_tracking_enabled
for each individual event. The advertiser_id
or attribution
parameter is required.
curl -i -X POST "https://graph.facebook.com/{app-id}/activities ?event=CUSTOM_APP_EVENTS" &advertiser_id={advertiser-tracking-id} &advertiser_tracking_enabled=1 &application_tracking_enabled=1 &custom_events=[ {"_eventName":"fb_mobile_purchase", "event_id":"123456", "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 }
The attribution
endpoint returns installs and conversions based on clicks that happened on an ad within 28 days. Ads Manager uses a 1-day view through a 28-day click-through attribution model and 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 - Setting consider_views=TRUE
returns attribution data for installs that occurred within 1 day of an ad impression, provided the Accounts Center account 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 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.
Advanced matching allows you to send customer data to Facebook where we use this data to more accurately determine which Accounts Center accounts 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 a parameter that will help to track your customer such as customer email or phone number. All customer data must be hashed or Facebook will ignore it. Be sure to set advertiser_tracking_enabled
for each individual event.
curl -i -X POST "https://graph.facebook.com/{app-id}/activities ?event=CUSTOM_APP_EVENTS &advertiser_id={advertiser-tracking-id} &advertiser_tracking_enabled=1 &application_tracking_enabled=1 &custom_events=[ {"_eventName":"fb_mobile_purchase", "event_id":"123456", "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 }
All user data must be SHA256 hashed before you send it to Facebook. Facebook will ignore data that is not hashed.
For app events, we apply the same deduplication functionality that exists for web events. The logic leverages the field event_id
and event_name
based deduplication. The event_id
parameter is an identifier that can uniquely distinguish between similar events. Inaccurate event IDs may cause your conversion to be wrongly deduplicated, further impacting conversion reporting and campaign performance.
Send device information, such as screen width and height, in your app event call using /{app-id}/activities?extinfo
. Values are separated by commas and must be in the order indexed in the /application/activites
reference guide. When using extinfo
all values are required.
version
must be a2
for Android version
must be i2
for iOSWe 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.
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.
The mobile cookie is created by Facebook iOS apps using CFUUIDCreateString
and is 128-bit UUID string representation.
Get both the cookie ID and the IDFA and send them to Facebook as an identifier:
ASIdentifierManager *manager = [ASIdentifierManager sharedManager]; NSString *advertiserID = [[manager advertisingIdentifier] UUIDString]; if (advertiserID) { // do stuff }
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.
curl ... -H "X-Forwarded-For: fd45:f238:3b40:23b1:ffff:ffff:ffff:abcd" \ https://graph.facebook.com/<APP_ID>/activities/
curl ... -H "X-Forwarded-For: 192.168.0.99" \ https://graph.facebook.com/<APP_ID>/activities
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:
If Facebook is reporting more installs than MMP:
Visit the /application/activites
reference guide for more information on app extended information.
for examples of properly normalized and hashed data for the parameters below.
User Data | Parameter | Format | Example |
---|---|---|---|
|
| ||
First Name |
| Lowercase letters |
|
Last Name |
| Lowercase letters |
|
Phone |
| Digits only including country code and area code |
|
External ID |
| Any unique ID from the advertiser, such as loyalty membership ID, user ID, and external cookie ID. |
|
Gender |
| Single lowercase letter, |
|
Birthdate |
| Digits only with birth year, month, then day |
|
City |
| Lowercase with any spaces removed |
|
State or Province |
| Lowercase two-letter state or province code |
|
Zip or Postal Code |
| Digits only |
|
Country |
| Lowercase two-letter country code |
|
Event Name | Event Parameters | _valueToSum |
---|---|---|
|
| |
|
| With App Ads, revenue of ads from a third-party platform appears on-screen within your app. |
| ||
| ||
| ||
|
| |
| ||
|
| |
|
| Price of item added |
|
| Price of item added |
|
| |
|
| Price of item viewed (if applicable) |
|
| Total price of items in cart |
|
| |
|
| Purchase price |
|
| Rating given |
|
| |
|
| Total value of credits spent |
|
| |
| ||
| ||
|
| Price of subscription |
| ||
|
| 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.
Event Parameter Name | Value | Description |
---|---|---|
| int | Recommend parameter to specify the time of event, specified in unixtime |
| float | Numeric value of individual event to be summed in reporting, see above for recommended events to attach to |
| string | International Article Number (EAN) when applicable, or other product or content identifier(s). For multiple product ids: e.g. "[\"1234\",\"5678\"]" |
| 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: |
| string | The |
| string | ISO 4217 code, e.g., "EUR", "USD", "JPY". Required when passing |
| string | A string description |
| string | Level of a game |
| int | Upper bounds of a rating scale, for example 5 on a 5 star scale |
| int | Number of items |
| boolean |
|
| string | Facebook, Email, Twitter, etc. |
| string | The text string that was searched for |
| boolean |
|