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.

Before You Start

You will need:

• A Facebook Developer Account
• A Facebook Ad Account
• A Facebook Business Portfolio (create a new business portfolio if you don’t already have one)
• A Facebook app

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.

Step 5: Configure Your Project

Step 6: Connect Your App Delegate and Scene Delegate

    
// 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]
        )
    }  
}

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

• Automatically Logged Events - App installs, launches, and in-app purchases are automatically logged with the Facebook SDK.
• The Codeless App Events tool - Use this tool to add Standard Events without adding code to your app.
• Manually Logged Events - Add code to your app to track Standard and Custom Events.

Automatically Logged Events

In-App Purchase Automatically Logged Events

Apple provides four different In-app purchase types: consumable, non-consumable, auto-renewable subscription, and non-renewing subscription. If you implement In-App Purchases with StoreKit 1, we will automatically log each of these In-app purchase types. If you implement In-App Purchases with StoreKit 2, we will automatically log non-consumables, auto-renewable subscriptions, and non-renewing subscriptions. If you would like to also automatically log consumables, you will need to add the SKIncludeConsumableInAppPurchaseHistory key to your Info.plist:

<key>SKIncludeConsumableInAppPurchaseHistory</key>

<true/>

In StoreKit 1, we will automatically log an event when the user successfully purchases a product, restores a product, or attempts to purchase a product but the purchase fails. In Store Kit 2, we will automatically log an event when the user successfully purchases a product or restores a product. If you would like to also log when a purchase fails in Store Kit 2, we have provided a manual API you must call. You can call this API in your StoreKit 2 purchase flow in the following way:

do {
   let result = try await product.purchase()
   switch result {
   case .success(let verificationResult):
       // Handle success case
   case .pending:
       // Handle pending case
   default:
       AppEvents.shared.logFailedStoreKit2Purchase(product.id)
   }
} catch {
   AppEvents.shared.logFailedStoreKit2Purchase(product.id)
}

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.

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

<key>FacebookAdvertiserIDCollectionEnabled</key>
<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

Meta 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.

If you’d like to use app events to measure Dynamic Ads conversions, please set the fb_content_id parameter to be the value of the Product ID used in the associated Dynamic Ad.

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.

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.
• Meta Blueprint course: Configure the SDK and App Events for iOS
• Meta Blueprint course: Use App Events to Target, Optimize and Measure

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.