Client-side event logging for specialized application analytics available through Facebook App Insights and for use with Facebook Ads conversion tracking and optimization.
The FBAppEvents
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 FBAppEvents
:
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 FBAppEvents
class in thread-safe in that events may be logged from any of the app's threads.
The developer can set the flushBehavior
on FBAppEvents
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 FBLoggingBehaviorAppEvents
value in [FBSettings setLoggingBehavior:]
.
Some things to note when logging events:
Inherits from: | NSObject |
Declared in: | FBAppEvents.h |
activateApp
Notifies the events system that the app has launched and, when appropriate, logs an "activated app" event. 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.
+ (void)
activateApp;
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.
FBAppEvents.h
flush
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 FBAppEventsLoggingResultNotification
.
+ (void)
flush;
FBAppEvents.h
flushBehavior
Get the current event flushing behavior specifying when events are sent back to Facebook servers.
+ (FBAppEventsFlushBehavior)
flushBehavior;
FBAppEvents.h
limitEventUsage
This method has been replaced by [FBSettings limitEventAndDataUsage]
+ (BOOL)
limitEventUsage __attribute__((deprecated("use [FBSettings limitEventAndDataUsage] instead")));
FBAppEvents.h
logEvent:
Log an event with just an eventName.
Parameter | Description |
---|---|
eventName | The name of the event to record. Limitations on number of events and name length
are given in the |
+ (void)
logEvent:(NSString *)eventName;
FBAppEvents.h
logEvent:parameters:
Log an event with an eventName and a set of key/value pairs in the parameters dictionary. Parameter limitations are described above.
Parameter | Description |
---|---|
eventName | The name of the event to record. Limitations on number of events and name construction
are given in the |
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 |
+ (void)
logEvent: | (NSString *)eventName |
parameters: | (NSDictionary *)parameters; |
FBAppEvents.h
logEvent:valueToSum:
Log an event with an eventName and a numeric value to be aggregated with other events of this name.
Parameter | Description |
---|---|
eventName | The name of the event to record. Limitations on number of events and name length
are given in the |
valueToSum | Amount to be aggregated into all events of this eventName, and App Insights will report the cumulative and average value of this amount. |
+ (void)
logEvent: | (NSString *)eventName |
valueToSum: | (double)valueToSum; |
FBAppEvents.h
logEvent:valueToSum:parameters:
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.
Parameter | Description |
---|---|
eventName | The name of the event to record. Limitations on number of events and name construction
are given in the |
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 |
+ (void)
logEvent: | (NSString *)eventName |
valueToSum: | (double)valueToSum |
parameters: | (NSDictionary *)parameters; |
FBAppEvents.h
logEvent:valueToSum:parameters:session:
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 FBSession. If nil is provided, then [FBSession activeSession]
will be used.
Parameter | Description |
---|---|
eventName | The name of the event to record. Limitations on number of events and name construction
are given in the |
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 |
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 |
session | to direct the event logging to, and thus be logged with whatever user (if any) is associated with that . |
+ (void)
logEvent: | (NSString *)eventName |
valueToSum: | (NSNumber *)valueToSum |
parameters: | (NSDictionary *)parameters |
session: | (FBSession *)session; |
FBAppEvents.h
loggingOverrideAppID
Get the 'override' App ID for App Event logging.
logPurchase:currency:
Log a purchase of the specified amount, in the specified currency.
Parameter | Description |
---|---|
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. |
+ (void)
logPurchase: | (double)purchaseAmount |
currency: | (NSString *)currency; |
This event immediately triggers a flush of the FBAppEvents
event queue, unless the flushBehavior
is set
to FBAppEventsFlushBehaviorExplicitOnly
.
FBAppEvents.h
logPurchase:currency:parameters:
Log a purchase of the specified amount, in the specified currency, also providing a set of additional characteristics describing the purchase.
Parameter | Description |
---|---|
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 |
+ (void)
logPurchase: | (double)purchaseAmount |
currency: | (NSString *)currency |
parameters: | (NSDictionary *)parameters; |
This event immediately triggers a flush of the FBAppEvents
event queue, unless the flushBehavior
is set
to FBAppEventsFlushBehaviorExplicitOnly
.
FBAppEvents.h
logPurchase:currency:parameters:session:
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 FBSession to log to.
Parameter | Description |
---|---|
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 |
session | to direct the event logging to, and thus be logged with whatever user (if any)
is associated with that . A value of |
+ (void)
logPurchase: | (double)purchaseAmount |
currency: | (NSString *)currency |
parameters: | (NSDictionary *)parameters |
session: | (FBSession *)session; |
This event immediately triggers a flush of the FBAppEvents
event queue, unless the flushBehavior
is set
to FBAppEventsFlushBehaviorExplicitOnly
.
FBAppEvents.h
setFlushBehavior:
Set the current event flushing behavior specifying when events are sent back to Facebook servers.
Parameter | Description |
---|---|
flushBehavior | The desired |
+ (void)
setFlushBehavior:(FBAppEventsFlushBehavior)flushBehavior;
FBAppEvents.h
setLimitEventUsage:
This method has been replaced by [FBSettings setLimitEventUsage]
+ (void)
setLimitEventUsage:(BOOL)limitEventUsage __attribute__((deprecated("use [FBSettings setLimitEventAndDataUsage] instead")));
FBAppEvents.h
setLoggingOverrideAppID:
Set the 'override' App ID for App Event logging.
Parameter | Description |
---|---|
appID | The Facebook App ID to be used for App Event logging. |
+ (void)
setLoggingOverrideAppID:(NSString *)appID;
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 FacebookLoggingOverrideAppID
plist value. If that's not set, the default App ID set via [FBSettings setDefaultAppID]
or in the FacebookAppID
plist entry.
This should be set before any other calls are made to FBAppEvents
. Thus, you should set it in your application
delegate's application:didFinishLaunchingWithOptions:
delegate.
FBAppEvents.h
FBAppEventNameAchievedLevel
FBSDK_EXTER N NSString *const FBAppEventNameAchievedLevel;
Log this event when the user has achieved a level in the app.
FBAppEvents.h
FBAppEventNameActivatedApp
FBSDK_EXTER N NSString *const FBAppEventNameActivatedApp __attribute__ ((deprecated("use [FBAppEvents activateApp] instead")));
Deprecated: use [FBAppEvents activateApp] instead.
FBAppEvents.h
FBAppEventNameAddedPaymentInfo
FBSDK_EXTER N NSString *const FBAppEventNameAddedPaymentInfo;
Log this event when the user has entered their payment info.
FBAppEvents.h
FBAppEventNameAddedToCart
FBSDK_EXTER N NSString *const FBAppEventNameAddedToCart;
Log this event when the user has added an item to their cart. The valueToSum passed to logEvent should be the item's price.
FBAppEvents.h
FBAppEventNameAddedToWishlist
FBSDK_EXTER N NSString *const FBAppEventNameAddedToWishlist;
Log this event when the user has added an item to their wishlist. The valueToSum passed to logEvent should be the item's price.
FBAppEvents.h
FBAppEventNameCompletedRegistration
FBSDK_EXTER N NSString *const FBAppEventNameCompletedRegistration;
Log this event when a user has completed registration with the app.
FBAppEvents.h
FBAppEventNameCompletedTutorial
FBSDK_EXTER N NSString *const FBAppEventNameCompletedTutorial;
Log this event when the user has completed a tutorial in the app.
FBAppEvents.h
FBAppEventNameInitiatedCheckout
FBSDK_EXTER N NSString *const FBAppEventNameInitiatedCheckout;
Log this event when the user has entered the checkout process. The valueToSum passed to logEvent should be the total price in the cart.
FBAppEvents.h
FBAppEventNamePurchased
FBSDK_EXTER N NSString *const FBAppEventNamePurchased __attribute__ ((deprecated("use [FBAppEvents logPurchase:currency:] or [FBAppEvents logPurchase:currency:parameters:] instead")));
Deprecated: use [FBAppEvents logPurchase:currency:] or [FBAppEvents logPurchase:currency:parameters:] instead
FBAppEvents.h
FBAppEventNameRated
FBSDK_EXTER N NSString *const FBAppEventNameRated;
Log this event when the user has rated an item in the app. The valueToSum passed to logEvent should be the numeric rating.
FBAppEvents.h
FBAppEventNameSearched
FBSDK_EXTER N NSString *const FBAppEventNameSearched;
Log this event when a user has performed a search within the app.
FBAppEvents.h
FBAppEventNameSpentCredits
FBSDK_EXTER N NSString *const FBAppEventNameSpentCredits;
Log this event when the user has spent app credits. The valueToSum passed to logEvent should be the number of credits spent.
FBAppEvents.h
FBAppEventNameUnlockedAchievement
FBSDK_EXTER N NSString *const FBAppEventNameUnlockedAchievement;
Log this event when the user has unlocked an achievement in the app.
FBAppEvents.h
FBAppEventNameViewedContent
FBSDK_EXTER N NSString *const FBAppEventNameViewedContent;
Log this event when a user has viewed a form of content in the app.
FBAppEvents.h
FBAppEventParameterNameContentID
FBSDK_EXTER N NSString *const FBAppEventParameterNameContentID;
Parameter key used to specify an ID for the specific piece of content being logged about. Could be an EAN, article identifier, etc., depending on the nature of the app.
FBAppEvents.h
FBAppEventParameterNameContentType
FBSDK_EXTER N NSString *const FBAppEventParameterNameContentType;
Parameter key used to specify a generic content type/family for the logged event, e.g. "music", "photo", "video". Options to use will vary based upon what the app is all about.
FBAppEvents.h
FBAppEventParameterNameCurrency
FBSDK_EXTER N NSString *const FBAppEventParameterNameCurrency;
Parameter key used to specify currency used with logged event. E.g. "USD", "EUR", "GBP". See ISO-4217 for specific values. One reference for these is http://en.wikipedia.org/wiki/ISO_4217
.
FBAppEvents.h
FBAppEventParameterNameDescription
FBSDK_EXTER N NSString *const FBAppEventParameterNameDescription;
Parameter key used to specify a description appropriate to the event being logged. E.g., the name of the achievement unlocked in the FBAppEventNameAchievementUnlocked
event.
FBAppEvents.h
FBAppEventParameterNameLevel
FBSDK_EXTER N NSString *const FBAppEventParameterNameLevel;
Parameter key used to specify the level achieved in a FBAppEventNameAchieved
event.
FBAppEvents.h
FBAppEventParameterNameMaxRatingValue
FBSDK_EXTER N NSString *const FBAppEventParameterNameMaxRatingValue;
Parameter key used to specify the maximum rating available for the FBAppEventNameRate
event. E.g., "5" or "10".
FBAppEvents.h
FBAppEventParameterNameNumItems
FBSDK_EXTER N NSString *const FBAppEventParameterNameNumItems;
Parameter key used to specify how many items are being processed for an FBAppEventNameInitiatedCheckout
or FBAppEventNamePurchased
event.
FBAppEvents.h
FBAppEventParameterNamePaymentInfoAvailable
FBSDK_EXTER N NSString *const FBAppEventParameterNamePaymentInfoAvailable;
Parameter key used to specify whether payment info is available for the FBAppEventNameInitiatedCheckout
event. FBAppEventParameterValueYes
and FBAppEventParameterValueNo
are good canonical values to use for this parameter.
FBAppEvents.h
FBAppEventParameterNameRegistrationMethod
FBSDK_EXTER N NSString *const FBAppEventParameterNameRegistrationMethod;
Parameter key used to specify method user has used to register for the app, e.g., "Facebook", "email", "Twitter", etc
FBAppEvents.h
FBAppEventParameterNameSearchString
FBSDK_EXTER N NSString *const FBAppEventParameterNameSearchString;
Parameter key used to specify the string provided by the user for a search operation.
FBAppEvents.h
FBAppEventParameterNameSuccess
FBSDK_EXTER N NSString *const FBAppEventParameterNameSuccess;
Parameter key used to specify whether the activity being logged about was successful or not. FBAppEventParameterValueYes
and FBAppEventParameterValueNo
are good canonical values to use for this parameter.
FBAppEvents.h
FBAppEventParameterValueNo
FBSDK_EXTER N NSString *const FBAppEventParameterValueNo;
No-valued parameter value to be used with parameter keys that need a Yes/No value
FBAppEvents.h
FBAppEventParameterValueYes
FBSDK_EXTER N NSString *const FBAppEventParameterValueYes;
Yes-valued parameter value to be used with parameter keys that need a Yes/No value
FBAppEvents.h
FBAppEventsLoggingResultNotification
FBSDK_EXTER N NSString *const FBAppEventsLoggingResultNotification;
NSNotificationCenter name indicating a result of a failed log flush attempt
FBAppEvents.h
NS_ENUM (NSUInteger, FBAppEventsFlushBehavior)
Control when FBAppEvents sends log events to the server
typedef NS_ENUM(NSUInteger, FBAppEventsFlushBehavior) { FBAppEventsFlushBehaviorAuto = 0, FBAppEventsFlushBehaviorExplicitOnly, };
Constant | Description |
---|---|
FBAppEventsFlushBehaviorAuto | Flush automatically: periodically (once a minute or every 100 logged events) and always at app reactivation. |
FBAppEventsFlushBehaviorExplicitOnly | Only flush when the |
FBAppEvents.h