App Events for iOS

Implementation

You can easily insert these app events into your iOS apps using a short snippet of code:

[FBAppEvents logEvent:FBAppEventName{XXXX}];

where FBAppEventName{XXXX} is one of the FBAppEventName* 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. 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.

[FBAppEvents logEvent:FBAppEventNameAddedToCart
           valueToSum:54.23
           parameters:@{ FBAppEventParameterNameCurrency    : @"USD",
                         FBAppEventParameterNameContentType : @"shoes",
                         FBAppEventParameterNameContentID   : @"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.

Events

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.

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.

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:

Custom App Events

You can also choose to create your own custom events, which is done simply by specifying their name as a string:

[FBAppEvents logEvent:@"battledAnOrc"];

Purchase methods

While calls to logEvent can be made to register purchase events, there is a helper method that explicitly takes a currency indicator. A purchase of USD $4.32, for example, can be be invoked as:

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

Logging app activations

Developers can observe how frequently users activate their app, and how much time they spend using it, by logging an app activation event. Like purchase, there is a helper for logging app activation. For iOS, this typically should be invoked in the app delegate's applicationDidBecomeActive method, as follows:

- (void)applicationDidBecomeActive:(UIApplication *)application {

    // Call the 'activateApp' method to log an app event for use in analytics and 
    // advertising reporting.
    [FBAppEvents activateApp];

    ...
}

Note that use of the activateApp method is the preferred way to log app activations vs. simply logging the FBAppEventNameActivatedApp event, as it performs a few other tasks that are necessary for proper accounting for Mobile App Install Ads.

Automatic In-App Purchase Logging
To save you time and help ensure consistent logging, we have made it possible to automatically log app events related to in-app purchases if you call the activateApp method and enable the “Automatic In-App Purchase” switch in the iOS settings section of the App Dashboard. Note this requires version 3.22 or higher of the iOS SDK. You can learn more about this feature in this FAQ.

API reference documentation

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

Verification

If you're an Admin or a Developer of an app, and want to validate that you've correctly implemented app events, go to App Insights, choose your app and then select 'App Events' from the left hand menu (this will not appear until your app starts logging events). The bottom half of this page will have a "Most recently logged events" section that looks like the following:

This table lists the last 20 events logged by your app, including the event name, app version, device type, value and parameters logged with the event. Events show up here as soon as they've been transmitted to the server from your mobile app.

You can pinpoint events coming from a version under development (vs. one that's in production) by choosing the App Version dropdown as shown in the image above. This will filter the events shown to that version. (The App Version for your app will be logged automatically from the version stored in the iOS app's bundle.) You can similarly filter by Event Name.

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

We offer a range of different attribution windows to choose from. Here's a breakdown of the various sources of Facebook app events reporting available to developers and the attribution methodology used across each:

• In the default Campaign Report, Ads Manager reports on app events based on a 1 day view and 28 day click attribution window. This represents the count of events that took place within 24 hours of someone viewing the ad or 28 days after clicking on it.
• In the full Actions by Impression Time Report we offer advertisers a range of attribution windows to select from when tracking app events, based on what is most meaningful for their business. Advertisers can see a count of events that happen within 1 day, 7 days, and 28 days after a person clicks on an ad, and 1 day, 7 days, and 28 days after viewing an ad when they export the Actions by Impression time report to Excel.

In order to view actions attributed to ads, go to Ads Manager and choose your specific campaign and ad group. You should see a chart similar to this:

App Insights

App events reporting is also available in App Insights, which provides a measure of total app events for an app broken down by demographic. In order to view demographic insights about the users of your mobile app, 1) go to App Insights, 2) choose your app and then choose App Events from the left hand menu. You should see a graph similar to this:

This graph shows the app events that have been received by Facebook for your app. You can then drill down and get details of the different events by clicking on the event name in the table at the bottom of this graph. For instance, clicking on the "Purchase on Device" link will lead to a chart with details on Mobile Purchase events, including this table of demographics at the bottom:

By viewing this chart, and the other content on this page, you can identify the age, gender, country and locale breakdown of your app users, as well as device usage and breakdown by the parameters that were logged with your event.

You can also view the distribution of users taking action to understand what percentiles are most active or are contributing the most value. More than that, you can even choose to target a range of people within those percentiles for advertising to effectively reach them.