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.

Requirements

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, such as 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. Set Up Your Development Environment

  1. Install Cocoapods - Open a terminal window and run: sudo gem install cocoapods
  2. Create a new Swift project and go to the project directory. If you are using an existing project, go to project directory of the existing project.
  3. 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 'FacebookCore'
  5. Install the Facebook SDK. In the terminal window, run the following command: pod install
    For Swift:
    • Add the following the AppDelegate.swift file: import FacebookCore
    • Add the following statement to the applicationDidBecomeActive function in the AppDelegate.swift file: AppEventsLogger.activate(application)
    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, Pre-defined Events, popular events that Facebook has created for you, and Custom Events, events you create that are specific to your app.

Automatically Logged Events

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

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.

Because these events are already in the Facebook SDK there is no need to add these events to your code.

Pre-defined Events

You can add pre-defined 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 Pre-defined Event

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

Event Names

Event Name: FBSDKAppEventName valueToSum Parameters

Achieved Level:

FBSDKAppEventNameAchievedLevel

Level

App Launched:

FBSDKAppEventNameActivatedApp

Added Payment Info:

FBSDKAppEventNameAddedPaymentInfo

Success

Added To Cart:

FBSDKAppEventNameAddedToCart

Price of item added

ContentType, ContentID or Content, and Currency

Added To Wishlist:

FBSDKAppEventNameAddedToWishlist

Price of item added

ContentType, ContentID or Content, and Currency

Completed Registration:

FBSDKAppEventNameCompletedRegistration

RegistrationMethod

Completed Tutorial:

FBSDKAppEventNameCompletedTutorial

Success, and ContentID or Content

Initiated Checkout:

FBSDKAppEventNameInitiatedCheckout

Total price of items in cart

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

Purchased:

`FBSDKAppEventNamePurchased`

Use the logPurchase method instead.

Purchase price

NumItems, ContentType, ContentID or Content, and Currency

Rated:

FBSDKAppEventNameRated

Rating given

ContentType, ContentID or Content, and MaxRatingValue

Searched:

FBSDKAppEventNameSearched

ContentType, SearchString, and Success

Spent Credits:

FBSDKAppEventNameSpentCredits

Total value of credits spent

ContentType, and ContentID or Content

Unlocked Achievement:

FBSDKAppEventNameUnlockedAchievement

Description

Viewed Content:

FBSDKAppEventNameViewedContent

Price of item viewed (if applicable)

ContentType, ContentID or Content, and Currency

Parameters

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:

FBSDKAppEventParameterNameContentID

string

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

Content:

FBSDKAppEventParameterNameContent

string

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 Type:

FBSDKAppEventParameterNameContentType

string

product or product_group

Currency:

FBSDKAppEventParameterNameCurrency

string

ISO 4217 code, e.g., 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

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 text 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 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 Pre-defined Event

  1. Choose the Custom Event tab.
  2. In Event Name, choose a pre-defined event.
  3. Choose Get Code.
  4. In the window, select a language to see 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"];

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.

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.

More Resources

For more information and helpful hints on App Events check out:

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