Getting Started with App Events for iOS

App Events is a feature of the Facebook SDK for iOS that 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 from your new or existing iOS app by integrating the Facebook SDK for iOS and then adding events to your app.


You'll need the following before you can add app events to your app:

1. Select an App or Create a New App

Please select an app or create a new one to get a Facebook App ID.

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 navigation 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 - You must provide a Privacy Policy URL. Must be provided to take your app public.
  • Terms of Service URL - You must provide a Terms of Service URL.
See the App Development docs to add more details, an icon or category, to your app.

To run ads and measure installs in the Ads Manager, you need to 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
          // 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
        // 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:
  • If your code already contains CFBundleURLTypes insert the following:
  • 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 will be sent to Facebook.

  • Install your app event codes manually: You will need to add event codes manually to your app. 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, you will need to omit "SDK" from your App Event calls. For example, you would use FBAppEvents instead of FBSDKAppEvents.

Automatically Logged Events

Beginning with v3.22, the Facebook iOS SDK automatically logs app installs, app sessions, and in-app purchases.

After you integrate the Facebook SDK into your app, these events are automatically logged.


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 purchases are automatically logged in new apps created after October 4, 2017. For apps created before that date, enable in-app purchase events in Settings in the app dashboard.

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:


In some cases, you may wish 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:


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

For Swift:


For Objective-C:

[FBSDKSettings setAutoLogAppEventsEnabled:YES];

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

For Swift:


For Objective-C:

[FBSDKSettings setAutoLogAppEventsEnabled: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.

Take a look at our Example Apps to view some scenarios of using App Events.

Standard Event Names

Event Name: FBSDKAppEventName valueToSum Parameters

Achieved Level:



Launched the App:


Clicked on an Ad:



Shown an Ad:



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

Added Contact Information:


Customized a Product:




Searched for a Location:


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

Started a Trial:


Price of Subscription




Submitted an Application:




Price of Subscription




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

Ad Type:



Type of ad: banner, interstitial, reward_video, native




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

Content ID:



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

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

Order ID:



The unique ID for all events within a subscription

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. 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 will not 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 in order 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 required, you can create your own events and parameters.

It is important to note that these guides should be used as 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.