Overview

Skill Level: Any

Step-by-step

  1. Replace step 2 in Getting started with the Tealeaf SDK in Android

    Replace step 2 in Getting started with the Tealeaf SDK in android with the following : 

     

    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 Customer Experience 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 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 Tealeaf Android SDK with Rakefile steps normally would install necessary 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 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 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.2.15 (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.2.15 (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.2.15 (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.2.15 (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
    CaptureUserEvents

    This entry is replacing CaptureScreenContents in Tealeaf SDK 10.2.15 (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
    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.2.15 (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();
        }
    

     

     

  2. Replace step 1 in Implementing the Android SDK

    replace step 1 in Implementing the Android SDK with the following:  

     

     

    Tealeaf has functions to log screen layouts for screenviews of native mobile app sessions. 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.

    The screen layouts of the native mobile app sessions are captured in Tealeaf JSON format. The screen layouts are then sent back to replay server. The replay server uses a template engine, which interprets the JSON into HTML format. You can then replay the screen layout from the native mobile app session as HTML pages in cxImpact Browser Based Replay.

    There are several advantages to using JSON data to replay mobile app session over screen captures.

    • Reduce bandwidth. Screen captures for each screenview generate relatively large image data. It not only consumes large amounts of wireless and cellular bandwidth, but it also consumes more memory inside the device. It also impacts the app performance.
    • Mask sensitive information. You cannot mask sensitive information in a screen capture. When you use JSON data to replay mobile app sessions, you can mask EditTexts by adding View IDs to the MaskIdList attribute in TealeafBasicConfig.properties.
    • Draw user interactions (UI events) onto the HTML pages that are created from the JSON data.

    TealeafBasicConfig.properties changes
    For native app session replay to be activated, you must set LogViewLayoutOnScreenTransition to true. If you do not, the library functions as it currently does.

    #Capture native layout
    LogViewLayoutOnScreenTransition=true
    
     

    During predeployment, you must perform all the replay cases to collect all the images with GetImageDataOnScreenLayout set to true. This creates a large payload sent to server that contains base64 images that are used for replay. When the application is ready to be deployed to Play Store, GetImageDataOnScreenLayout must be changed to false.

    #Current only done on ImageView
    GetImageDataOnScreenLayout=true 
    
     

    Understand your activity
    In Android, an Activity can be considered a page, which is displayed on mobile device. By default, you should record an activity that is displayed.

    For more information, see http://developer.android.com/training/basics/activity-lifecycle/starting.html.

    You can record an activity that is displayed, by placing the following information in the OnCreate method.

    // this will indicate logical page name.
    Tealeaf.logScreenview(activity, "Name", ScreenviewType.LOAD);
    // this will get layout of page after it being created.
    Tealeaf.logScreenLayoutOnCreate(activity, "Name");
    
    
    
    

    If you need to log a layout, you can enable the AutoLayout controller in your application which gives that ability to log a screen layout without making additional changes to your application code.

    The 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.2.15 (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.2.15 (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.4.1 (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.2.15 (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
    CaptureUserEvents

    This entry is replacing CaptureScreenContents in Tealeaf SDK 10.2.15 (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
    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.2.15 (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 dialog fragments 

    You can capture dialog fragments by using MyDialogFragment to extend DialogFragment.  

    // How to capture DialogFragment
    public class MyDialogFragment extends DialogFragment {
    
        public MyDialogFragment() {
            // Empty constructor is required for DialogFragment
            // Make sure not to add arguments to the constructor
            // Use `newInstance` instead as shown below
        }
    
        @NonNull
        @Override
        public Dialog onCreateDialog(Bundle savedInstanceState) {
            return super.onCreateDialog(savedInstanceState);
        }
    
        public static MyDialogFragment newInstance(String title) {
            MyDialogFragment frag = new MyDialogFragment();
            Bundle args = new Bundle();
            args.putString("title", title);
            frag.setArguments(args);
            return frag;
        }
    
        @Override
        public View onCreateView(LayoutInflater inflater, ViewGroup container,
                                 Bundle savedInstanceState) {
            return inflater.inflate(R.layout.fragment_dialog, container);
        }
    
        @Override
        public void onViewCreated(View view, @Nullable Bundle savedInstanceState) {
            super.onViewCreated(view, savedInstanceState);
    
            Activity activity = this.getActivity();
            while (activity != null && activity.getParent() != null) {
                activity = activity.getParent();
            }
    
            // Handles case where onShow method is being overridden
            final DialogLogScreenTask dialogLogScreenTask = new DialogLogScreenTask(activity, "", this.getDialog(), Tealeaf.getCurrentSessionId());
            dialogLogScreenTask.execute();
        }
    } 

    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. Replace table for TealeafLayoutConfig.json in Android Configuration file

    add to table for TealeafLayoutConfig.json in https://developer.ibm.com/customer-engagement/docs/watson-marketing/ibm-watson-customer-experience-analytics/ibm-watson-customer-experience-analytics-mobile-android-basic-edition/cxa_android_config/#TL%20Layout

     

    Sub-Entry Description Values
    ScreenChange

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

    Indicates if the screen should be tracked or not.

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

    Example: To enable tracking for the screen:

    "ScreenChange": true
    
    Boolean
    DisplayName

    This entry is replacing screenViewName in Tealeaf SDK 10.2.15.

    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" 
    
    String
    CaptureLayoutDelay

    This entry is replaying delay in Tealeaf SDK 10.2.15 (and later).

    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
    
    Numeric
    ScreenShot

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

    Indicates whether or not to capture screenshots on the 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
    
    Boolean
    CaptureUserEvents

    This entry is replaying CaptureScreenContents in Tealeaf SDK 10.2.15 (and later).

    Indicates whether or not to track user events like types 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
    Boolean
    CaptureLayoutOn

    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
    Numeric
    CaptureScreenshotOn

    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
    Numeric
    CaptureWebViewScreenshotOn

    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
    Numeric
    NumberOfWebViews

    This entry is replacing numberOfWebviews and isWebView in Tealeaf SDK 10.2.15  (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.

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

    Numeric

    AppendMapIds

    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.

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

    JSON

    The following snippet is an example of a 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"
          }
      }
    }
    

Join The Discussion

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