Reference (Old Docs)
FBInsights
This class is no longer available in the most recent version of the SDK.
A more recent version of this class is available. Check out the latest version.

Client-side event logging for specialized application analytics available through Facebook Insights and Conversion Pixel conversion tracking for ads optimization.

Discussion:

The FBInsights static class has a few related roles:

  • Logging predefined events to Facebook Application 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 'purchase' events to later be used for ads optimization around lifetime value.

  • Logging 'conversion pixels' for use in ads conversion tracking and optimization.

  • 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 FBInsights:

  • 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.
  • when a time threshold is passed.

  • 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 FBInsights class in thread-safe in that events may be logged from any of the app's threads.

Some things to note when logging events:

  • 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 10. 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
  • The length of each parameter value can be no more than on the order of 100 characters.
  • When logging events, the "client token" must be set. An exception will be thrown if it isn't. See [FBSettings setClientToken] for more information.
Inherits from:NSObject
Declared in:FBInsights.h
Class Methods
appVersion

Gets the application version to the provided string. Insights allows breakdown of events by app version.

+ (NSString *) appVersion;
Declared In: FBInsights.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 FBInsightsLoggingResultNotification.

+ (void) flush;
Declared In: FBInsights.h
flushBehavior

Get the current event flushing behavior specifying when events are sent back to Facebook servers.

+ (FBInsightsFlushBehavior) flushBehavior;
Declared In: FBInsights.h
logConversionPixel:valueOfPixel:

Log, or "Fire" a Conversion Pixel. Conversion Pixels are used for Ads Conversion Tracking. See https://www.facebook.com/help/435189689870514 to learn more.

ParameterDescription
pixelID

Numeric ID for the conversion pixel to be logged. See https://www.facebook.com/help/435189689870514 to learn how to create a conversion pixel.

value

Value of what the logging of this pixel is worth to you. The currency that this is expressed in doesn't matter, so long as it is consistent across all logging for this pixel. This value will be rounded to the thousandths place (e.g., 12.34567 becomes 12.346).

+ (void)
logConversionPixel: (NSString *)pixelID
valueOfPixel: (double)value;
Discussion:

This event immediately triggers a flush of the FBInsights event queue, unless the flushBehavior is set to FBInsightsFlushBehaviorExplicitOnly. The "client token" must be set via [FBSettings setClientToken] prior to calling this method. An exception is thrown if it's not.

Declared In: FBInsights.h
logConversionPixel:valueOfPixel:session:

Log, or "Fire" a Conversion Pixel. Conversion Pixels are used for Ads Conversion Tracking. See https://www.facebook.com/help/435189689870514 to learn more.

ParameterDescription
pixelID

Numeric ID for the conversion pixel to be logged. See https://www.facebook.com/help/435189689870514 to learn how to create a conversion pixel.

value

Value of what the logging of this pixel is worth to you. The currency that this is expressed in doesn't matter, so long as it is consistent across all logging for this pixel. This value will be rounded to the thousandths place (e.g., 12.34567 becomes 12.346).

session

to direct the event logging to, and thus be logged with whatever user (if any) is associated with that . A value of nil will use [FBSession activeSession].

+ (void)
logConversionPixel: (NSString *)pixelID
valueOfPixel: (double)value
session: (FBSession *)session;
Discussion:

This event immediately triggers a flush of the FBInsights event queue, unless the flushBehavior is set to FBInsightsFlushBehaviorExplicitOnly. The "client token" must be set via [FBSettings setClientToken] prior to calling this method. An exception is thrown if it's not.

Declared In: FBInsights.h
logPurchase:currency:

Log a purchase of the specified amount, in the specified currency.

ParameterDescription
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;
Discussion:

This event immediately triggers a flush of the FBInsights event queue, unless the flushBehavior is set to FBInsightsFlushBehaviorExplicitOnly. The "client token" must be set via [FBSettings setClientToken] prior to calling this method. An exception is thrown if it's not.

Declared In: FBInsights.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.

ParameterDescription
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 FBInsights documentation.

+ (void)
logPurchase: (double)purchaseAmount
currency: (NSString *)currency
parameters: (NSDictionary *)parameters;
Discussion:

This event immediately triggers a flush of the FBInsights event queue, unless the flushBehavior is set to FBInsightsFlushBehaviorExplicitOnly. The "client token" must be set via [FBSettings setClientToken] prior to calling this method. An exception is thrown if it's not.

Declared In: FBInsights.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.

ParameterDescription
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 FBInsights documentation.

session

to direct the event logging to, and thus be logged with whatever user (if any) is associated with that . A value of nil will use [FBSession activeSession].

+ (void)
logPurchase: (double)purchaseAmount
currency: (NSString *)currency
parameters: (NSDictionary *)parameters
session: (FBSession *)session;
Discussion:

This event immediately triggers a flush of the FBInsights event queue, unless the flushBehavior is set to FBInsightsFlushBehaviorExplicitOnly. The "client token" must be set via [FBSettings setClientToken] prior to calling this method. An exception is thrown if it's not.

Declared In: FBInsights.h
setAppVersion:

Sets the application version to the provided string. Insights allows breakdown of events by app version.

ParameterDescription
appVersion

The version identifier of the iOS app that events are being logged through. Enables analysis and breakdown of logged events by app version.

+ (void) setAppVersion:(NSString *)appVersion;
Declared In: FBInsights.h
setFlushBehavior:

Set the current event flushing behavior specifying when events are sent back to Facebook servers.

ParameterDescription
flushBehavior

The desired FBInsightsFlushBehavior to be used.

+ (void) setFlushBehavior:(FBInsightsFlushBehavior)flushBehavior;
Declared In: FBInsights.h
Constants
FBInsightsLoggingResultNotification
extern NSString *const FBInsightsLoggingResultNotification;
Discussion:

NSNotificationCenter name indicating a result of a log flush attempt

Declared In: FBInsights.h
Typedefs
FBInsightsFlushBehavior enum

Control when FBInsights sends log events to the server

typedef enum {
FBInsightsFlushBehaviorAuto,
FBInsightsFlushBehaviorExplicitOnly,
} FBInsightsFlushBehavior;
Discussion:

If an instance of an app doesn't send during its lifetime, or can't establish connectivity, the events will be stashed for the next run and sent then.

Declared In: FBInsights.h