Get Started with App Events on iOS

This guide shows you how to add App Events to your new or existing app by integrating the Facebook SDK then logging these events.

Changes have been made to the Facebook iOS SDK. We recommend upgrading to the new version of the Facebook iOS SDK. See the Device Consent section for more information about this change.

Before You Start

You will need:

Step 1: Configure Your Facebook App

Go to the App Dashboard, click My Apps, and create a new app if you don't already have one. Navigate to Settings > Basic to view the App Details Panel with your App ID, your App Secret, and other details about your app.

Scroll down to the bottom of the page and click Add Platform. Choose iOS, add your app details, and save your changes.

Set up your app for advertising by adding the following details:

  • App Domains - Provide Apple App Store URL of your app.
  • Privacy Policy URL - Provide a Privacy Policy URL. Required to take your app public.
  • Terms of Service URL - Provide a Terms of Service URL.
  • Platform - Scroll to the bottom of the Settings panel to add the iOS Platform.

To learn more about adding details to your app, such as an icon or category, visit the App Development docs.

Step 2: Link your ad and business portfolios

To run ads and measure installs in the Ads Manager, associate at least one ad account and a business portfolio with your App.

  1. In the App Dashboard click Settings > Advanced.
  2. In Authorized Ad Account IDs, add your Ad Account IDs. You can get your ad account IDs from your Ads Manager.
  3. In the Advertising Accounts Panel, click Get Started and follow the instructions to connect the app to a Business.

Step 3: Set Up Your Development Environment

The following procedure uses Swift Package Manager to set up your development environment in Xcode.

  1. In Xcode, click File > Add Packages....
  2. In the search field that appears, enter the repository URL: https://github.com/facebook/facebook-ios-sdk.
  3. In Dependency Rule, select Up to Next Major Version and enter a recent version. The most current release is listed at https://github.com/facebook/facebook-ios-sdk/releases/
  4. Choose the libraries you intend to use and the targets to which you want to add those libraries.
  5. Click on Add Package to complete your setup.

Step 4: Register and Configure Your App with Facebook

Add Your Bundle Identifier and enable Single Sign-On for your app.

The bundle identifier (Bundle ID) should appear in the box below. If the box is empty, find your bundle identifier in your Xcode Project's iOS Application Target and paste it into the box below.
Bundle ID
You can change your bundle identifier in the future via the iOS section on the settings page.
Enable Single Sign On
Enable single sign on for your app by setting Single Sign On to Yes below.
Single sign on Will launch from iOS Notifications

Step 5: Configure Your Project

Configure the Info.plist file with an XML snippet that contains data about your app.

After you integrate Facebook Login, certain App Events are automatically logged and collected for Events Manager, unless you disable Automatic App Event Logging. In particular, when launching an app in Korea, please note that Automatic App Event Logging can be disabled. For details about what information is collected and how to disable automatic app event logging, see Automatic App Event Logging.

  1. Right-click Info.plist, and choose Open As ▸ Source Code.
  2. Copy and paste the following XML snippet into the body of your file ( <dict>...</dict>).
    <key>CFBundleURLTypes</key>
    <array>
      <dict>
      <key>CFBundleURLSchemes</key>
      <array>
        <string>fbAPP-ID</string>
      </array>
      </dict>
    </array>
    <key>FacebookAppID</key>
    <string>APP-ID</string>
    <key>FacebookClientToken</key>
    <string>CLIENT-TOKEN</string>
    <key>FacebookDisplayName</key>
    <string>APP-NAME</string>
  3. In <array><string> in the key [CFBundleURLSchemes], replace APP-ID with your App ID.
  4. In <string> in the key FacebookAppID, replace APP-ID with your App ID.
  5. In <string> in the key FacebookClientToken, replace CLIENT-TOKEN with the value found under Settings > Advanced > Client Token in your App Dashboard.
  6. In <string> in the key FacebookDisplayName, replace APP-NAME with the name of your app.
  7. To use any of the Facebook dialogs (e.g., Login, Share, App Invites, etc.) that can perform an app switch to Facebook apps, your application's Info.plist also needs to include the following:
    <key>LSApplicationQueriesSchemes</key>
    <array>
      <string>fbapi</string>
      <string>fb-messenger-share-api</string>
    </array>

You may directly set the automatic collection of App Events to “true” or “false” by adding FacebookAutoLogAppEventsEnabled as a key in Info.plist.

Your project will need to include the Keychain Sharing capability in order for login to work in Mac Catalyst applications.
  1. Select the + Capability button in the Signing & Capabilities tab when configuring your app target.
  2. Find and select the Keychain Sharing capability.
  3. Ensure that the Keychain Sharing capability is listed for the target.

Step 6: Connect Your App Delegate and Scene Delegate

Replace the code in AppDelegate.swift method with the following code. This code initializes the SDK when your app launches, and allows the SDK to handle logins and sharing from the native Facebook app when you perform a Login or Share action. Otherwise, the user must be logged into Facebook to use the in-app browser to login.
    
// AppDelegate.swift
import UIKit
import FacebookCore

@UIApplicationMain
class AppDelegate: UIResponder, UIApplicationDelegate {    
    func application(
        _ application: UIApplication,
        didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
    ) -> Bool {          
        ApplicationDelegate.shared.application(
            application,
            didFinishLaunchingWithOptions: launchOptions
        )

        return true
    }
          
    func application(
        _ app: UIApplication,
        open url: URL,
        options: [UIApplication.OpenURLOptionsKey : Any] = [:]
    ) -> Bool {
        ApplicationDelegate.shared.application(
            app,
            open: url,
            sourceApplication: options[UIApplication.OpenURLOptionsKey.sourceApplication] as? String,
            annotation: options[UIApplication.OpenURLOptionsKey.annotation]
        )
    }  
}

iOS 13 moved opening URL functionality to the SceneDelegate. If you are using iOS 13, add the following method to your SceneDelegate so that operations like logging in or sharing function as intended:
// SceneDelegate.swift
import FacebookCore
  ...
func scene(_ scene: UIScene, openURLContexts URLContexts: Set<UIOpenURLContext>) {
    guard let url = URLContexts.first?.url else {
        return
    }

    ApplicationDelegate.shared.application(
        UIApplication.shared,
        open: url,
        sourceApplication: nil,
        annotation: [UIApplication.OpenURLOptionsKey.annotation]
    )
}

Step 7: Add App Events

There are three ways events are tracked in your app:

App Store Connect for iOS 14

Events that your app collects and sends to Facebook may require you to disclose these data types in the App Store Connect questionnaire. It is your responsibility to ensure this is reflected in your application’s privacy policy. Visit the Apple App Store Privacy Details article to learn more about the data types you will need to disclose.

Automatically Logged Events

When using the Facebook SDK, certain events in your app are automatically logged and collected for Facebook Events Manager 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 these events, as well as other Facebook internal events such as login impression events. 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 a person launches your app, the Facebook SDK is initialized and the event is logged. However, if a second app launch event occurs within 60 seconds of the first, the second app launch event is not logged.

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.

Facebook SDK Crash Report

(For Facebook Use Only.)

If your app crashed due to the Facebook SDK, a crash report is generated and sent to Facebook when your app is restarted. This report contains no user data and helps Facebook ensure the quality and stability of the SDK. To opt out of logging this event, disable automatically logged events.

Get Device Consent

Starting with iOS 14.5, you will need to set isAdvertiserTrackingEnabled and log each time you give a device permission to share data with Facebook.

If a device provides consent, set Settings.shared.isAdvertiserTrackingEnabled = true.

If a device does not allow tracking, set Settings.shared.isAdvertiserTrackingEnabled = false.

Disable Automatically Logged Events

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

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

In some cases, you want to delay the collection of automatically logged events, such as to obtain User consent or fulfill legal obligations, instead of disable it. In this case, set Settings.shared.isAutoLogAppEventsEnabled = true to re-enable auto-logging after the end-user provides consent.

To suspend collection again for any reasons, set Settings.shared.isAutoLogAppEventsEnabled = false.

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, set Settings.shared.isAdvertiserIDCollectionEnabled = true after the end-user provides consent.

To suspend collection for any reason, set Settings.shared.isAdvertiserIDCollectionEnabled = false.

Manually Log Events

To log a custom event, just pass the name of the event as an AppEvents.Name:

AppEvents.shared.logEvent(AppEvents.Name("battledAnOrc"))

Event Parameters

Facebook has created a set of useful event 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. 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 a dictionary where the key holds the parameter name as an AppEvents.ParameterName, and the value must be either a String or a number (Int, Double, etc.).

Step 8: 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.

  1. Open the App Ads Helper.
  2. In Select an App, choose your app and choose Submit.
  3. Scroll to the bottom and choose Test Event.
  4. Start your app and send an event. The event should appear on the page.

If you plan to optimize/track your events in SKAdNetwork campaigns, you also need to properly configure event priority (also known as conversion value) in order for Facebook to correctly receive the conversions. More details can be found here.

Learn More

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.