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:

Requirements

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

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:
  • App Domains - Provide Apple App Store URL of your app.
  • Platform - Scroll to the bottom of the Settings panel to add the iOS Platform.
  • Privacy Policy URL - Provide a Privacy Policy URL. Required to take your app public.
  • Terms of Service URL - Provide a Terms of Service URL.
To add more details to your app, such as an icon or category, visit the App Development docs.

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

In Xcode, select an iOS simulator and click Run. Xcode builds your project and then launches the most recent version of your app running in 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.

The instructions below are for version 4.0 and higher of the SDK. If you are still using version 3.X, omit "SDK" from your App Event calls. For example, you would use FBAppEvents instead of FBSDKAppEvents.

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.

EventDetails

App Install

The first time a new user activates an app or the first time an app starts on a particular device.

App Launch

When the Facebook SDK is initialized in your app for each session.

In-App Purchase

When a purchase processed by the Apple App Store or Google Play has been completed. If you use other payments platforms, you will need to add purchase event code manually.

In-app purchase logging is automatically enabled for apps that have installed or upgraded to v4.39. For apps running an earlier version, enable in-app purchase events in Basic > Settings iOS card in the app dashboard or add the purchase event code manually.

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.

To Generate Code for a Standard Event

  1. Choose the Standard Event tab.
  2. In Event Name, choose a standard event.
  3. Choose Get Code.
  4. In the window, select a language to see the code to copy and paste into your app.

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

Standard Event Names

Event Name: FBSDKAppEventName Parameters Description

Achieve Level: FBSDKAppEventNameAchievedLevel

Level

The achievement of specific levels you define within your application, business or organization.

Activate App: FBSDKAppEventNameActivatedApp

The launch of your app.

In-App Ad Click: FBSDKAppEventNameAdClick

AdType

An ad from a third-party platform is clicked within your app.

In-App Ad Impression: FBSDKAppEventNameAdImpression

AdType

An ad from a third-party platform appears on-screen within your app.

Add Payment Info: FBSDKAppEventNameAddedPaymentInfo

Success

The addition of customer payment information during a checkout process.

Add to Cart: FBSDKAppEventNameAddedToCart

valueToSum: Price of item added

ContentType, ContentID or Content, and Currency

The addition of an item to a shopping cart or basket. For example, clicking an Add to Cart button on a website.

Add to Wishlist: FBSDKAppEventNameAddedToWishlist

valueToSum: Price of item added

ContentType, ContentID or Content, and Currency

The addition of items to a wishlist. For example, clicking an Add to Wishlist button on a website.

Complete Registration: FBSDKAppEventNameCompletedRegistration

RegistrationMethod

A submission of information by a customer in exchange for a service provided by your business. For example, sign up for an email subscription.

Complete Tutorial: FBSDKAppEventNameCompletedTutorial

Success, and ContentID or Content

A completion of a tutorial on your app.

Contact: FBSDKAppEventNameContact

A telephone or SMS, email, chat or other type of contact between a customer and your business.

Customize Product: FBSDKAppEventNameCustomizeProduct

The customization of products through a configuration tool or other application your business owns.

Donate: FBSDKAppEventNameDonate

The donation of funds to your organization or cause.

Find Location: FBSDKAppEventNameFindLocation

When a person finds one of your locations via web or app, with an intention to visit. For example, searching for a product and finding it at one of your local stores.

Initiate Checkout: FBSDKAppEventNameInitiatedCheckout

valueToSum: Total price of items in cart

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

The start of a checkout process.

Purchase: FBSDKAppEventNamePurchased

Use the logPurchase method instead.

valueToSum: Purchase price

NumItems, ContentType, ContentID or Content, and Currency

The completion of a purchase, usually signified by receiving order or purchase confirmation or a transaction receipt.

Rate: FBSDKAppEventNameRated

valueToSum: Rating given

ContentType, ContentID or Content, and MaxRatingValue

A rating of something within your app, business or organization. For example, rates a restaurant within a restaurant review app

Schedule: FBSDKAppEventNameSchedule

The booking of an appointment to visit one of your locations.

Search: FBSDKAppEventNameSearched

ContentType, SearchString, and Success

A search performed on your website, app or other property, such as product searches, travel searches, etc.

Spent Credits: FBSDKAppEventNameSpentCredits

valueToSum: Total value of credits spent

ContentType, and ContentID or Content

The completion of a transaction where people spend credits specific to your business or application, such as in-app currency.

Start Trial: FBSDKAppEventNameStartTrial

valueToSum: Total value of credits spent

OrderID

and

Currency

The start of a free trial of a product or service you offer, such as a trial subscription.

Submit Application: FBSDKAppEventNameSubmitApplication

The submission of an application for a product, service or program you offer, such as a credit card, educational program or job.

Subscription: FBSDKAppEventNameSubscription

valueToSum: Price of Subscription

OrderID

and

Currency

The start of a paid subscription for a product or service you offer.

Unlock Achievement: FBSDKAppEventNameUnlockedAchievement

Description

The completion of specific activities or actions you want to reward within your application, business or organization. For example, refer a friend, complete your profile, etc.

View Content: FBSDKAppEventNameViewedContent

valueToSum: Price of item viewed (if applicable)

ContentType, ContentID or Content, and Currency

A visit to a content page you care about, such as a product page, landing page or article. Information about the page viewed can be passed to Facebook for use in dynamic ads.

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:

Parameter: FBSDKAppEventParameterName Possible Values Description

Ad Type:

FBSDKAppEventParameterNameAdType

string

Type of ad: banner, interstitial, reward_video, native

Content:

FBSDKAppEventParameterNameContent

string

A list of JSON object that contains the International Article Number (EAN) when applicable, or other product or content identifiers and additional information about the products. id and quantity are the available fields. e.g. "[{\"id\": \"1234\", \"quantity\": 2}, {\"id\": \"5678\", \"quantity\": 1}]"

Content ID:

FBSDKAppEventParameterNameContentID

string

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

Content Type:

FBSDKAppEventParameterNameContentType

string

product or product_group

Currency:

FBSDKAppEventParameterNameCurrency

string

ISO 4217 code, for example, EUR, USD, JPY

Description:

FBSDKAppEventParameterNameDescription

string

A string description

Level:

FBSDKAppEventParameterNameLevel

string

Level of a player

Max. Rating Value:

FBSDKAppEventParameterNameMaxRatingValue

int

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

Number of Items:

FBSDKAppEventParameterNameNumItems

int

Number of items

Order ID:

FBSDKAppEventParameterNameOrderID

string

The unique ID for all events within a subscription

Payment Info Available:

FBSDKAppEventParameterNamePaymentInfoAvailable

1 or 0

1 for yes, 0 for no

Registration Method:

FBSDKAppEventParameterNameRegistrationMethod

string

Facebook, Email, Twitter, etc.

Search String:

FBSDKAppEventParameterNameSearchString

string

The string that was searched for

Success:

FBSDKAppEventParameterNameSuccess

1 or 0

1 for yes, 0 for no

Custom App Events

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

Do not use event as the name of a parameter. Custom parameters with the name event are be logged. Use another name or add a prefix or suffix to the name, such as my_custom_event.

To Generate Code for a Custom Event

  1. Choose the Custom Event tab.
  2. In Event Name, enter the name of your event.
  3. Click Add Event Paramter if you'd like to add parameters to your event.
  4. Click Get Code.
  5. In the window, select a language to get the code to copy and paste into your app.

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.

It is important to note that these examples are a starting point for your app and should be customized by you.

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.