Package 

Class AppEventsLogger

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

    • Method Detail

      • logEvent

         final Unit logEvent(String eventName)

        Log an app event with the specified name.

        Parameters:
        eventName - eventName used to denote the event.

      • logEvent

         final Unit logEvent(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 Unit logEvent(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 Unit logEvent(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 Unit logPurchase(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 Unit logPurchase(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 Unit logPushNotificationOpen(Bundle payload)

        Logs an app event that tracks that the application was open via Push Notification.

        Parameters:
        payload - Notification payload received.

      • logPushNotificationOpen

         final Unit logPushNotificationOpen(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 Unit logProductItem(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 Unit 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.

      • isValidForAccessToken

         final Boolean isValidForAccessToken(AccessToken accessToken)

        Determines if the logger is valid for the given access token.

        Parameters:
        accessToken - The access token to check.