Overview

Skill Level: Intermediate

You add the Acoustic Tealeaf SDK for Android to your application so it can capture user interface and application events. You manually install and configure the Tealeaf SDK in each application. Installing and configuring the Tealeaf SDK for Android involves these major steps:
1. Move files to the proper locations in your application.
2. Configure auto-instrumentation (AA).
3. Configure properties, including application-specific URLs.
4. Extend Application and Activity classes.

Prerequisites

To get started, you need:

  • The Acoustic Experience Analytics (Tealeaf) package.
  • The Acoustic Experience Analytics (Tealeaf) sample application. You deploy the sample application that is provided byAcoustic Experience Analytics (Tealeaf) to test the capabilities and measure the effects of the Android SDK. Instead of integrating the Android SDK with your application in development, you deploy the sample application and complete any necessary configuration steps on the remainder of this page to begin to capture mobile app data into your instance of .
  • To understand and meet the Android development environment requirements.
  • To understand Acoustic Experience Analytics (Tealeaf) impact on device resources. In benchmark tests, the Android SDK has the following effects on resources of the visitor’s device.
    • 2-3% more memory consumption
      Note: If the server is unreachable, the SDK saves data to memory until the server is reachable. By default the SDK will store up to 512000 bytes to the device memory. If the cache grows larger than 512000 bytes, the oldest data is truncated from cache and is deleted. The cache size is managed through the CachedFileMaxBytesSize setting in EOCoreAdvancedConfig.json.
    • Minimal effect on battery life

For more information, see the Acoustic Experience Analytics (Tealeaf) SDK for Android overview page

Step-by-step

  1. Install the Tealeaf Android SDK (with rakefile or manually).

    After you acquire Acoustic Experience Analytics (Tealeaf) Android SDK, you can install the SDK as a package using Rakefile or you can manually install the SDK into your application project.

    Using Rakefile to install the SDK eases the installation and integration process by automatically performing most integration steps that would otherwise be performed manually.

    Note: The rake tool should be used as a helper tool to auto install the Acoustic Experience Analytics (Tealeaf) Android SDK and setup common instrumentation scenario. You may need to manually install the SDK if it is not compatible with your project.

    Installing with Rakefile

    Before you can use Rakefile to install the Android SDK, the following items must already be installed:

    • Ruby v1.9.3
    • Ruby gems

    For more information on these requirements, see Ruby and Download RubyGems.

    To install the SDK as a package using Rakefile, follow these steps:

    1. From a command line, use the following Rakefile commands to complete a new SDK integration with Android Studio for an on-premises or on Cloud installation.

    Acoustic Analytics for Mobile (on-premises):

     

    rake modulePath="/Users/<username>/dev/RTC_Production/AndroidSrc/FragManualClean/app"
    postMessageUrl="http://<target_URL>/store/js/tealeaf/TealeafTarget.php"
     killswitchUrl="http://<target_URL>/store/js/tealeaf/killswitch.php"
    

    Acoustic Analytics for Mobile (on Cloud):

    rake modulePath="/Users/<username>/dev/RTC_Production/AndroidSrc/FragManualClean/app"
    postMessageUrl="http://decollector.tealeaf.ibmcloud.com/collector/collectorPost"
     killswitchUrl="http://decollector.tealeaf.ibmcloud.com/collector/switch/9131b982167c4e82899999cdfe951be3"
    appKey="9131b982167c4e82899999cdfe951be3"
    

    where,

    • modulePath: Defines the path where Android Studio module is located. Note: In the example, replace <username> with the active user name.
    • postMessageUrl: Points to the URL POST of the target page. Note: In the example, replace <target_URL> with the IP address for the target page.
    • killSwitchUrl: Points to the URL of the kill switch. Note: In the example, replace <target_URL> with the URL for the kill switch.
    • appKey: Defines the application key value for Acoustic Experience Analytics (Tealeaf) .

     

    Manually installing the Android SDK libraries into an Android application project

    To manually install the Android SDK libraries into an Android application project, follow these steps. Note: Your Eclipse project must include the frameworks that follow in steps 1 to 3.

    1. Install the EOCore.jar and TealeafMod.jar into the libs folder of your Android application to make the capture functions available in your application. Add the files into the build path of the application you want to instrument.

    2. Integrate Acoustic Experience Analytics (Tealeaf) SDK files into your Android project by copying the following Acoustic Experience Analytics (Tealeaf) SDK files to the specified folder for your Android project.

     File name Android project location
     TealeafBasicConfig.properties   assets folder
     TealeafAdvancedConfig.json   assets folder
     TealeafLayoutConfig.json   assets folder
     EOCoreBasicConfig.properties   assets folder
     EOCoreAdvancedConfig.json   assets folder

     eocore.jar

    libs folder
    tealeafmod.jar libs folder

     Note: In Android Studio, you will need to add the following files to the build.gradle file. Use the following snippet as an example of how to add the files to build.gradle, where  xx.x.x is replaced  with the version number of the Android library instance.

    dependencies {
    compile 'com.android.support:appcompat-v7:xx.x.x'
    compile files('libs/eocore.jar')
    compile files('libs/tealeafmod.jar')}
    

    3. After you have integrated theAcoustic Experience Analytics (Tealeaf) SDK files with your Android project, use the following procedure to register the Acoustic Experience Analytics (Tealeaf) SDK files in AndroidManifest.xml.

    1. Open AndroidManifest.xml in an editor.
    2. Add the following permissions:

      <uses-permission android:name="android.permission.INTERNET" />
      <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
      <uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
      
    3. If you want to enable geolocation data, add the following permission:

      <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"
       />
      
    4. Save and close AndroidManifest.xml.
  2. Implement Android Auto Instrumentation.

     

    The Android SDK supports limited auto-instrumentation for new applications. The SDK uses the TeaCuts library module and AspectJ to support auto-instrumentation for the Activity, Application, and UI aspects. This simplifies the number of API calls that you must make in your application to instrument Acoustic Analytics for Mobile.

    TeaCuts library
    The TeaCuts library is part of the Android package. You add the library to the Inpath for your application with an AspectJ build. This weaves the Acoustic Experience Analytics (Tealeaf) library into your application and produces a final android APK that adds logging functions to your application.

    Configure the TeaCutsBasicConfig.properties file.

    • When enabled, auto instrumentation will try to set up OnClick event listener with OnGlobalLayoutListener.
      Note: Set the value to false if TextView based controls does not respond to click events due to an unexpected event listener timing issue.

    TextViewEnabled=true
    
    • When enabled, EditText control will be auto instrumented.

    EditTextEnabled=true
    
    • When Fragment lifecycle events are defined, layout/type 10 is auto instrumented.

    FragmentLifecycleEnabled=true
    
    • This setting is deprecated, needs to default to false on TealeafMod version >= 10.2.1.260 When below property is set to true, onResume/onPause lifecycles are auto instrumented.

    ActivityLifecycleEnabled=false
    

     

    Common use case scenarios for lifecycle events – onResume, onPause, onDestroy
    Use Case 1:

    If your app uses Activities only for screen content, use these settings

    ActivityLifecycleEnabled=false
    FragmentLifecycleEnabled=false
    

    Use Case 2:

    If your app uses Fragments only for screen content, use these settings

    FragmentLifecycleEnabled=true
    ActivityLifecycleEnabled=false
    

    Use Case 3:

    If your app needs to more precise timing of when to log screen layout, then use these settings and manual implementation

        1. FragmentLifecycleEnabled=false
          ActivityLifecycleEnabled=false
          
        2. The following code snippet shows manual logging for type 10 or screen. Place in your Fragment setup below lifecycle events.

          private String TAG = "MyLogicalPageName";
          public void onPause() {
          Tealeaf.onPause(this, TAG);
          super.onPause();
          }
          public void onResume() {
          Tealeaf.onResume(this, TAG);
          super.onResume();
          }
          public void onDestroy() {
          Tealeaf.onDestroy(this, TAG);
          super.onDestroy();
          }
          
        3. Call the following API in your code when the network data and UI screen is ready for logging.

    Tealeaf.logScreenLayout(this, "logicalPageName", 500);
    

    Supported aspects

    The TeaCuts library incorporates logging functions for:

    • Navigation logging (Type 10 screen layout)
    • UI event logging (Type 4 UI events)
    • Gestures (Type 11 UI event)

    Implement AAI into your application project

    Installing the Acoustic Experience Analytics (Tealeaf) Android SDK with Rakefile steps normally would install necessary Acoustic Experience Analytics (Tealeaf) artifacts into your application. However, in case of unexpected problems, you may complete the following steps to implement the auto instrumentation library into your application.

    Eclipse implementation

    Complete the following steps before you implement the auto instrumentation library into your Eclipse application.

    1. Install the Eclipse Mars or later IDE from https://eclipse.org/downloads/packages/release/Mars/R.
    2. Install and setup AspectJ in your Eclipse project. For more information, see https://eclipse.org.
    3. Enable JDT weaving in the Eclipse IDE. Select Eclipse > Preferences > JDT Weaving > Enable.

    Begin the implementation process for Eclipse:

    1. Copy and paste the following .jar files from the distribution folder to the libs folder for your project:
      AndroidRelease/Tealeaf/TealeafMod/eocore.jar
      AndroidRelease/Tealeaf/TealeafMod/tealeafmod.jar
      AndroidRelease/Tealeaf/TeaCuts/teacuts.jar
    2. Right-click on the project in the Package Explorer to bring up the context menu.
    3. Click Configure > Convert to AspectJ project.
    4. Add the runtime library by clicking Preferences > Java Build Path > Libraries.
    5. Add the Tealeaf AspectJ library called teacuts.jar to your project by clicking Eclipse > Preference > AspectJ Build > Add JARs.

     Android Studio implementation

    Before you begin implementing AAI into Android Studio, install the Android Studio IDE 1.4.1 or later IDE from https://developer.android.com/sdk/index.html.

    Begin the implementation process for Android Studio:

    1. Copy and paste the following jar files from the distribution folder to your moduleslibs folder:
      AndroidRelease/Tealeaf/TealeafMod/eocore.jar
      AndroidRelease/Tealeaf/TealeafMod/tealeafmod.jar
      AndroidRelease/Tealeaf/TeaCuts/teacuts.jar
    2. Install and setup the required Acoustic Experience Analytics (Tealeaf) libraries in the gradle file (build.gradle):
      1. Insert the following imports to the top of build.gradle:
        import org.aspectj.bridge.IMessage
        import org.aspectj.bridge.MessageHandler
        import org.aspectj.tools.ajc.Main
      2. Insert the following snippet into the dependencies section:

         dependencies {
        compile files('libs/eocore.jar')
        compile files('libs/tealeafmod.jar')
        compile files('libs/teacuts.jar')
        compile 'org.aspectj:aspectjrt:1.8.8'
        compile 'com.android.support:support-v4:xx.x.x'
        }
        

        Replace xx.x.x with the version number of the Android library instance.

      3. Insert the following snippet to use jars that are managed by Maven Central.

        buildscript {
         repositories {
         mavenCentral()
         }
         dependencies {
         classpath 'org.aspectj:aspectjtools:1.8.8'
         }
        }
        
      4. Insert the following snippet to the end of the file to enable weaving during AspectJ compiling.

        android.libraryVariants.all { variant >
        LibraryPlugin plugin =
         project.plugins.getPlugin(LibraryPlugin)
        JavaCompile javaCompile = variant.javaCompile
        javaCompile.doLast {
         String[] args = ["-showWeaveInfo",
         "-1.8",
         "-inpath",
         javaCompile.destinationDir.toString(),
         "-aspectpath", javaCompile.classpath.asPath,
         "-d", javaCompile.destinationDir.toString(),
         "-classpath", javaCompile.classpath.asPath,
         "-bootclasspath",
         plugin.project.android.bootClasspath.join(
         File.pathSeparator)]
         MessageHandler handler = new MessageHandler(true);
         new Main().run(args, handler)
        
         } 
         }
        

         

    Override lifecycle events in Application and Activity classes for AAI classes

    Extending and overriding standard classes to enable the AAI hook into the application and activity lifecycle events. If you want to trace events through AAI, you should use the following code samples to override the extended application and activity classes. Note: You can import a sample application from the distribution folder AndroidRelease/Tealeaf/SampleCode/DarkHoloAuto.

    Prerequisites:

    1. Copy and paste the following configuration files from the distribution folder to your project assets folder:
      AndroidRelease/Tealeaf/TealeafMod/TealeafBasicConfig.properties
      AndroidRelease/Tealeaf/TealeafMod/EOCoreBasicConfig.properties
      AndroidRelease/Tealeaf/TealeafMod/TealeafAdvancedConfig.json
      AndroidRelease/Tealeaf/TealeafMod/EOCoreAdvancedConfig.json
      AndroidRelease/Tealeaf/TeaCuts/TeaCutsAdvancedConfig.json
      AndroidRelease/Tealeaf/TeaCuts/TeaCutsBasicConfig.properties
    2. Make sure that DisableAutoInstrumentation is set to DisableAutoInstrumentation=false in TealeafBasicConfig.properties.
      Sample base Application class:

      public class MyApplication extends Application {
      @Override
      public void onCreate() {
      super.onCreate();
      // Enable Tealeaf library
      Tealeaf.enable(this)
      }
      

      Once the AAI integration steps are complete and the SDK library is enabled, the following logcat message is displayed when the app is launched in the emulator.

      LogCat output: "Auto Instrumentation is turned on successfully."
      

       

    Disable lifecycle events for activities and fragments during auto instrumentation

    If auto instrumentation is turned on with AspectJ, each lifecycle event methods such as onResume or onPause defined in source code are used as hooks to enable auto layout. To avoid duplicate API calls, you can disable the lifecycle events during auto instrumentation by editing TeaCutsBasicConfig.properties.

    By default, lifecycle events are enabled. To disable lifecycle events for activities and fragments, add the following snippet to TeaCutsBasicConfig.properties.

    ActivityLifecycleEnabled=false
    FragmentLifecycleEnabled=false
    

    Use the manual instrumentation steps to log screen views and screen layouts.

    Use the AutoLayout controller to enable type 10 screen logging for native mobile applications

    Screen logging for a native mobile application can be enabled by configuring the AutoLayout controller instead of adding custom code to enable screen logging in your application.

    The Acoustic Experience Analytics (Tealeaf) Android SDK can use the settings that are defined in TealeafLayoutConfig.json to log type 10 screen layouts for screenviews of native mobile application sessions. The AutoLayout controller also enables the application to automatically continue logging type 10 screen layouts when it resumes to the foreground. You can replay a mobile app session in cxImpact Browser Based Replay as you would an HTML web session instead of viewing the mobile app session as a series of screen captures.

    TealeafLayoutConfig.json is in the assets folder and is formatted as a JSON file.

    Edit TealeafLayoutConfig.json to configure Autolayout to log screen layouts.

     

    Sub entry Description
    ScreenChange

    This entry is replacing do in Tealeaf SDK 10.3.4 (and later).

     

    Boolean value

    Indicates if the screen should be tracked or not.

    • true¬†(Capture Type 2s for this screen): Tracks the screen.
    • false (Don’t Capture Type 2s for this screen): Does not track the screen.

     

    Example: To enable tracking for the screen: 

    "ScreenChange": true
    DisplayName

    This entry is replacing screenViewName in Tealeaf SDK 10.3.4 (and later).

     

    String value

    Provides the name of the screen to be shown during replay, instead of showing the view controller name or activity name. DisplayName is displayed during replay in the navigation list. If DisplayName is empty, view controller class name is used.

    For example, the DisplayName for a payments page might be “Payment Screen”.

    Example: To set the value of DisplayName to Payment Screen: 

    "DisplayName": "Payment Screen" 

     

    CaptureLayoutDelay

    This entry is replacing delay in Tealeaf SDK 10.3.4 (and later).

     

    Numeric value

    The delay in milliseconds before Tealeaf SDK takes a layout capture of a screen. Increasing the value of this setting increases the amount of time that must pass between when the layout is loaded and when the layout logging action occurs. The CaptureLayoutDelay value is used for ScreenChange and ScreenShot.

    Example: To set the delay between layout load and layout logging to 500 milliseconds:

    "CaptureLayoutDelay": 500
    ScreenShot

    This entry is replacing takeScreenShot in Tealeaf SDK 10.3.4 (and later). Note that takeScreenShot applied only for type 2 load events but ScreenShot applies to type 2, 4, 10, 11.

     

    Boolean value

    Indicates whether or not to capture screenshots on this screen.

    • true (Capture screenshots on type 2, 4, 10, 11): Takes a screen capture.
    • false (Don’t capture screenshots on this screen): Does not take a screen capture. If you do not want Tealeaf SDK to take any screenshots on a specific screen, set ScreenShot to false.

    Example: To turn on screen capturing for the screen activity:

    "ScreenShot": true

    Note: Android SDK per screen configuration is not supported in this release. Use IBMGlobalSettings to enable/disble screenshot.

    CaptureUserEvents

    This entry is replacing CaptureScreenContents in Tealeaf SDK 10.3.4 (and later).

    Boolean value

    Indicates whether or not to track user events like type 4s or 11s.

    • true (Capture type 4, 11): Tealeaf SDK resumes capturing user events (type 4, 11) on the specified screen.
    • false (Don’t capture type 4, 11): Tealeaf SDK pauses, does not capture type 4, 11 events, and based on the value of CaptureScreenVisits, captures screen load/unload events.

    Example:  To turn on user event capturing for the screen activity: 

    "CaptureUserEvents": true
    CaptureLayoutOn

    Numeric value

    The event to capture layout on. Never, or on first user gesture, or on screen change.

    • 2 (Capture Layout on screen change): Tealeaf SDK captures the layout as soon as the view controller is loaded.
    • 1 (Capture Layout on first user gesture): Tealeaf SDK captures the layout after the end user makes a first gesture on a given view controller.
    • 0 (Don’t Capture Layout): the layout is not captured.

    Example:  To capture layout on screen changes: 

    "CaptureLayoutOn": 2
    CaptureScreenshotOn

    Numeric value

    The event to capture screenshots for view controller load events: Never, or on first user gesture, or on screen changes. 

    • 2¬†(Capture screen load screenshot on screen change): Captures screen load screenshot on screen changes.¬† Tealeaf SDK captures the screenshot as soon as the view controller is loaded.
    • 1 (Capture screen load screenshot on first user gesture): Tealeaf SDK captures the screenshot after the end user makes a first gesture on a specified view controller.
    • 0 (Don’t capture screen load screenshot): Does not take a screen capture. Note that even if CaptureScreenshotOn is set to 0 and ScreenShot is true, the Tealeaf SDK continues to capture screenshots on other user events, such as type 4 and type 11. CaptureScreenshotOn applies only to screenshots on view controller load.

    Example: To capture screen load screenshot on screen changes: 

    "CaptureScreenshotOn": 2

    Note: Android SDK does not support this property in this release.

    CaptureWebViewScreenshotOn

    Numeric value

    The event to capture the first screenshot on for a web view, if there is any.

    • 2 (Capture webview screen load screenshot on screen change): Captures the webview screen load screenshot on screen changes.¬†
    • 1 (Capture webview screen load screenshot on first user gesture): Captures the webview screen load screenshot on the first user gesture.¬†
    • 0 (Don’t capture webview screen load screenshot): Does not capture the webview screen load screenshot.¬†

    Example: To capture webview screen load screenshot on screen changes: 

    "CaptureWebViewScreenshotOn": 2

     

    NumberOfWebViews

    This entry is replacing numberOfWebviews and isWebView in Tealeaf SDK 10.3.4 (and later). If you set isWebView = false in earlier releases, you can now set NumberOfWebViews = 0. Non-zero values for NumberOfWebViews indicate the number of web views on a view controller.

     

    Numeric value

    Indicates the amount of webviews on the page. Default value is 0.

    CaptureScreenVisits

    Boolean value

    Indicates whether you want type 2 objects on pages that you set CaptureUserEvents to false. This property helps you understand how your users are using your application by showing how they get to a page. Default value is true.

    If you do not want to track screen load/unload events, set this entry to false. CaptureScreenVisits applies only if CaptureUserEvents = false. If CaptureUserEvents = true, CaptureScreenVisits is ignored and load/unload events are tracked because it doesn’t make any sense to track user events on a screen where visits are not tracked.

    AppendMapIds

    JSON

    Assigns an identifier to a target item. You can assign a readable identifier to the mid that maps to the target item. You can then configure events to fire when the identifier is encountered. You can use the same identifier for Android devices as well as iOS devices. When you assign the same identifier to your Android and iOS devices, you can create a single event in Event Manager that fires on the identifier. The event fires for both Android and iOS devices.

    Example:

      "AppendMapIds": {
     "[PWDV,0][ABOL,0][FL,0][TH,0][LL,0][TW,0][LL,1][LL,0]": {
       "mid": "LoginButton"
       },
     "ibm.com.demoapp.main_activity_login:id\/send": {
       "mid": "LoginButton"
       }
    
    
    

    Uses the mid setting to assign an identifier to two targets. The first target is for an iOS device and the second target is for an Android device. The target for both devices is identified as LoginButton. You can create a single event that fires when LoginButton is encountered in either application.

     

    The following snippet shows an example of the TealeafLayoutConfig.json file.

    {
      "AutoLayout": {
          "IBMGlobalScreenSettings":{
              "ScreenChange": true,
              "DisplayName": "",
              "CaptureLayoutDelay": 0,
              "ScreenShot": false,
              "NumberOfWebViews": 0,
              "CaptureUserEvents": true,
              "CaptureScreenVisits": true,
              "CaptureLayoutOn": 2,
              "CaptureScreenshotOn": 0
          },
          "PaymentActivity":{
              "ScreenChange": false,
              "DisplayName": "The Payment Screen",
              "CaptureLayoutDelay": 0,
              "ScreenShot": false,
              "NumberOfWebViews": 0,
              "CaptureUserEvents": false,
              "CaptureScreenVisits": true,
              "CaptureLayoutOn": 0,
              "CaptureScreenshotOn": 0
          }
      },
      "AppendMapIds": {
          "[w,9290],[v,0]": {
              "mid": "ASimpleUIView"
          },
          "tag2999999": {
              "mid": "giveAdditionalId1"
          },
          "idxPathValue": {
              "mid": "giveAdditionalId2"
          }
      }
    }
    

     

     You can also manually configure a screen to log a layout by adding the following code snippet.

    Tealeaf.logScreenLayout(activity, "Name", delayInMS);
    
    
    

    Capture specific pages by pausing and resuming the library

    There are two ways of pausing and resuming the library:

    • Edit¬†TealeafLayoutConfig.json. This is the preferred method.
    • Call TealeafLayoutConfig.json.

    Edit TealeafLayoutConfig.json

    By default, if you are missing the IBMGlobalScreenSettings section, you have the following defaults, which capture all pages, events, and gestures, but no screenshots:

     

    "AutoLayout": {
    "IBMGlobalScreenSettings":{
              "ScreenChange": true,
              "DisplayName": "",
              "CaptureLayoutDelay": 0,
              "ScreenShot": false,
              "NumberOfWebViews": 0,
              "CaptureUserEvents": true,
              "CaptureScreenVisits": true,
              "CaptureLayoutOn": 2,
              "CaptureScreenshotOn": 0
          },
    },
    "AppendMapIds": {
      }
    
    /

    You use CaptureUserEvents to indicate that you want to pause the library and no longer capture information on a page. To pause the library, set CaptureUserEvents to false. To resume the library, set CaptureUserEvents to true. Remember that pausing the library pauses only capture of user events. If you do not want to capture screens at all, set ScreenChange to false. If you do not want to capture screen visits, set CaptureScreenVisits to false.

    For example, to capture all data except for user events on “FirstViewController”, which is the first page, enable the library to resume on “SecondViewController”, which is the second page.

    {
       "AutoLayout": {
    "IBMGlobalScreenSettings":{
            "ScreenChange": true,
             "DisplayName": "",
             "CaptureLayoutDelay": 0,
             "ScreenShot": false,
             "NumberOfWebViews": 0,
             "CaptureUserEvents": true,
             "CaptureScreenVisits": true,
             "CaptureLayoutOn": 2,
             "CaptureScreenshotOn": 0
           },
           "FirstViewController": {
            "ScreenChange": false,
             "DisplayName": "First Screen",
             "CaptureLayoutDelay": 0,
             "ScreenShot": false,
             "NumberOfWebViews": 0,
             "CaptureUserEvents": false,
             "CaptureScreenVisits": false,
             "CaptureLayoutOn": 0,
             "CaptureScreenshotOn": 0
           },
           "SecondViewController": {
            "ScreenChange": true,
             "DisplayName": "Second Screen",
             "CaptureLayoutDelay": 0,
             "ScreenShot": false,
             "NumberOfWebViews": 0,
             "CaptureUserEvents": true,
             "CaptureScreenVisits": true,
             "CaptureLayoutOn": 2,
             "CaptureScreenshotOn": 0
           }
       },
       "AppendMapIds": {
       }
    }
    
    
    

    Additionally, you can disable capture of all data except for specific pages, as shown in the following example.

    {
      "AutoLayout": {
    "IBMGlobalScreenSettings":{
           "ScreenChange": false,
            "DisplayName": "",
            "CaptureLayoutDelay": 0,
            "ScreenShot": false,
            "NumberOfWebViews": 0,
            "CaptureUserEvents": false,
            "CaptureScreenVisits": false,
            "CaptureLayoutOn": 0,
            "CaptureScreenshotOn": 0
          },
          "FirstViewController": {
           "ScreenChange": true,
            "DisplayName": "First Screen",
            "CaptureLayoutDelay": 0,
            "ScreenShot": false,
            "NumberOfWebViews": 0,
            "CaptureUserEvents": true,
            "CaptureScreenVisits": true,
            "CaptureLayoutOn": 2,
            "CaptureScreenshotOn": 0
          },
          "SecondViewController": {
           "ScreenChange": true,
            "DisplayName": "Second Screen",
            "CaptureLayoutDelay": 0,
            "ScreenShot": false,
            "NumberOfWebViews": 0,
            "CaptureUserEvents": true,
            "CaptureScreenVisits": true,
            "CaptureLayoutOn": 2,
            "CaptureScreenshotOn": 0
          }
      },
      "AppendMapIds": {
      }
    }
    
    
    

    For more information about configuring properties in TealeafLayoutConfig.json for pausing and resuming the library, see  Table 1. 

    Call TealeafLayoutConfig.json programmatically

    Use IBMGlobalScreenSettings to set values for all view controllers in TealeafLayoutConfig.json that are not documented.

    If you want to call TealeafLayoutConfig.json programmatically, go to the page where you want to start pausing the library on onStart and onResume, which is always called when an activity is displayed. 

     

       @Override
        protected void onResume() {
            Tealeaf.pauseTealeaf();
            super.onResume();
        }
    
        @Override
        protected void onStart() {
            Tealeaf.pauseTealeaf();
            super.onStart();
        }
    

    Next, go to the page where you want to start resuming the library on onPause, which is always called when an activity is displayed.

         @Override
        protected void onPause() {
            Tealeaf.resumeTealeaf(true);
            super.onPause();
        }
    

     

     

  3. Configure Tealeaf properties.

    You must configure several items for your app for use with Acoustic Analytics for Mobile , including:

    • how screen layouts are logged
    • target-page location
    • kill-switch location
    • whether to log gestures
    • Specific URLS for logging events
    • Message flow
    • Logging levels

    All of the configuration in this task involves modifying settings in the EOCoreBasicConfig.properties and TealeafBasicConfig.properties file in the Assets folder of your project.

    You can manually update configuration values by editing EOCoreBasicConfig.properties and TealeafBasicConfig.properties, or you can dynamically update the configuration values through an API. 

     

    The following table provides a list of properties that must be configured to work with your application:

    Required property  Description
     Whether to display logcat messages.  

    This setting is enabled or disabled with the DisplayLogging property in EOCoreBasicConfig.properties.

    • To display logcat messages, set DisplayLogging=true.
    • To disable logcat messages, set DisplayLogging=false. The logcat messages are disabled by default.
     Set the logging level  

    You can set the logging level based on where your project is in the development cycle. For example, you can set the level high for development and testing; then, lower the logging level for production. The logging level is set with the LoggingLevel property.

    The logging level can be set from 0 through 3, where:

    • 0 turns off logging.
    • 1 is the lowest logging level.LoggingLevel=1 is the default setting.
    • 3 is the highest logging level.

    A log level is given to each message that goes to the message queue. The value that is assigned to the log level determines importance of the logged message.

    The log level can be set from 0 to 3. Messages that are assigned a value of 0 are not logged. Messages that are assigned a value of 1 are logged as the most important message. Messages that are assigned a value of 3 are logged as the least important.

    Examples:

    • If a device is set to a log level of 2:
      – A message with 0 or 3 is not logged.
      – A message with 1 or 2 is logged.
    • If a device is set to a log level of 1:
      – A message with 0 is not logged.
      – A message with 1 is logged.
      – A message with 2 or 3 is not logged.

    The log level in the library is based on the network connection that the device is using.

    • If the device configured for WIFI and cellular data, then WIFI will assign log level.
    • If the device is configured for WIFI only, then WIFI will assign log level.
    • If the device is configured for cellular only, then cellular will assign log level.
    • If the device is configured for no network, then:
      – If you use the kill switch, the library does not start at all because it cannot establish a connection to the KillSwitch URL. The KillSwitch URL is used to enable or disable the kill switch.
      – If the kill switch is not used, the default log level is used.
     Enable and set kill switch  

    The kill switch is used to control logging. When the kill switch is enabled, it must have a URL to check before the framework initializes. When the page is reachable, the framework initializes. If the page is not reachable, because of network problems or because you disabled it on your server, the framework does not initialize. The kill switch URL is set by the person who sets up  Acoustic Experience Analytics (Tealeaf) on the server. The kill switch is enabled with theKillSwitchEnabled property. The kill switch URL is set with the KillSwitchUrl property in TealeafBasicConfig.properties.

    • To enable the kill switch:
      • Set KillSwitchEnabled=true.
      • Set KillSwitchUrl=<URL> to the URL for the kill switch for your application.
      • Note: When the URL returns 1, Acoustic Experience Analytics (Tealeaf) is enabled. When URL returns 0 or error, Acoustic Experience Analytics (Tealeaf) is disabled.
    • To disable the kill switch, set KillSwitchEnabled=false.
     Set target URL  All events that are captured are sent in JSON format to a target page. The target page acknowledges the receipt of the JSON message and forwards the client-side events to Acoustic Experience Analytics (Tealeaf). The person that sets up Tealeafon the server creates the target page. The target page is set with the PostMessageUrl property in TealeafBasicConfig.properties.
     Set how screen layouts are logged  

    Acoustic Experience Analytics (Tealeaf) can log screen images as Base64 or as MD5 checksum with PNG or JPG images.

    • To capture Base64 data, set GetImageDataOnScreenLayout=true in TealeafBasicConfig.properties.
    • To log MD5 checksum and PNG or JPG images, set GetImageDataOnScreenLayout=false in TealeafBasicConfig.properties.¬†
    • Note: Setting GetImageDataOnScreenLayout=false creates smaller payloads in production and is the recommended setting.
     Auto-instrumentation Android enables the use of one handler at a time for any object. As a result, auto-instrumentation is not supported in Acoustic Experience Analytics (Tealeaf). You must apply instrumentation as part of your application development.

    To manually customize your configuration, you can use a text editor to modify the values for each property in EOCoreBasicConfig.properties and TealeafBasicConfig.properties. Follow these steps:

    1. In your project, open the EOCoreBasicConfig.properties file.
    2. Set the LoggingLevel to an appropriate level for development, testing, or production.
    3. Open the TealeafBasicConfig.properties file.
    4. Set the DisplayLogging to false for production and to true for development.
    5. Set the PostMessageUrl to the URL of the target page for your app.
    6. Set the KillSwitchEnabled to true.
    7. Set the KillSwitchUrl to the URL for the kill switch for your app.
    8. Set the GetImageDataOnScreenLayout to false for production and to true for development.
    9. Set the LoggingLevel to an appropriate level for development, testing, or production.
    10. Save and exit the both files.

    To dynamically update configuration values through an API, use the following API call structure to update a configuration value:

    EOCore.updateConfig(final String key, final String value, 
    final EOLifecycleObjectName
     module)
    

    Examples:

    The following API call can be used to update a configuration value that is stored in EOCoreBasicConfig.properties:

    EOCore.updateConfig(‚Äúkey‚ÄĚ, ‚Äúvalue‚ÄĚ, EOCore.getInstance())
    

    Where key is the configuration property that you want to update and value is the value that you want to assigned to the configuration property.

    The following API call can be used to update an application configuration value that is stored in TealeafBasicConfig.properties:

    EOCore.updateConfig(‚Äúkey‚ÄĚ, ‚Äúvalue‚ÄĚ, 
    TealeafEOLifecy
    

    Where key is the configuration property that you want to update and value is the value that you want to assigned to the configuration property.

  4. Extend Android classes.

    You extend Android classes to provide logging for components in your application. You can extend the classes with the Acoustic Experience Analytics (Tealeaf) extended classes or you can manually change your files to integrate Acoustic Experience Analytics (Tealeaf) snippets into the library.

    Application class

    You extend the Activity class to automatically capture points the lifecycle of a native Android application page. Acoustic Experience Analytics (Tealeaf) listens to these events:

    • onLowMemory – disable the library when you get a LowMemory warning
    • onCreate – initialize the library when the application starts
    • onTerminate – clean up the library when the application is terminated

    How you extend the Application class depends on whether you have a custom activity class for your application. If you:

    • Do not have a custom Application class for your application, use the Acoustic Experience Analytics (Tealeaf) class UIApplication. NOTE: You do this only if you are not using the Eclipse plug-in. The plug-in automatically extends the Application class with the Acoustic Experience Analytics (Tealeaf) UICApplication class.
    • Have a custom Activity class for your application, modify your custom Application class to point to the Acoustic Experience Analytics (Tealeaf) UICApplication class.

     

    Application class and the Eclipse plug-in
    After you install the Eclipse plug-in, if you decide to use a custom Application class in your application, you need to change the Application class automatically added by the plug-in:

    1. Create the custom Application class.
    2. Modify AndroidManifest.xml file for the application and change the application class name to the name of Application class you created.

     

    Activity class

    You extend the Activity class to automatically capture points the lifecycle of a native Android application page. Acoustic Experience Analytics (Tealeaf) listens to these events:

    • onPause – what happens when the application goes to the background
    • onResume – what happens when the application goes to the foreground
    • onDestroy – what happens when the activity is no longer in memory and gets garbage collected

    How you extend the Activity class depends on whether you have a custom activity class for your application. If you:

    • Do not have a custom Activity class for your application, use the Acoustic Experience Analytics (Tealeaf) UIActivity class.
    • Have a custom Activity class for your application, modify your custom Activity class to point to the Acoustic Experience Analytics (Tealeaf) UICActivity class.

    Extending the Application class with the Acoustic Experience Analytics (Tealeaf) UICApplication class

    If you do not have a custom Application class, you can use theAcoustic Experience Analytics (Tealeaf) UICApplication class to extend the Application class. The application file manages the lifecycle of an Android application. Acoustic Experience Analytics (Tealeaf) manages the library by listening to onLowMemory to disable library if you get a warning, onTerminate to clean up library, and onCreate to initialize the library.

    Follow these steps:

    1. Open the existing Java file that extends from application class. If this file does not exist, you must create it and have it listen to the complete lifecycle of an Android application to control library and log information needed. You must also change the file to extend from com.tl.uic.app.UICApplication instead of android.app.Application.
    2. Add these imports:
      1. import com.tl.uic.Tealeaf;
      2. import com.tl.uic.app.UICApplication;
    3. In onCreate() method, add Tealeaf.enable() that initializes capture of user actions in the application.
    4. Adjust AndroidManifest.xml to indicate application class. For example, if your application class is named MyApplication, you can add ‚Ä®android:name=”.MyApplication” in <application> node.
    5. Add the following permissions in AndroidManifest.xml.

      <uses-permission android:name="android.permission.INTERNET" />
       <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
       <uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
       <uses-permission android:name="android.permission.READ_PHONE_STATE" />
      

      Example: This example shows the lines that you add to the AndroidManifest.xml file:

      import com.tl.uic.Tealeaf;
      import com.tl.uic.app.UICApplication;
      
      public class MyApplication extends UICApplication {
       @Override
       public void onCreate() {
       super.onCreate();
       Tealeaf.enable();
       }
      }
      

       

    Extending the Activity class with the Acoustic Experience Analytics (Tealeaf) UICActivity class

    The activity file manages the lifecycle of a page in a native Android application similar to what a page does in a web application. Acoustic Experience Analytics (Tealeaf) listens to the following events onPause, which happen when application goes to the background, onResume, which happens when application goes to foreground, and onDestroy when activity is no longer in memory and gets garbage collected.

    On each activity files that you want to log, extend it using UICActivity. Using UICActivity extends the base Activity from the Android framework. UICActivity adds some functionality that is required by the Acoustic Experience Analytics (Tealeaf) Logging Framework library to enable and disable asynchronous tasks, and to perform screen captures of the device after creation.

    To avoid capturing potentially private data, the Android SDK takes screen captures as soon as the image was rendered on the device. As a result, no user-defined fields are populated in any captured screen image.

    Android does not support capture of pop-up windows.

    The method in this task enables automatic capture of screen captures from the client application. If you do not enable this item through UICActivity, you can manually capture screen captures through the Logging Framework.

    The value for the black background color can be replaced by any color constant to set the color of the background of your screen captures.

    To extend the Activity class, follow these steps:

    1. Open the existing Java file that extends from android.app.Activity class, and change it to extend from com.tl.uic.app.UICActivity instead of android.app.Activity.
    2. Add these imports:
      Import com.tl.uic.Tealeaf;
      Import com.tl.uic.app.UICApplication;
    3. In the onCreate() method, add:
      Add this.setTakeSnapshotAfterCreate(true); //To enable automatic screen shots.
      Add setLogicalPageName(“LoginPage”) //Recommended to identify page.
      Add setImageBackground(-16777216) //To set to black background of screenshot because the screen capture background is transparent.

    Example: This example shows the lines that you add to the file that extends the Activity class:

    import com.tl.uic.app.UICActivity;
    public class LoginActivity extends UICActivity {
     @Override
     public void onCreate(Bundle savedInstanceState) {
     this.setTakeSnapshotAfterCreate(true); //To enable automatic screen shots
     setLogicalPageName("LoginPage") //Recommended to identify page
     setImageBackground(-16777216) //To set to back background of 
    screenshot
     super.onCreate(savedInstanceState);
    

    Extending your custom Application class

    If you have a custom Application class in your application, you are able to extend from it. You do not need to extend from the UICApplication class.

    The application file manages the lifecycle of an Android application. Acoustic Experience Analytics (Tealeaf) manages the library by listening to onLowMemory to disable the library if you get a warning, onTerminate to clean up library, and onCreate to initialize the library.

    When extending from the UICApplication class, there is no need to include lifecycle events as the UICApplication class already has it built in. If you are extending from an Application (or another custom class), the lifecycle events must be included.

    To extend your custom Application class, follow these steps:

    1. Open the existing Java file that extends from the android.app.Application class. If this file does not exist, you must create it and have it listen to the complete lifecycle of an Android application to control library and log information needed.
    2. Add this import:
      import com.tl.uic.Tealeaf;
      
    3. In onCreate():
      Add Tealeaf tealeaf = new Tealeaf(this);, which initializes the Acoustic Experience Analytics (Tealeaf) library with a reference to application instrumented.

      Add Tealeaf.enable(); that initializes capture of user actions in the application.

    4. In onLowMemory():
      Add Tealeaf.onLowMemory(); before super so it can adjust the library due to low memory.
    5. In onTerminate():
      Add Tealeaf.disable(); before super so it can disable the library.
    6. Adjust AndroidManifest.xml to indicate application class. For example, if your application class is named MyApplication, you can add ‚Ä®android:name=”.MyApplication” in <application> node.
    7. Add these permissions to AndroidManifest.xml.

      <uses-permission android:name="android.permission.INTERNET" />
       <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
       <uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
       <uses-permission android:name="android.permission.READ_PHONE_STATE" />
      

      Example: This example shows the lines you add to the file that extends the Application class:

      import android.app.Application;
      import com.tl.uic.Tealeaf;
      
      public class MyApplication extends Application {
      
       @Override
       public void onCreate() {
       super.onCreate();
       Tealeaf tealeaf = new Tealeaf(this);
       Tealeaf.enable();
      }
      
       @Override
       public void onLowMemory() {
       Tealeaf.onLowMemory();
       super.onLowMemory();
       }
      
       @Override
       public void onTerminate() {
       Tealeaf.disable();
       super.onTerminate();
       }
      }
      

       

  5. Enable screen logging in fragments.

    Acoustic Experience Analytics (Tealeaf) cannot automatically identify when a fragment is rendered. If your application uses fragments, place the following code into each fragment to enable screen logging for the fragment.

    /**
     * {@inheritDoc}
     */
     @Override
     public void onResume(){
     super.onResume();
     Tealeaf.onResumeFragment(getActivity(), "", this);
    }
    /**
     * {@inheritDoc}
     */
     @Override
     public void onPause(){
     super.onPause();
     Tealeaf.onPauseFragment(getActivity(), "", this);
    }
    

Expected outcome

The Acoustic Tealeaf SDK for Android is installed in your application. Next, implement the Acoustic Tealeaf SDK for Android functionality. For instructions, see Implementing the Acoustic Tealeaf SDK for Android.

Join The Discussion

Your email address will not be published. Required fields are marked *