Android SDK Version
facebook Reference

public final class 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 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 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 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 by calling FacebookSdk.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 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 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.
Nested Class Summary
Modifier and TypeClassDescription
public enumAppEventsLogger.FlushBehavior
Controls when an AppEventsLogger sends log events to the server
public enumAppEventsLogger.ProductAvailability
Product availability for Product Catalog product item update
public enumAppEventsLogger.ProductCondition
Product condition for Product Catalog product item update
public classAppEventsLogger.Companion
Field Summary
Modifier and TypeFieldDescription
private final StringapplicationId
Method Summary
Modifier and TypeMethodDescription
final StringgetApplicationId()
final UnitlogEvent(String eventName) Log an app event with the specified name.
final UnitlogEvent(String eventName, Double valueToSum) Log an app event with the specified name and the supplied value.
final UnitlogEvent(String eventName, Bundle parameters) Log an app event with the specified name and set of parameters.
final UnitlogEvent(String eventName, Double valueToSum, Bundle parameters) Log an app event with the specified name, supplied value, and set of parameters.
final UnitlogPurchase(BigDecimal purchaseAmount, Currency currency) Logs a purchase event with Facebook, in the specified amount and with the specified currency.
final UnitlogPurchase(BigDecimal purchaseAmount, Currency currency, Bundle parameters) Logs a purchase event with Facebook explicitly, in the specified amount and with the specified currency.
final UnitlogPushNotificationOpen(Bundle payload) Logs an app event that tracks that the application was open via Push Notification.
final UnitlogPushNotificationOpen(Bundle payload, String action) Logs an app event that tracks that the application was open via Push Notification.
final UnitlogProductItem(String itemID, AppEventsLogger.ProductAvailability availability, AppEventsLogger.ProductCondition condition, String description, String imageLink, String link, String title, BigDecimal priceAmount, Currency currency, String gtin, String mpn, String brand, Bundle parameters) Uploads product catalog product item as an app event.
final Unitflush() Explicitly flush any stored events to the server.
final BooleanisValidForAccessToken(AccessToken accessToken) Determines if the logger is valid for the given access token.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
Method Detail

getApplicationId

 final StringgetApplicationId()

logEvent

 final UnitlogEvent(String eventName)
Log an app event with the specified name.
Parameters:
eventName - eventName used to denote the event.

logEvent

 final UnitlogEvent(String eventName, Double valueToSum)
Log an app event with the specified name and the supplied value.
Parameters:
eventName - eventName used to denote the event.
valueToSum - a 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

 final UnitlogEvent(String eventName, Bundle parameters)
Log an app event with the specified name and set of parameters.
Parameters:
eventName - eventName used to denote the event.
parameters - A Bundle of parameters to log with the event.

logEvent

 final UnitlogEvent(String eventName, Double valueToSum, Bundle parameters)
Log an app event with the specified name, supplied value, and set of parameters.
Parameters:
eventName - eventName used to denote the event.
valueToSum - a 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.
parameters - A Bundle of parameters to log with the event.

logPurchase

 final UnitlogPurchase(BigDecimal purchaseAmount, Currency currency)
Logs a purchase event with Facebook, in the specified amount and with the specified currency.
Parameters:
purchaseAmount - Amount of purchase, in the currency specified by the 'currency' parameter.
currency - Currency used to specify the amount.

logPurchase

 final UnitlogPurchase(BigDecimal purchaseAmount, Currency currency, Bundle parameters)
Logs a purchase event with Facebook explicitly, in the specified amount and with the specified currency. Additional detail about the purchase can be passed in through the parameters bundle.
Parameters:
purchaseAmount - Amount of purchase, in the currency specified by the 'currency' parameter.
currency - Currency used to specify the amount.
parameters - Arbitrary additional information for describing this event.

logPushNotificationOpen

 final UnitlogPushNotificationOpen(Bundle payload)
Logs an app event that tracks that the application was open via Push Notification.
Parameters:
payload - Notification payload received.

logPushNotificationOpen

 final UnitlogPushNotificationOpen(Bundle payload, String action)
Logs an app event that tracks that the application was open via Push Notification.
Parameters:
payload - Notification payload received.

logProductItem

 final UnitlogProductItem(String itemID, AppEventsLogger.ProductAvailability availability, AppEventsLogger.ProductCondition condition, String description, String imageLink, String link, String title, BigDecimal priceAmount, Currency currency, String gtin, String mpn, String brand, Bundle parameters)
Uploads product catalog product item as an app event.
Parameters:
itemID - Unique ID for the item.
availability - If item is in stock.
condition - Product condition: new, refurbished or used.
description - Short text describing product.
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.
currency - Currency used to specify the amount.
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.

flush

 final Unitflush()
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.

isValidForAccessToken

 final BooleanisValidForAccessToken(AccessToken accessToken)
Determines if the logger is valid for the given access token.
Parameters:
accessToken - The access token to check.