iOS SDK Version
FBSDKCoreKit Reference

FBSDKAppEvents

@interfaceFBSDKAppEvents:NSObject
Client-side event logging for specialized application analytics available through Facebook App Insights and for use with Facebook Ads conversion tracking and optimization.
The FBSDKAppEvents static class has a few related roles:
  • Logging predefined and application-defined events to Facebook App Insights with a numeric value to sum across a large number of events, and an optional set of key/value parameters that define “segments” for this event (e.g., ‘purchaserStatus’ : ‘frequent’, or ‘gamerLevel’ : ‘intermediate’)
  • Logging events to later be used for ads optimization around lifetime value.
  • Methods that control the way in which events are flushed out to the Facebook servers.
Here are some important characteristics of the logging mechanism provided by FBSDKAppEvents:
  • Events are not sent immediately when logged. They’re cached and flushed out to the Facebook servers in a number of situations:
  • when an event count threshold is passed (currently 100 logged events).
  • when a time threshold is passed (currently 15 seconds).
  • when an app has gone to background and is then brought back to the foreground.
  • Events will be accumulated when the app is in a disconnected state, and sent when the connection is restored and one of the above ‘flush’ conditions are met.
  • The FBSDKAppEvents class is thread-safe in that events may be logged from any of the app’s threads.
  • The developer can set the flushBehavior on FBSDKAppEvents to force the flushing of events to only occur on an explicit call to the flush method.
  • The developer can turn on console debug output for event logging and flushing to the server by using the FBSDKLoggingBehaviorAppEvents value in [FBSettings setLoggingBehavior:].
Some things to note when logging events:
  • There is a limit on the number of unique event names an app can use, on the order of 1000.
  • There is a limit to the number of unique parameter names in the provided parameters that can be used per event, on the order of 25. This is not just for an individual call, but for all invocations for that eventName.
  • Event names and parameter names (the keys in the NSDictionary) must be between 2 and 40 characters, and must consist of alphanumeric characters, _, -, or spaces.
  • The length of each parameter value can be no more than on the order of 100 characters.
  • Unavailable
    Undocumented

    Declaration

    Objective-C
    -(instancetype)initNS_UNAVAILABLE;
  • Unavailable
    Undocumented

    Declaration

    Objective-C
    +(instancetype)newNS_UNAVAILABLE;
  • The current event flushing behavior specifying when events are sent back to Facebook servers.

    Declaration

    Objective-C
    @property(class,nonatomic,assign,unsafe_unretained,readwrite)FBSDKAppEventsFlushBehaviorflushBehavior;
    Swift
    classvarflushBehavior:AppEvents.FlushBehavior{getset}
  • Set the ‘override’ App ID for App Event logging.
    In some cases, apps want to use one Facebook App ID for login and social presence and another for App Event logging. (An example is if multiple apps from the same company share an app ID for login, but want distinct logging.) By default, this value is nil, and defers to the FBSDKAppEventsOverrideAppIDBundleKey plist value. If that’s not set, it defaults to [FBSDKSettings appID].
    This should be set before any other calls are made to FBSDKAppEvents. Thus, you should set it in your application delegate’s application:didFinishLaunchingWithOptions: delegate.

    Declaration

    Objective-C
    @property(class,nonatomic,copy,readwrite,nullable)NSString*loggingOverrideAppID;
    Swift
    classvarloggingOverrideAppID:String?{getset}
  • Undocumented

    Declaration

    Objective-C
    @property(class,nonatomic,copy,nullable)NSString*userID
    Swift
    classvaruserID:String?{getset}
  • Undocumented

    Declaration

    Objective-C
    @property(class,nonatomic,readonly)NSString*anonymousID
    Swift
    classvaranonymousID:String{get}
  • Log an event with just an eventName.

    Declaration

    Objective-C
    +(void)logEvent:(nonnullFBSDKAppEventName)eventName;
    Swift
    classfunclogEvent(_eventName:AppEvents.Name)

    Parameters

    eventName
    The name of the event to record. Limitations on number of events and name length are given in the FBSDKAppEvents documentation.
  • Log an event with an eventName and a numeric value to be aggregated with other events of this name.

    Declaration

    Objective-C
    +(void)logEvent:(nonnullFBSDKAppEventName)eventNamevalueToSum:(double)valueToSum;
    Swift
    classfunclogEvent(_eventName:AppEvents.Name,valueToSum:Double)

    Parameters

    eventName
    The name of the event to record. Limitations on number of events and name length are given in the FBSDKAppEvents documentation. Common event names are provided in FBAppEventName* constants.
    valueToSum
    Amount to be aggregated into all events of this eventName, and App Insights will report the cumulative and average value of this amount.
  • Log an event with an eventName and a set of key/value pairs in the parameters dictionary. Parameter limitations are described above.

    Declaration

    Objective-C
    +(void)logEvent:(nonnullFBSDKAppEventName)eventNameparameters:(nonnullNSDictionary<NSString*,id>*)parameters;
    Swift
    classfunclogEvent(_eventName:AppEvents.Name,parameters:[String:Any])

    Parameters

    eventName
    The name of the event to record. Limitations on number of events and name construction are given in the FBSDKAppEvents documentation. Common event names are provided in FBAppEventName* constants.
    parameters
    Arbitrary parameter dictionary of characteristics. The keys to this dictionary must be NSString’s, and the values are expected to be NSString or NSNumber. Limitations on the number of parameters and name construction are given in the FBSDKAppEvents documentation. Commonly used parameter names are provided in FBSDKAppEventParameterName* constants.
  • Log an event with an eventName, a numeric value to be aggregated with other events of this name, and a set of key/value pairs in the parameters dictionary.

    Declaration

    Objective-C
    +(void)logEvent:(nonnullFBSDKAppEventName)eventNamevalueToSum:(double)valueToSumparameters:(nonnullNSDictionary<NSString*,id>*)parameters;
    Swift
    classfunclogEvent(_eventName:AppEvents.Name,valueToSum:Double,parameters:[String:Any])

    Parameters

    eventName
    The name of the event to record. Limitations on number of events and name construction are given in the FBSDKAppEvents documentation. Common event names are provided in FBAppEventName* constants.
    valueToSum
    Amount to be aggregated into all events of this eventName, and App Insights will report the cumulative and average value of this amount.
    parameters
    Arbitrary parameter dictionary of characteristics. The keys to this dictionary must be NSString’s, and the values are expected to be NSString or NSNumber. Limitations on the number of parameters and name construction are given in the FBSDKAppEvents documentation. Commonly used parameter names are provided in FBSDKAppEventParameterName* constants.
  • Log an event with an eventName, a numeric value to be aggregated with other events of this name, and a set of key/value pairs in the parameters dictionary. Providing session lets the developer target a particular
    . If nil is provided, then [FBSession activeSession] will be used.

    Declaration

    Objective-C
    +(void)logEvent:(nonnullFBSDKAppEventName)eventNamevalueToSum:(nullableNSNumber*)valueToSumparameters:(nonnullNSDictionary<NSString*,id>*)parametersaccessToken:(nullableFBSDKAccessToken*)accessToken;
    Swift
    classfunclogEvent(_eventName:AppEvents.Name,valueToSum:NSNumber?,parameters:[String:Any],accessToken:FBSDKAccessToken?)

    Parameters

    eventName
    The name of the event to record. Limitations on number of events and name construction are given in the FBSDKAppEvents documentation. Common event names are provided in FBAppEventName* constants.
    valueToSum
    Amount to be aggregated into all events of this eventName, and App Insights will report the cumulative and average value of this amount. Note that this is an NSNumber, and a value of nil denotes that this event doesn’t have a value associated with it for summation.
    parameters
    Arbitrary parameter dictionary of characteristics. The keys to this dictionary must be NSString’s, and the values are expected to be NSString or NSNumber. Limitations on the number of parameters and name construction are given in the FBSDKAppEvents documentation. Commonly used parameter names are provided in FBSDKAppEventParameterName* constants.
    accessToken
    The optional access token to log the event as.
  • Log a purchase of the specified amount, in the specified currency.

    Declaration

    Objective-C
    +(void)logPurchase:(double)purchaseAmountcurrency:(nonnullNSString*)currency;
    Swift
    classfunclogPurchase(_purchaseAmount:Double,currency:String)

    Parameters

    purchaseAmount
    Purchase amount to be logged, as expressed in the specified currency. This value will be rounded to the thousandths place (e.g., 12.34567 becomes 12.346).
    currency
    Currency, is denoted as, e.g. “USD”, “EUR”, “GBP”. See ISO-4217 for specific values. One reference for these is http://en.wikipedia.org/wiki/ISO_4217.
    Thiseventimmediatelytriggersaflushofthe`FBSDKAppEvents`eventqueue,unlessthe`flushBehavior`isset
    to FBSDKAppEventsFlushBehaviorExplicitOnly.
  • Log a purchase of the specified amount, in the specified currency, also providing a set of additional characteristics describing the purchase.

    Declaration

    Objective-C
    +(void)logPurchase:(double)purchaseAmountcurrency:(nonnullNSString*)currencyparameters:(nonnullNSDictionary<NSString*,id>*)parameters;
    Swift
    classfunclogPurchase(_purchaseAmount:Double,currency:String,parameters:[String:Any])

    Parameters

    purchaseAmount
    Purchase amount to be logged, as expressed in the specified currency.This value will be rounded to the thousandths place (e.g., 12.34567 becomes 12.346).
    currency
    Currency, is denoted as, e.g. “USD”, “EUR”, “GBP”. See ISO-4217 for specific values. One reference for these is http://en.wikipedia.org/wiki/ISO_4217.
    parameters
    Arbitrary parameter dictionary of characteristics. The keys to this dictionary must be NSString’s, and the values are expected to be NSString or NSNumber. Limitations on the number of parameters and name construction are given in the FBSDKAppEvents documentation. Commonly used parameter names are provided in FBSDKAppEventParameterName* constants.
    Thiseventimmediatelytriggersaflushofthe`FBSDKAppEvents`eventqueue,unlessthe`flushBehavior`isset
    to FBSDKAppEventsFlushBehaviorExplicitOnly.
  • Log a purchase of the specified amount, in the specified currency, also providing a set of additional characteristics describing the purchase, as well as an
    to log to.

    Declaration

    Objective-C
    +(void)logPurchase:(double)purchaseAmountcurrency:(nonnullNSString*)currencyparameters:(nonnullNSDictionary<NSString*,id>*)parametersaccessToken:(nullableFBSDKAccessToken*)accessToken;
    Swift
    classfunclogPurchase(_purchaseAmount:Double,currency:String,parameters:[String:Any],accessToken:FBSDKAccessToken?)

    Parameters

    purchaseAmount
    Purchase amount to be logged, as expressed in the specified currency.This value will be rounded to the thousandths place (e.g., 12.34567 becomes 12.346).
    currency
    Currency, is denoted as, e.g. “USD”, “EUR”, “GBP”. See ISO-4217 for specific values. One reference for these is http://en.wikipedia.org/wiki/ISO_4217.
    parameters
    Arbitrary parameter dictionary of characteristics. The keys to this dictionary must be NSString’s, and the values are expected to be NSString or NSNumber. Limitations on the number of parameters and name construction are given in the FBSDKAppEvents documentation. Commonly used parameter names are provided in FBSDKAppEventParameterName* constants.
    accessToken
    The optional access token to log the event as.
    Thiseventimmediatelytriggersaflushofthe`FBSDKAppEvents`eventqueue,unlessthe`flushBehavior`isset
    to FBSDKAppEventsFlushBehaviorExplicitOnly.
  • Log an app event that tracks that the application was open via Push Notification.

    Declaration

    Objective-C
    +(void)logPushNotificationOpen:(nonnullNSDictionary*)payload;
    Swift
    classfunclogPushNotificationOpen(_payload:[AnyHashable:Any])

    Parameters

    payload
    Notification payload received via UIApplicationDelegate.
  • Log an app event that tracks that a custom action was taken from a push notification.

    Declaration

    Objective-C
    +(void)logPushNotificationOpen:(nonnullNSDictionary*)payloadaction:(nonnullNSString*)action;
    Swift
    classfunclogPushNotificationOpen(_payload:[AnyHashable:Any],action:String)

    Parameters

    payload
    Notification payload received via UIApplicationDelegate.
    action
    Name of the action that was taken.
  • Uploads product catalog product item as an app event

    Declaration

    Objective-C
    +(void)logProductItem:(nonnullNSString*)itemIDavailability:(FBSDKProductAvailability)availabilitycondition:(FBSDKProductCondition)conditiondescription:(nonnullNSString*)descriptionimageLink:(nonnullNSString*)imageLinklink:(nonnullNSString*)linktitle:(nonnullNSString*)titlepriceAmount:(double)priceAmountcurrency:(nonnullNSString*)currencygtin:(nullableNSString*)gtinmpn:(nullableNSString*)mpnbrand:(nullableNSString*)brandparameters:(nullableNSDictionary<NSString*,id>*)parameters;
    Swift
    classfunclogProductItem(_itemID:String,availability:AppEvents.ProductAvailability,condition:AppEvents.ProductCondition,description:String,imageLink:String,link:String,title:String,priceAmount:Double,currency:String,gtin:String?,mpn:String?,brand:String?,parameters:[String:Any]?)

    Parameters

    itemID
    Unique ID for the item. Can be a variant for a product. Max size is 100.
    availability
    If item is in stock. Accepted values are: in stock - Item ships immediately out of stock - No plan to restock preorder - Available in future available for order - Ships in 1-2 weeks discontinued - Discontinued
    condition
    Product condition: new, refurbished or used.
    description
    Short text describing product. Max size is 5000.
    imageLink
    Link to item image used in ad.
    link
    Link to merchant’s site where someone can buy the item.
    title
    Title of item.
    priceAmount
    Amount of purchase, in the currency specified by the ‘currency’ parameter. This value will be rounded to the thousandths place (e.g., 12.34567 becomes 12.346).
    currency
    Currency used to specify the amount. E.g. “USD”, “EUR”, “GBP”. See ISO-4217 for specific values. One reference for these is http://en.wikipedia.org/wiki/ISO_4217
    gtin
    Global Trade Item Number including UPC, EAN, JAN and ISBN
    mpn
    Unique manufacture ID for product
    brand
    Name of the brand Note: Either gtin, mpn or brand is required.
    parameters
    Optional fields for deep link specification.
  • Notifies the events system that the app has launched and, when appropriate, logs an “activated app” event. This function is called automatically from FBSDKApplicationDelegate applicationDidBecomeActive, unless one overrides ‘FacebookAutoLogAppEventsEnabled’ key to false in the project info plist file. In case ‘FacebookAutoLogAppEventsEnabled’ is set to false, then it should typically be placed in the app delegates’ applicationDidBecomeActive: method.
    This method also takes care of logging the event indicating the first time this app has been launched, which, among other things, is used to track user acquisition and app install ads conversions.
    activateApp will not log an event on every app launch, since launches happen every time the app is backgrounded and then foregrounded. “activated app” events will be logged when the app has not been active for more than 60 seconds. This method also causes a “deactivated app” event to be logged when sessions are “completed”, and these events are logged with the session length, with an indication of how much time has elapsed between sessions, and with the number of background/foreground interruptions that session had. This data is all visible in your app’s App Events Insights.

    Declaration

    Objective-C
    +(void)activateApp;
    Swift
    classfuncactivateApp()
  • Sets and sends device token to register the current application for push notifications.
    Sets and sends a device token from NSData representation that you get from UIApplicationDelegate.-application:didRegisterForRemoteNotificationsWithDeviceToken:.

    Declaration

    Objective-C
    +(void)setPushNotificationsDeviceToken:(nonnullNSData*)deviceToken;
    Swift
    classfuncsetPushNotificationsDeviceToken(_deviceToken:Data)

    Parameters

    deviceToken
    Device token data.
  • Sets and sends device token string to register the current application for push notifications.
    Sets and sends a device token string

    Declaration

    Objective-C
    +(void)setPushNotificationsDeviceTokenString:(nonnullNSString*)deviceTokenString;
    Swift
    classfuncsetPushNotificationsDeviceToken(_deviceTokenString:String)

    Parameters

    deviceTokenString
    Device token string.
  • Explicitly kick off flushing of events to Facebook. This is an asynchronous method, but it does initiate an immediate kick off. Server failures will be reported through the NotificationCenter with notification ID FBSDKAppEventsLoggingResultNotification.

    Declaration

    Objective-C
    +(void)flush;
    Swift
    classfuncflush()
  • Creates a request representing the Graph API call to retrieve a Custom Audience “third party ID” for the app’s Facebook user. Callers will send this ID back to their own servers, collect up a set to create a Facebook Custom Audience with, and then use the resultant Custom Audience to target ads.
    The JSON in the request’s response will include an “custom_audience_third_party_id” key/value pair, with the value being the ID retrieved. This ID is an encrypted encoding of the Facebook user’s ID and the invoking Facebook app ID. Multiple calls with the same user will return different IDs, thus these IDs cannot be used to correlate behavior across devices or applications, and are only meaningful when sent back to Facebook for creating Custom Audiences.
    The ID retrieved represents the Facebook user identified in the following way: if the specified access token is valid, the ID will represent the user associated with that token; otherwise the ID will represent the user logged into the native Facebook app on the device. If there is no native Facebook app, no one is logged into it, or the user has opted out at the iOS level from ad tracking, then a nil ID will be returned.
    This method returns nil if either the user has opted-out (via iOS) from Ad Tracking, the app itself has limited event usage via the [FBSDKSettings limitEventAndDataUsage] flag, or a specific Facebook user cannot be identified.

    Declaration

    Objective-C
    +(nullableFBSDKGraphRequest*)requestForCustomAudienceThirdPartyIDWithAccessToken:(nullableFBSDKAccessToken*)accessToken;
    Swift
    classfuncrequestForCustomAudienceThirdPartyID(withaccessToken:FBSDKAccessToken?)->FBSDKGraphRequest?

    Parameters

    accessToken
    The access token to use to establish the user’s identity for users logged into Facebook through this app. If nil, then the [FBSDKAccessToken currentAccessToken] is used.
  • Undocumented

    Declaration

    Objective-C
    +(void)clearUserID;
    Swift
    classfuncclearUserID()
  • Undocumented

    Declaration

    Objective-C
    +(void)setUserEmail:(nullableNSString*)emailfirstName:(nullableNSString*)firstNamelastName:(nullableNSString*)lastNamephone:(nullableNSString*)phonedateOfBirth:(nullableNSString*)dateOfBirthgender:(nullableNSString*)gendercity:(nullableNSString*)citystate:(nullableNSString*)statezip:(nullableNSString*)zipcountry:(nullableNSString*)countryNS_SWIFT_NAME(setUser(email:firstName:lastName:phone:dateOfBirth:gender:city:state:zip:country:));
    Swift
    classfuncsetUser(email:String?,firstName:String?,lastName:String?,phone:String?,dateOfBirth:String?,gender:String?,city:String?,state:String?,zip:String?,country:String?)
  • Undocumented

    Declaration

    Objective-C
    +(nullableNSString*)getUserData;
    Swift
    classfuncgetUserData()->String?
  • Undocumented

    Declaration

    Objective-C
    +(void)clearUserData;
    Swift
    classfuncclearUserData()
  • Undocumented

    Declaration

    Objective-C
    +(void)setUserData:(nullableNSString*)dataforType:(FBSDKAppEventUserDataType)type;
    Swift
    classfuncsetUserData(_data:String?,forTypetype:AppEvents.UserDataType)
  • Undocumented

    Declaration

    Objective-C
    +(void)clearUserDataForType:(FBSDKAppEventUserDataType)type;
    Swift
    classfuncclearUserData(forTypetype:AppEvents.UserDataType)
  • Deprecated
    updateUserProperties is deprecated
    Undocumented

    Declaration

    Objective-C
    +(void)updateUserProperties:(NSDictionary<NSString*,id>*)propertieshandler:(nullableFBSDKGraphRequestBlock)handler__attribute__((deprecated("updateUserProperties is deprecated")));
    Swift
    classfuncupdateUserProperties(_properties:[String:Any],handler:GraphRequestBlock?=nil)
  • Undocumented

    Declaration

    Objective-C
    +(void)augmentHybridWKWebView:(WKWebView*)webView;
    Swift
    classfuncaugmentHybridWKWebView(_webView:WKWebView)
  • Set if the Unity is already initialized

    Declaration

    Objective-C
    +(void)setIsUnityInit:(BOOL)isUnityInit;
    Swift
    classfuncsetIsUnityInit(_isUnityInit:Bool)

    Parameters

    isUnityInit
    whether Unity is initialized.
  • Undocumented

    Declaration

    Objective-C
    +(void)sendEventBindingsToUnity;
    Swift
    classfuncsendEventBindingsToUnity()