Getting Started with App Events for iOS

App Events is a feature of the Facebook SDK for iOS that allows you to track actions within your app or website. Tracking these actions, or events, allows you to target, measure, and optimize the delivery of your ads to people most likely to take action. This guide shows you how to add App Events to your new or existing app by integrating the Facebook SDK then logging these events.

There are three types of App Events:

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

Requirements

The following are required before you can add app events to your app.

• A Facebook Developer Account
• A Facebook Ad Account ID

  Get your Facebook App ID or create a new one.

  If you already have implemented the Facebook Android SDK, begin at Step 6. Add App Events.

1. Setup Your App Details for Advertising

1. Go to your App Dashboard and select the app you wish to update.
2. In the left side panel of the App Dashboard, click Settings > Basic to view the App Details Panel with your App ID, your App Secret, and other details about your app.
3. To set up your app for advertising set the following details:

2. Link your Ad Account with your App

To run ads and measure installs in the Ads Manager, associate at least one Ad Account with your App.

1. In the App Dashboard click Settings > Advanced.
2. In Authorized Add Account IDs, add your Ad Account IDs. You can get your ad account IDs from your Ads Manager.
3. If you also have a business account, in Authorized Businesses, add your Business Manager ID. You can find your Business Manager id in the URL of your Business Manager

3. Set Up Your Development Environment

1. Install Cocoapods - Open a terminal window and run:

   sudo gem install cocoapods

2. Go to the project directory of the existing project
3. (Optional) If you haven't used Cocoapods in your project, create a pod file for the project. In a terminal window, run:

   pod init

4. Add the following line to the pod file of your project:

   pod 'FacebookSDK' 

5. Install the Facebook SDK. In the terminal window, run the following command:

    pod install 

   For Swift:
   • Add the following to the AppDelegate.swift file:

     import FBSDKCoreKit

   • Add the following line to this function:

     application(_ application: UIApplication, 
     didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey : Any]? = nil) -> Bool

     func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {
       FBSDKApplicationDelegate.sharedInstance().application(application, didFinishLaunchingWithOptions: launchOptions)
     
       // Add any custom logic here.
       
       return true
     }
     
     func application(_ app: UIApplication, open url: URL, options: [UIApplicationOpenURLOptionsKey : Any] = [:]) -> Bool {
       let handled = FBSDKApplicationDelegate.sharedInstance().application(app, open: url, options: options)
     
       // Add any custom logic here.
       
       return handled
     }

   For Objective-C:
   • Add the following to the AppDelegate.m file:

     #import <FBSDKCoreKit/FBSDKCoreKit.h>

   • Add the following to the (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions function in the AppDelegate.m file:

     - (BOOL)application:(UIApplication *)application 
         didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
     		  
         [[FBSDKApplicationDelegate sharedInstance] application:application
         didFinishLaunchingWithOptions:launchOptions];
     
         // Add any custom logic here.
         return YES;
     }
     		
     - (BOOL)application:(UIApplication *)application 
         openURL:(NSURL *)url 
     		options:(NSDictionary<UIApplicationOpenURLOptionsKey,id> *)options {
     		
         BOOL handled = [[FBSDKApplicationDelegate sharedInstance] application:application
             openURL:url
     		    sourceApplication:options[UIApplicationOpenURLOptionsSourceApplicationKey]
     		    annotation:options[UIApplicationOpenURLOptionsAnnotationKey]
         		];
     
       // Add any custom logic here.
     	return handled;
     }

4. Configure Your Information Property List

In Xcode, right-click info.plist and choose Open As Source Code.

• If your code does not have CFBundleURLTypes, add the following just before the final </dict> element:

  <key>CFBundleURLTypes</key>
  <array>
    <dict>
    <key>CFBundleURLSchemes</key>
    <array>
      <string>fb[APP_ID]</string>
    </array>
    </dict>
  </array>
  <key>FacebookAppID</key>
  <string>[APP_ID]</string>
  <key>FacebookDisplayName</key>
  <string>[APP_NAME]</string>
• If your code already contains CFBundleURLTypes, insert the following:

  <array>
    <dict>
    <key>CFBundleURLSchemes</key>
    <array>
      <string>fb[APP_ID]</string>
    </array>
    </dict>
  </array>
  <key>FacebookAppID</key>
  <string>[APP_ID]</string>
  <key>FacebookDisplayName</key>
  <string>[APP_NAME]</string>
• In the XML snippet, replace the following:

  • [APP_ID] with the App ID of your app.
  • [APP_NAME] with the name of your app.

5. Build and Run Your Project in the Simulator

6. Add App Events

There are three types of App Events: Automatically Logged Events, Standard Events, popular events that Facebook has created for you, and Custom Events, events you create that are specific to your app.

You can set up standard events and custom events events in two ways:

• Use our codeless set up tool in Facebook's Events Manager: This is a simple tool for setting up events without implementing codes. You can interact with app screen elements such as buttons, images or links to define event names. As your users navigate through the app and interact with these UI elements, events are sent to Facebook.

• Install your app event code manually: To learn where to place your App Event code in your app, we have example apps with a screen by screen breakdown of the different events and parameters that can be collected in our Best Practices Guide.

Note: If you are using Swift, please refer to App Events with the Facebook SDK for Swift.

Automatically Logged Events

When using the Facebook SDK, certain events in your app are automatically logged and collected for Facebook Analytics unless you disable automatic event logging. These events are relevant for all use cases - targeting, measurement and optimization. There are three key events collected as part of the Automatic App Event Logging: App Install, App Launch, and Purchase. When automatic logging is enabled, advertisers are able to disable the automatic logging of those key events: Installs, Launch, and Purchase. However, if you have disabled automatic logging, but still want to log specific events, such as install or purchase events, manually implement logging for these events in your app.

Disable Automatically Logged Events

To disable automatic event logging, open the application's .plist as code in Xcode and add the following XML to the property dictionary:

<key>FacebookAutoLogAppEventsEnabled</key>
<false/>

In some cases, you want to only delay the collection of automatically logged events, such as to obtain User consent or fulfill legal obligations. Open the application's .plist as code in Xcode and add the same XML to the property dictionary:

<key>FacebookAutoLogAppEventsEnabled</key>
<false/>

Then re-enable auto-logging after an end-user provides consent, by calling the setAutoLogAppEventsEnabled method of the FBSDKSettings class.

For Swift:

FBSDKSettings.setAutoLogAppEventsEnabled(true)

For Objective-C:

[FBSDKSettings setAutoLogAppEventsEnabled:YES];

To suspend collection again for any reasons, add the following line.

For Swift:

FBSDKSettings.setAutoLogAppEventsEnabled(false)

For Objective-C:

[FBSDKSettings setAutoLogAppEventsEnabled:NO];

You can also disable automatic In-App Purchase event logging using the app dashboard. Go to the iOS card under Basic>Settings and toggle the switch to No.

Disable Collection of Advertiser IDs

To disable collection of advertiser-id, open the application's .plist as code in Xcode and add the following XML to the property dictionary:

<key>FacebookAdvertiserIDCollectionEnabled</key>
<false/>

In some cases, you want to delay the collection of advertiser_id, such as to obtain User consent or fulfill legal obligations, instead of disabling it. In this case, open the application's .plist as code in Xcode and add the same XML to the property dictionary:

<key>FacebookAdvertiserIDCollectionEnabled</key>
<false/>

Then, re-enable collection of advertiser_id after the end-user provides consent, by calling the setAdvertiserIDCollectionEnabled method of the FBSDKSettings class.

For Swift:

FBSDKSettings.setAdvertiserIDCollectionEnabled(true);

For Objective-C:

[FBSDKSettings setAdvertiserIDCollectionEnabled:@YES];

To suspend collection for any reason, set the setAdvertiserIDCollectionEnabled method.

For Swift:

FBSDKSettings.setAdvertiserIDCollectionEnabled(false)

For Objective-C:

[FBSDKSettings setAdvertiserIDCollectionEnabled:@NO];

Standard Events

You can add standard events, see the Event Names and Event Parameters below, to your app. Use the Code Generator to get the code for these events.

View some scenarios of App Events in the Example Apps section.

Standard Event Names

Parameters

The following table shows typically useful parameters for inclusion with standard events or with your own custom events. You can also provide your own parameters.

These pre-defined parameters are intended to provide guidance on common logging patterns, and may have a more readable form in reporting and other UIs. 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:

Custom App Events

You can also choose to create your own custom events. Use the Code Generator to generate code for these events.

To log a custom event, just pass the name of the event as an NSString:

[FBSDKAppEvents logEvent:@"battledAnOrc"];

Example Apps

We have created some examples for different app types to make it easier for you to see how you can use app events. Each of the example apps provides a screen by screen breakdown of the different events and parameters that can be collected. At the end of each section, there is a table listing the recommended events and parameters for each app. And, if necessary, you can create your own events and parameters.

7. Test Your Events

The App Ads Helper allows you to test the app events in your app to ensure that your app is sending events to Facebook.

a. Open the App Ads Helper.

b. In Select an App, choose your app and choose Submit.

c. Go to the bottom and choose Test App Events.

d. Start your app and send an event. The event appears on the web page.

Learn More

• Best Practices Guide - View a wide variety of sample apps and how each handles App Events.
• FAQ - Check out our Frequently Asked Questions.