Skill Level: Intermediate
You add the 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.

To get started, you need:

• The Experience Analytics (Tealeaf) package.
• The Experience Analytics (Tealeaf) sample application. You deploy the sample application that is provided byExperience 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 DANALYTICSMOBILE-MED.
• To understand and meet the Android development environment requirements.
• To understand 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

• Minimal effect on battery life
  For more information, see the [Experience Analytics (Tealeaf) SDK for Android overview page}(https://developer.goacoustic.com/acoustic-exp-analytics/docs/acoustic-experience-analytics-tealeaf-sdk-for-android-standard-and-mobile-editions).

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

After you acquire 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.

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.

DANALYTICSMOBILE-MED (on-premises):

DANALYTICSMOBILE-MED (on Cloud):

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 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 Experience Analytics (Tealeaf) SDK files into your Android project by copying the following Experience Analytics (Tealeaf) SDK files to the specified folder for your Android project.

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

   a. Open AndroidManifest.xml in an editor.

   b. Add the following permissions:

c. If you want to enable geolocation data, add the following permission:

d. 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 DANALYTICSMOBILE-MED.

TeaCuts library

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

Supported configuration:
AspectJ plugin 4.2.1
Android Gradle Plugin 4.0.0
Gradle 6.1.1

Note: AspectJ plugin version 4.3.0 is not supported.

Configure the TeaCutsBasicConfig.properties file.

• When enabled, auto instrumentation will try to set up OnClick event listener with OnGlobalLayoutListener.
  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:

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.

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

Android Studio implementation

Before you begin implementing AAI into Android Studio, install the Android Studio IDE 1.4.1 or later IDE.

Begin the implementation process for Android Studio:

1. Copy and paste the following jar files from the distribution folder to your module's libs folder:
   AndroidRelease/Tealeaf/TealeafMod/eocore.jar
AndroidRelease/Tealeaf/TealeafMod/tealeafmod.jar
AndroidRelease/Tealeaf/TeaCuts/teacuts.jar

2. Install and setup the required Experience Analytics (Tealeaf) libraries in the gradle file (build.gradle):

3. Insert the following snippet into the dependencies section:

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

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

6. Insert the following snippet to the end of the file to enable weaving during AspectJ compiling.

Overide 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:

3. 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."

4. In order to instrument gesture events, the following hook is required by the AspectJ auto instrumentation library.

   public boolean dispatchTouchEvent(MotionEvent e) {
            return super.dispatchTouchEvent(e);
        }
   

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.

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

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:

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.

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

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.

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

3. Configure Tealeaf properties

You must configure several items for your app for use with DANALYTICSMOBILE-MED, 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:

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 update configuration values dynamically 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 Experience Analytics (Tealeaf) extended classes or you can manually change your files to integrate 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. 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 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 Experience Analytics (Tealeaf) UICApplication class.

• Have a custom Activity class for your application, modify your custom Application class to point to the 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. 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 Experience Analytics (Tealeaf) UIActivity class.
• Have a custom Activity class for your application, modify your custom Activity class to point to the Experience Analytics (Tealeaf) UICActivity class.

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

If you do not have a custom Application class, you can use the Experience Analytics (Tealeaf) UICApplication class to extend the Application class. The application file manages the lifecycle of an Android application. Experience Analytics (Tealeaf) manages the library by listening to on LowMemory 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:

   • import com.tl.uic.Tealeaf;
   • 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.

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

Extending the Activity class with the 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. 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 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:

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. 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: i**mport** com.tl.uic.Tealeaf;

3. In onCreate():
   Add Tealeaf tealeaf = new Tealeaf(this);, which initializes the 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.

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

5. Enable screen logging in fragments

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.

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