App Events for iOS

App Events help you understand the makeup of people who engage with your app and measure and reach specific sets of your users with Facebook mobile app ads. This is done by logging events from your app via the Facebook SDK for iOS. The event can be one of 14 predefined events such as added to cart in a commerce app or achieved level in a game, or any custom events you can define.

The examples in this document are written in Objective-C. If you are using Swift, refer to App Events with the Facebook SDK for Swift.


For each application session, the Facebook SDK for iOS is automatically initialized logs the session as an app activation event. The app activation event shows you how many users install your app, how frequently users activate your app, how much time they spend using it, and to view other demographic information through Facebook Analytics. For more information on the events that are logged automatically, see Automatic App Event Logging.

If you want to disable automatic event logging, see Manual Event Logging.

Automatic In-App Purchase Logging

Facebook has made it possible to automatically log app events related to in-app purchases. To enable automatic purchase logging, call the activateApp method during app activation and enable Automatic Log App Events for in-App Purchases on iOS (Recommended) in the iOS settings section of the app's dashboard.

You can learn more about this feature in this FAQ.

The maximum number of different event names is 1000. 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.

Logging Purchases

If the automatic method does not work for you, the Facebook SDK provides a helper method to log purchases with a single line of code. For example, a purchase of USD $4.32, can be be logged with:

[FBSDKAppEvents logPurchase:4.32 currency:@"USD"];

The currency specification is expected to be an ISO 4217 currency code. This is used to determine a uniform value for use in ads optimization.

Important: There are many reasons that a user may initiate a purchase that can't be completed. For accurate logging of purchase events, only log the purchase after a purchase has been completed.

Manual Event Logging

The process described here for manual event logging with the SDK is provided so that you have the option of controlling when app events are logged. We recommend that you do not disable automatic logging because it may impact how data is collected for your app.

To disable automatic event logging:

Open the application's .plist as code in Xcode and add the following XML to the property dictionary:


Logging App Activations

Logging app activations as an App Event enables almost all other functionality and should be the first thing that you add to your app. The SDK provides a helper method to log app activation.

Insert this piece of code in your app delegate's applicationDidBecomeActive method:

- (void)applicationDidBecomeActive:(UIApplication *)application {    
    // Call the 'activateApp' method to log an app event for use
    // in analytics and advertising reporting.
    [FBSDKAppEvents activateApp];
    // ...

The activateApp method is the preferred way to log app activations, even though there's an event that you can send manually via the SDK. The helper method performs a few other tasks that are necessary for proper accounting for Mobile App Install Ads.

Logging Other Events

For all other types of events, use the logEvent method:

[FBSDKAppEvents logEvent:FBSDKAppEventName{XXXX}];

where FBSDKAppEventName{XXXX} is one of the FBSDKAppEventName* constants shown in the Events table below.

You can also specify a set of parameters and a valueToSum property which is an arbitrary number that can represent any value (e.g., a price or a quantity). When reported, all of the valueToSum properties will be summed together in Facebook Analytics. For example, if 10 people each purchased one item that cost $10 (and passed in valueToSum) then they would be summed to report a number of $100.

[FBSDKAppEvents logEvent:FBSDKAppEventNameAddedToCart
              parameters:@{ FBSDKAppEventParameterNameCurrency    : @"USD",
                            FBSDKAppEventParameterNameContentType : @"product",
                            FBSDKAppEventParameterNameContent     : @"[{\"id\": \"1234\", \"quantity\": 2, \"item_price\": 5.99}, {\"id\": \"5678\", \"quantity\": 1, \"item_price\": 9.99}]" } ];
[FBSDKAppEvents logEvent:FBSDKAppEventNameAddedToCart
              parameters:@{ FBSDKAppEventParameterNameCurrency    : @"USD",
                            FBSDKAppEventParameterNameContentType : @"product",
                            FBSDKAppEventParameterNameContentID   : @"HDFU-8452" } ];

Note that both the valueToSum and parameters arguments are optional.

The full list of pre-defined events and pre-defined parameters are listed below.


Each of these events can be logged with a valueToSum and a set of parameters (up to 25 parameters). The table below shows the recommended events and what are typically useful parameters for each event (the common parameter names are defined in the next table). You should include the events that make sense based on the user actions in your app.

You can use the following app event builder to create code for both custom events and predefined events.

The following table lists the event names.

Event Name: FBSDKAppEventName valueToSum Parameters

Achieved Level:



App Launched:


Added Payment Info:



Added To Cart:


Price of item added

ContentType, ContentID or Content, and Currency

Added To Wishlist:


Price of item added

ContentType, ContentID or Content, and Currency

Completed Registration:



Completed Tutorial:


Success, and ContentID or Content

Initiated Checkout:


Total price of

ContentType, ContentID or Content, NumItems, PaymentInfoAvailable, and Currency



Use the logPurchase method instead.

Purchase price

NumItems, ContentType, ContentID or Content, and Currency



Rating given

ContentType, ContentID or Content, and MaxRatingValue



ContentType, SearchString, and Success

Spent Credits:


Total value of credits spent

ContentType, and ContentID or Content

Unlocked Achievement:



Viewed Content:


Price of item viewed (if applicable)

ContentType, ContentID or Content, and Currency


The table below are typically useful parameters for inclusion with the events shown above, or with your own custom events. You can also 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. Log the set of parameters you're interested in seeing broken down in Analytics. The recommended description for these are guidance only - you can use these parameters for whatever makes sense for your app.

The parameters are passed via an NSDictionary where the key holds the parameter name as an NSString (iOS SDK constants for the pre-defined ones are listed below), and the value must be either an NSString or an NSNumber:

Parameter: FBSDKAppEventParameterName Possible Values Description

Content ID:



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




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. id, quantity, and item_price are required fields. e.g. "[{\"id\": \"1234\", \"quantity\": 2, \"item_price\": 5.99}, {\"id\": \"5678\", \"quantity\": 1, \"item_price\": 9.99}]". Note that item_price is the price of a single item, not cumulative price.

Content Type:



product or product_group




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




A string description




Level of a player

Max. Rating Value:



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

Number of Items:



Number of items

Payment Info Available:


1 or 0

1 for yes, 0 for no

Registration Method:



Facebook, Email, Twitter, etc.

Search String:



The text string that was searched for



1 or 0

1 for yes, 0 for no

Custom App Events

You can also choose to create your own custom events. To log a custom event, just pass the name of the event as an NSString:

[FBSDKAppEvents logEvent:@"battledAnOrc"];

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.

API Reference

More details about the FBSDKAppEvents class can be found in the reference documentation.

Verifying Event Logging in Facebook Analytics

If you're an Admin or a Developer of an app, you can validate that you've correctly implemented app events in Facebook Analytics. Please see our documentation on debugging events in Facebook Analytics to learn how to verify that events are being logged.

Enabling Debug Logs

Developers can enable debug logs so they can easily verify App Event usages from client sides. The debug logs contain detailed request and response in JSON. You can enable debug logs by adding this code:

[FBSDKSettings enableLoggingBehavior:FBSDKLoggingBehaviorAppEvents];

This is only for debugging purpose. Please make sure to disable debug logs before deploying app in production.

Facebook Analytics

Enabling App Events means that you can automatically start using Facebook Analytics. This analytics channel provides demographic info about the people using your app, offers tools for better understanding the flows people follow in your app, and lets you compare cohorts of different kids of people performing the same actions.

See our documentation for Facebook Analytics for more information.

Facebook Ads

Mobile App Ad Performance

You can use app events to better understand the engagement and ROI coming from your mobile ads on Facebook. If you've set up app events, they will be reported as different types of actions in Ads Manager so you can see which ads and campaigns resulted in what actions within your app. For example, you may see that a particular ad resulted in 10 total actions. Those actions could be 8 checkouts and 2 registrations, which will be specified in Ads Manager.

Mobile App Ad Targeting

Measuring app events also opens up an easier way to reach your existing app users for mobile app ads. After integrating app events, you will be able to reach your existing users, specific subsets of users based on what actions they have taken within your app, or even percentages of your most active users. For instance you can run ads to bring recent purchasers back into your app to complete more purchases or to your top 25% of purchasers. You can choose an audience to reach based on the app events you are measuring in your app.

To learn more about our mobile app ads, go to our tutorial on mobile app ads for installs or mobile app ads for engagement.

Ads Attribution

Once you've implemented app events into your iOS app, the App Events you've added will automatically be tracked when you run Facebook mobile app ads for installs or mobile app ads for engagement and conversion. Initially, we will only track the 14 predefined events described above.

If using Ads Manager to set up your ad, please ensure you use the default tracking settings, or if you manually configure tracking settings that the following tracking_spec is present, with {app_id} replaced with your app's Facebook App Id.

{"action.type" : ["app_custom_event"], 
 "application" : [{app_id}]} 

What's reported:

If you have set up app events, they will be reported as different types of actions in Ads Manager. For example, you may see that a particular ad resulted in 10 total actions. Those actions could be 8 checkouts and 2 registrations, which will be specified in Ads Manager. You can learn more about measuring performance of mobile app ads in Ads Manager in Measuring using the Ads Manager and Measure Installs and In-App Conversions

Data Control

The Facebook SDK offers a tool to give your users control over how app events data is used by the Facebook ads system. Our Platform Policy requires that you provide users with an option to opt out from sharing this info with Facebook. We recommend that you use our SDK tools to offer the opt-out. Facebook also respects device-level controls where available, including the Advertising Identifier control on iOS6 and beyond.

setLimitEventAndDataUsage behavior

If the user has set the limitEventAndDataUsage flag to YES, your app will continue to send this data to Facebook, but Facebook will not use the data to serve targeted ads. Facebook may continue to use the information for other purposes, including frequency capping, conversion events, estimating the number of unique users, security and fraud detection, and debugging.

[FBSDKSettings setLimitEventAndDataUsage:YES];

The limitEventAndDataUsage setting will persist across app sessions. To use this property, you can match your opt-out's UI to the value of the limitEventAndDataUsage flag.

Data Sharing

App Event data you share with Facebook will not be shared with advertisers or other third parties, unless we have your permission or are required to do so by law.