com.worklight.common

Class WLAnalytics

  • java.lang.Object
    • com.worklight.common.WLAnalytics

  • public class WLAnalytics
extends java.lang.Object

    WLAnalytics means of persistently capturing analytics data and provides a method call to send captured data to the IBM MobileFirst Platform server, to be forwarded to the Operational Analytics engine.

    Capture is on by default.

    When this WLAnalytics class's capture flag is turned on via enable method call, all messages passed through this class's log method will be persisted to file in the following JSON object format: 

     {
   "timestamp"    : "17-02-2013 13:54:27:123",  // "dd-MM-yyyy hh:mm:ss:S"
   "level"        : "ERROR",                    // ERROR || WARN || INFO || LOG || DEBUG
   "package"      : "your_tag",                 // typically a class name, app name, or JavaScript object name
   "msg"          : "the message",              // a helpful log message
   "metadata"     : {"hi": "world"},            // (optional) additional JSON metadata, appended via doLog API call
   "threadid"     : long                        // (optional) id of the current thread
 }

    Log data is accumulated persistently to a log file until the file size is greater than FILE_SIZE_LOG_THRESHOLD. At this point the log file is rolled over. Log data will only be captured once com.worklight.common.WLAnalytics.setContext(Context) is called. Once both files are full, the oldest log data is pushed out to make room for new log data.

    Log file data is sent to the IBM MobileFirst Platform server when this class's send() method is called and the accumulated log size is greater than zero. When the log data is successfully uploaded, the persisted local log data is deleted.

    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class and Description
      static class  WLAnalytics.DeviceEvent
      Set of device attribute changes WLAnalytics can register event listeners for.

    • Constructor Summary

      Constructors 
      Constructor and Description
      WLAnalytics() 

    • Method Summary

      Methods 
      Modifier and Type Method and Description
      static void addDeviceEventListener(WLAnalytics.DeviceEvent deviceEvent)
      Enable analytics to capture the specified DeviceEvent
      static void disable()
      Disable persistent capture of analytics data.
      static void enable()
      Enable persistent capture of analytics data.
      static void init(Application app)
      Initialize WLAnalytics API.
      static void log(java.lang.String message, JSONObject additionalMetadata)
      Log data you want to be captured in the context of "analytics".
      static void log(java.lang.String message, JSONObject additionalMetadata, java.lang.Throwable t)
      Log exceptions you want to be captured in the context of "analytics".
      static void logAppBackground()
      Manually record the application successfully exiting from the user (entering the background) - used to recored app session analytics.
      static void logAppCrash(java.lang.Throwable t)
      Manually record the application crashing - used to record app session analytics.
      static void logAppForeground()
      Manually record the application entering the foreground - used to record app session analytics.
      static void removeDeviceEventListener(WLAnalytics.DeviceEvent deviceEvent)
      Disable analytics from capturing the specified DeviceEvent
      static void send()
      Send the accumulated log data when the persistent log buffer exists and is not empty.
      static void send(com.worklight.wlclient.WLRequestListener listener)
      See WLAnalytics.send()
      static void setContext(Context context)
      Deprecated. 
      use WLAnalytics.init() instead Context object must be set in order to use the WLAnalytics API. This is called automatically by WL.init.
      static void setUserContext(java.lang.String _user)
      Specify current application user.
      static void unsetUserContext()
      Unset any user context previously set.

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    • Field Detail

      • SHARED_PREF_KEY

        public static final java.lang.String SHARED_PREF_KEY

      • SHARED_PREF_KEY_USER_ID

        public static final java.lang.String SHARED_PREF_KEY_USER_ID

      • WAIT_LOCK

        public static final java.lang.Object WAIT_LOCK

    • Constructor Detail

      • WLAnalytics

        public WLAnalytics()

    • Method Detail

      • init

        public static void init(Application app)
        Initialize WLAnalytics API. This must be called before any other WLAnalytics.* methods init should only be called once in your Application subclass. Any subsequent calls will be a no-op. If the configuration needs to be changed, please use the addDeviceEventLister and removeDeviceEventLister methods.
        Parameters:
        app - Android Application to instrument with WLAnalytics.

      • addDeviceEventListener

        public static void addDeviceEventListener(WLAnalytics.DeviceEvent deviceEvent)
        Enable analytics to capture the specified DeviceEvent
        Parameters:
        deviceEvent - the DeviceEvent to capture

      • removeDeviceEventListener

        public static void removeDeviceEventListener(WLAnalytics.DeviceEvent deviceEvent)
        Disable analytics from capturing the specified DeviceEvent
        Parameters:
        deviceEvent - the DeviceEvent to disable

      • setContext

        public static void setContext(Context context)
        Deprecated. use WLAnalytics.init() instead Context object must be set in order to use the WLAnalytics API. This is called automatically by WL.init.
        Parameters:
        context - Android Context object

      • setUserContext

        public static void setUserContext(java.lang.String _user)
        Specify current application user. If you want user-based analytics, you must use this method call. For example, use it when the user logs in, and call the unsetUserContext method when the user logs out. Or if your application supports user profiles, call this method when the user profile changes.
        Parameters:
        _user - User User id for current app user.

      • unsetUserContext

        public static void unsetUserContext()
        Unset any user context previously set.

      • enable

        public static void enable()
        Enable persistent capture of analytics data. Enable, and thus capture, is the default.

      • disable

        public static void disable()
        Disable persistent capture of analytics data.

      • log

        public static void log(java.lang.String message,
       JSONObject additionalMetadata)
        Log data you want to be captured in the context of "analytics". Some data is already captured by the framework. To avoid collisions, the following keys will be excluded if logged:
        • appStoreID
        • appStoreLabel
        • appStoreVersion
        • appStoreVersionDisplay
        • mfpAppName
        • mfpAppVersion
        • deviceBrand
        • deviceOSversion
        • deviceOS
        • deviceModel
        • deviceID
        • timezone
        • timestamp
        Parameters:
        message - Message to be logged.
        additionalMetadata - Meta-data associated with log message.

      • log

        public static void log(java.lang.String message,
       JSONObject additionalMetadata,
       java.lang.Throwable t)
        Log exceptions you want to be captured in the context of "analytics". Some data is already captured by the framework. To avoid collisions, the following keys will be excluded if logged:
        • appStoreID
        • appStoreLabel
        • appStoreVersion
        • appStoreVersionDisplay
        • mfpAppName
        • mfpAppVersion
        • deviceBrand
        • deviceOSversion
        • deviceOS
        • deviceModel
        • deviceID
        • timezone
        • timestamp
        Parameters:
        message - Message to be logged.
        additionalMetadata - Meta-data associated with log message.
        t - a Throwable whose stack trace is converted to string and logged

      • send

        public static void send()
        Send the accumulated log data when the persistent log buffer exists and is not empty. The data accumulates in the log buffer from the use of WLAnalytics with capture (see WLAnalytics.enable()) turned on.

      • send

        public static void send(com.worklight.wlclient.WLRequestListener listener)
        See WLAnalytics.send()
        Parameters:
        listener - WLRequestListener which specifies an onSuccess callback and an onFailure callback (see WLRequestListener)

      • logAppForeground

        public static void logAppForeground()
        Manually record the application entering the foreground - used to record app session analytics.

        Note that once logAppForeground is called a timestamp is stored representing the beginning of the app session. This timestamp will not be overwritten when logAppForeground is called again - this timestamp persists until logAppBackground or logAppCrash are called.

      • logAppBackground

        public static void logAppBackground()
        Manually record the application successfully exiting from the user (entering the background) - used to recored app session analytics.

      • logAppCrash

        public static void logAppCrash(java.lang.Throwable t)
        Manually record the application crashing - used to record app session analytics.


© Copyright IBM Corp. 2006, 2015. All Rights Reserved.