AppEventsLogger
这个类有新版本。查看 最新版本。

The AppEventsLogger class allows the developer to log various types of events back to Facebook. In order to log events, the app must create an instance of this class via a newLogger.newLogger method, and then call the various "log" methods off of that.

This client-side event logging is then available through Facebook App Insights and for use with Facebook Ads conversion tracking and optimization.

The AppEventsLogger 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'). These events may also be used for ads conversion tracking, optimization, and other ads related targeting in the future.

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

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 60 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 AppEventsLogger class is intended to be used from the thread it was created on. Multiple AppEventsLoggers may be created on other threads if desired.

The developer can call the setFlushBehavior method 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 Settings.addLoggingBehavior(LoggingBehavior.APP_EVENTS);

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

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

扩展:Object
应用安装包:facebook
类方法
getLimitEventUsage(Context)

Sets whether events sent to Facebook should be restricted from being used for purposes than analytics and conversions, such as remarketing for this user. Defaults to false. This value is stored on the device and persists across app launches.

public static boolean getLimitEventUsage(Context context)
参数描述
contextUsed to read the value.
setLimitEventUsage(Context, boolean)

Sets whether events sent to Facebook should be restricted from being used for purposes than analytics and conversions, such as remarketing for this user. Defaults to false. This value is stored on the device and persists across app launches. Changes to this setting will apply to any events currently queued to be flushed, as well as any subsequent events.

public static void setLimitEventUsage(Context context, boolean limitEventUsage)
参数描述
contextUsed to persist this value across app runs.
limitEventUsage
activateApp(Context)

Notifies the events system that the app has launched & logs an activatedApp event. Should be called whenever your app becomes active, typically in the onResume() method of each long-running Activity of your app.

Use this method if your application ID is stored in application metadata, otherwise see AppEventsLogger.activateApp(android.content.Context, String).

public static void activateApp(Context context)
参数描述
contextUsed to access the applicationId and the attributionId for non-authenticated users.
activateApp(Context, String)

Notifies the events system that the app has launched & logs an activatedApp event. Should be called whenever your app becomes active, typically in the onResume() method of each long-running Activity of your app.

public static void activateApp(Context context, String applicationId)
参数描述
contextUsed to access the attributionId for non-authenticated users.
applicationIdThe specific applicationId to report the activation for.
newLogger(Context)

Build an AppEventsLogger instance to log events through. The Facebook app that these events are targeted at comes from this application's metadata. The application ID used to log events will be determined from the app ID specified in the package metadata.

public static AppEventsLogger newLogger(Context context)
参数描述
contextUsed to access the applicationId and the attributionId for non-authenticated users.
Returns
AppEventsLogger instance to invoke log* methods on.
newLogger(Context, Session)

Build an AppEventsLogger instance to log events through.

public static AppEventsLogger newLogger(Context context, Session session)
参数描述
contextUsed to access the attributionId for non-authenticated users.
sessionExplicitly specified Session to log events against. If null, the activeSession will be used if it's open, otherwise the logging will happen against the default app ID specified via the app ID specified in the package metadata.
Returns
AppEventsLogger instance to invoke log* methods on.
newLogger(Context, String, Session)

Build an AppEventsLogger instance to log events through.

public static AppEventsLogger newLogger(Context context, String applicationId, Session session)
参数描述
contextUsed to access the attributionId for non-authenticated users.
applicationIdExplicitly specified Facebook applicationId to log events against. If null, the default app ID specified in the package metadata will be used.
sessionExplicitly specified Session to log events against. If null, the activeSession will be used if it's open, otherwise the logging will happen against the specified app ID.
Returns
AppEventsLogger instance to invoke log* methods on.
newLogger(Context, String)

Build an AppEventsLogger instance to log events that are attributed to the application but not to any particular Session.

public static AppEventsLogger newLogger(Context context, String applicationId)
参数描述
contextUsed to access the attributionId for non-authenticated users.
applicationIdExplicitly specified Facebook applicationId to log events against. If null, the default app ID specified in the package metadata will be used.
Returns
AppEventsLogger instance to invoke log* methods on.
getFlushBehavior()

Access the behavior that AppEventsLogger uses to determine when to flush logged events to the server. This setting applies to all instances of AppEventsLogger.

public static FlushBehavior getFlushBehavior()
Returns
Specified flush behavior.
setFlushBehavior(FlushBehavior)

Set the behavior that this AppEventsLogger uses to determine when to flush logged events to the server. This setting applies to all instances of AppEventsLogger.

public static void setFlushBehavior(FlushBehavior flushBehavior)
参数描述
flushBehaviorThe desired behavior.
onContextStop()

Call this when the consuming Activity/Fragment receives an onStop() callback in order to persist any outstanding events to disk, so they may be flushed at a later time. The next flush (explicit or not) will check for any outstanding events and, if present, include them in that flush. Note that this call may trigger an I/O operation on the calling thread. Explicit use of this method is not necessary if the consumer is making use of UiLifecycleHelper, which will take care of making the call in its own onStop() callback.

public static void onContextStop()
实例方法
logEvent(String)

Log an app event with the specified name.

public void logEvent(String eventName)
参数描述
eventNameEventName used to denote the event. Choose amongst the EVENT_NAME_* constants in AppEventsConstants when possible. Or create your own if none of the EVENT_NAME_* constants are applicable. Event names should be 40 characters or less, alphanumeric, and can include spaces, underscores or hyphens, but mustn't have a space or hyphen as the first character. Any given app should have no more than ~300 distinct event names.
logEvent(String, double)

Log an app event with the specified name and the supplied value.

public void logEvent(String eventName, double valueToSum)
参数描述
eventNameEventName used to denote the event. Choose amongst the EVENT_NAME_* constants in AppEventsConstants when possible. Or create your own if none of the EVENT_NAME_* constants are applicable. Event names should be 40 characters or less, alphanumeric, and can include spaces, underscores or hyphens, but mustn't have a space or hyphen as the first character. Any given app should have no more than ~300 distinct event names. * @param eventName
valueToSumA value to associate with the event which will be summed up in Insights for across all instances of the event, so that average values can be determined, etc.
logEvent(String, Bundle)

Log an app event with the specified name and set of parameters.

public void logEvent(String eventName, Bundle parameters)
参数描述
eventNameEventName used to denote the event. Choose amongst the EVENT_NAME_* constants in AppEventsConstants when possible. Or create your own if none of the EVENT_NAME_* constants are applicable. Event names should be 40 characters or less, alphanumeric, and can include spaces, underscores or hyphens, but mustn't have a space or hyphen as the first character. Any given app should have no more than ~300 distinct event names.
parametersA Bundle of parameters to log with the event. Insights will allow looking at the logs of these events via different parameter values. You can log on the order of 10 parameters with each distinct eventName. It's advisable to keep the number of unique values provided for each parameter in the, at most, thousands. As an example, don't attempt to provide a unique parameter value for each unique user in your app. You won't get meaningful aggregate reporting on so many parameter values. The values in the bundles should be Strings or numeric values.
logEvent(String, double, Bundle)

Log an app event with the specified name, supplied value, and set of parameters.

public void logEvent(String eventName, double valueToSum, Bundle parameters)
参数描述
eventNameEventName used to denote the event. Choose amongst the EVENT_NAME_* constants in AppEventsConstants when possible. Or create your own if none of the EVENT_NAME_* constants are applicable. Event names should be 40 characters or less, alphanumeric, and can include spaces, underscores or hyphens, but mustn't have a space or hyphen as the first character. Any given app should have no more than ~300 distinct event names.
valueToSumA value to associate with the event which will be summed up in Insights for across all instances of the event, so that average values can be determined, etc.
parametersA Bundle of parameters to log with the event. Insights will allow looking at the logs of these events via different parameter values. You can log on the order of 10 parameters with each distinct eventName. It's advisable to keep the number of unique values provided for each parameter in the, at most, thousands. As an example, don't attempt to provide a unique parameter value for each unique user in your app. You won't get meaningful aggregate reporting on so many parameter values. The values in the bundles should be Strings or numeric values.
logPurchase(BigDecimal, Currency)

Logs a purchase event with Facebook, in the specified amount and with the specified currency.

public void logPurchase(BigDecimal purchaseAmount, Currency currency)
参数描述
purchaseAmountAmount 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).
currencyCurrency used to specify the amount.
logPurchase(BigDecimal, Currency, Bundle)

Logs a purchase event with Facebook, in the specified amount and with the specified currency. Additional detail about the purchase can be passed in through the parameters bundle.

public void logPurchase(BigDecimal purchaseAmount, Currency currency, Bundle parameters)
参数描述
purchaseAmountAmount 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).
currencyCurrency used to specify the amount.
parametersArbitrary additional information for describing this event. Should have no more than 10 entries, and keys should be mostly consistent from one purchase event to the next.
flush()

Explicitly flush any stored events to the server. Implicit flushes may happen depending on the value of getFlushBehavior. This method allows for explicit, app invoked flushing.

public void flush()
logSdkEvent(String, Double, Bundle)

This method is intended only for internal use by the Facebook SDK and other use is unsupported.

public void logSdkEvent(String eventName, Double valueToSum, Bundle parameters)
参数描述
eventName
valueToSum
parameters
getApplicationId()

Returns the app ID this logger was configured to log to.

public String getApplicationId()
Returns
The Facebook app ID
常量
ACTION_APP_EVENTS_FLUSHED
The action used to indicate that a flush of app events has occurred. This should be used as an action in an IntentFilter and BroadcastReceiver registered with the LocalBroadcastManager.
public static final String ACTION_APP_EVENTS_FLUSHED
APP_EVENTS_EXTRA_NUM_EVENTS_FLUSHED
public static final String APP_EVENTS_EXTRA_NUM_EVENTS_FLUSHED
APP_EVENTS_EXTRA_FLUSH_RESULT
public static final String APP_EVENTS_EXTRA_FLUSH_RESULT