Download IBM Tealeaf Android SDK Guide - IBM ExperienceOne Documentation

IBM Tealeaf
Version 10 Release 2.1.54
November 2016
Android SDK Guide
IBM
Note
Before using this information and the product it supports, read the information in “Notices” on page 175.
This edition applies to version 10, release 2.1, modification 54 of IBM Tealeaf Android SDK with EOCore 2.0.0.59,
TeaCuts 2.0.0.15, and to all subsequent releases and modifications until otherwise indicated in new editions.
© Copyright IBM Corporation 1999, 2016.
US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract
with IBM Corp.
Contents
IBM Tealeaf Android SDK Guide . . . . v
Internal settings: do not change .
Chapter 1. Tealeaf installation and
implementation in an Android
application . . . . . . . . . . . . . 1
Chapter 3. Application images and
replay. . . . . . . . . . . . . . . 103
Client Framework versions supported in this
documentation. . . . . . . . . . . . . . 2
Install the Tealeaf SDK for Android development in
your application . . . . . . . . . . . . . 2
Tealeaf package contents . . . . . . . . . 2
Tealeaf sample application . . . . . . . . . 3
Android development environment requirements 3
Tealeaf impact on Android device resources . . . 4
Installing the IBM Tealeaf Android SDK with
Rakefile . . . . . . . . . . . . . . . 4
Android Auto Instrumentation (AAI) . . . . . 5
Installing IBM Tealeaf Android SDK manually. . 12
How log levels work . . . . . . . . . . 13
Configure Tealeaf properties . . . . . . . . 14
Extended Android classes . . . . . . . . 16
Enabling screen logging in fragments . . . . . 21
Implement Tealeaf . . . . . . . . . . . 21
Install the Eclipse Tealeaf plug-in for Android
development in your application . . . . . . . 54
Tealeaf package contents . . . . . . . . . 55
Android development environment requirements 56
Tealeaf impact on Android device resources . . 57
Add Eclipse Tealeaf plug-in to your Eclipse
Android project . . . . . . . . . . . . 57
Configure Tealeaf properties . . . . . . . . 59
Extended Android classes . . . . . . . . 62
Implement Tealeaf . . . . . . . . . . . 67
Quick start for server configuration . . . . . . 89
Target page for traffic capture . . . . . . . 89
Traffic volume management . . . . . . . . 89
CX Passive Capture Application traffic capture
verification . . . . . . . . . . . . . 90
Options for monitoring captures and processing 91
Configuring sessionization for Android
applications in IBM Tealeaf . . . . . . . . 92
Runtime configuration. . . . . . . . . . 95
IBM Tealeaf events for Android SDK . . . . . . 95
Upgrading the Android SDK . . . . . . . . 95
Chapter 2. Configuration file . . . . . 97
Application key . . . .
Log level settings . . .
Kill switch settings . . .
Local cache file settings .
Post settings . . . . .
Masking settings . . .
Filter message type setting
Cookie settings . . . .
Session timeout setting .
Screen shot settings . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
© Copyright IBM Corp. 1999, 2016
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 97
. 97
. 98
. 98
. 99
. 100
. 100
. 100
. 101
. 101
.
.
.
Target Simulator . . . . . . . . .
Collecting images from your application
the Target Simulator . . . . . . .
Android Image Capture Tool . . . . .
Collecting images from your application
the Android Image Capture Tool . . .
.
.
. .
with
. .
. .
with
. .
. 101
. 104
. 105
. 106
. 107
Chapter 4. Sample applications. . . . 109
Chapter 5. Guidelines . . . . . . . . 111
Chapter 6. Reference . . . . . . . . 113
UICActivity class . . . .
UICApplication class . . .
Tealeaf class . . . . . .
UICWebView class . . .
UICWebChromeClient Class
UICWebViewClient Class .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
113
115
116
126
128
129
Chapter 7. Sample Code. . . . . . . 131
How to instrument TextView based controls . .
How to instrument ExpandableListView based
controls . . . . . . . . . . . . . .
How to instrument SlidingDrawer based controls
How to mask controls . . . . . . . . .
How to implement AdvertisingId in your
application to capture Google Advertising ID
(GAID) data . . . . . . . . . . . . .
Server-Side KillSwitch Sampling Function . . .
Sampling function examples for ASPX . . .
Sampling Function for JSP . . . . . . .
Sampling Function for PHP . . . . . .
JSON message type schemas and examples . .
Message header properties . . . . . . .
Message header properties schema . . . .
Client state (Type 1) messages . . . . . .
ScreenView (Type 2) messages . . . . . .
Connections (Type 3) messages . . . . .
Control (Type 4) messages . . . . . . .
Custom Event (Type 5) messages . . . . .
Exception (Type 6) messages . . . . . .
Performance (Type 7) messages . . . . .
Web Storage (Type 8) messages . . . . .
Overstat Hover Event (Type 9) messages . .
Layout (Type 10) messages . . . . . . .
Gesture (Type 11) messages. . . . . . .
DOM Capture (Type 12) messages . . . .
GeoLocation (Type 13) messages . . . . .
Cookie (Type 14) message schema . . . .
. 131
. 131
132
. 132
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
132
133
133
134
136
137
138
138
139
141
143
144
147
148
149
150
151
151
154
163
168
168
iii
Chapter 8. Troubleshooting . . . . . 171
Troubleshooting and debugging - enabling raw
request and response headers . . . . . . .
Troubleshooting - managing client-side issues .
. 171
. 171
Chapter 9. IBM Tealeaf documentation
and help . . . . . . . . . . . . . 173
Notices . . . . . . . . . . . . . . 175
Trademarks .
iv
.
.
.
.
.
.
.
.
.
.
.
.
. 176
IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide
Privacy Policy Considerations .
.
.
.
.
.
.
. 177
IBM Tealeaf Android SDK Guide
The IBM Tealeaf Android SDK for mobile native applications requires the IBM
Tealeaf CX Mobile license for Mobile App.
For more information, contact your IBM Tealeaf representative. Licensees must
implement in their apps code that is provided by IBM Tealeaf. For more
information on downloading IBM Tealeaf, see IBM® Passport Advantage® Online.
The IBM Tealeaf Android SDK Guide provides guidance on how to enable the
capture of mobile application data directly from the application that is installed on
the visitor's Android-enabled device.
Note: Whenever possible, use the latest version of the IBM Tealeaf Android SDK
software.
© Copyright IBM Corp. 1999, 2016
v
vi
IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide
Chapter 1. Tealeaf installation and implementation in an
Android application
You add the Tealeaf® SDK to your application so that the Android SDK can capture
user interface and application events. There are two ways to install the Tealeaf
SDK in your Android application.
Supported Frameworks
The installation and implementation instructions in this guide apply to the
step-based version of JSON messaging from this client framework.
The step-based version of JSON messaging from this client framework was
introduced in Release 8.5.
For Release 8.5 and later, IBM Tealeaf continues to support the legacy method of
submitting data from the client frameworks, which resulted in submitted data
being split into individual hits in the Windows pipeline.
In a future release, the hit-splitting method of processing data that is submitted
from client frameworks is likely to be deprecated.
The installation and implementation instructions for the legacy version are similar
but require additional configuration in the Windows pipeline.
Eclipse Tealeaf plug-in for Android development
Note: The Android SDK is no longer supported with Eclipse. Android Studio
should be used to integrate the Android SDK with your mobile application. The
following references to integrating the Android SDK using Eclipse should only be
used as a reference.
The Eclipse Tealeaf plug-in installs the Tealeaf SDK into your Eclipse workspace
and includes basic configuration. You download the plug-in and install the plug-in
with the Eclipse Install new software option. The plug-in installs custom widgets
in your Eclipse workspace. These widgets can be used in any application in that
workspace.
If you do not have a custom Application class in your application, the plug-in
creates and extends one for you. If you create a custom Application class after you
install the plug-in, you:
1. Create and extend your custom Application class
2. Modify AndroidManifest.xml file to use your custom Application class
You manually configure properties, including application-specific URLs, and
Android Activity class extension.
Tealeaf SDK for Android development
You manually install and configure the Tealeaf SDK. You download the Tealeaf
package and you:
1. Move files to the proper locations in your application
© Copyright IBM Corp. 1999, 2016
1
2. Configure properties, including application-specific URLs
3. Extend Application and Activity classes
Client Framework versions supported in this documentation
The installation and implementation instructions in this guide apply to the
step-based version of JSON messaging from this client framework.
The step-based version of JSON messaging from this client framework was
introduced in Release 8.5.
For Release 8.5 and later, IBM Tealeaf continues to support the legacy method of
submitting data from the client frameworks, which resulted in submitted data
being split into individual hits in the Windows pipeline.
Note: In a future release, the hit-splitting method of processing data that is
submitted from client frameworks is likely to be deprecated.
The installation and implementation instructions for the legacy version are similar
but require additional configuration in the Windows pipeline.
Install the Tealeaf SDK for Android development in your application
You add the Tealeaf SDK to your application so that the Android SDK can capture
user interface and application events. You manually install and configure the
Tealeaf SDK in each application .
Tealeaf SDK for Android development
You manually install and configure the Tealeaf SDK. You download the Tealeaf
installation package and you:
1. Move files to the proper locations in your application
2. Configure properties, including application-specific URLs
3. Extend Application and Activity classes
If you are upgrading from a previous version of the SDK, see “Upgrading the
Android SDK” on page 95.
Tealeaf package contents
A single file contains the Android SDK and its software components.
IBM Tealeaf Android SDK is delivered in the IBM Tealeaf Android SDK - iOS
Logging Framework for Windows within the IBM Passport Advantage Online.
The package contains the following software components.
v KillSwitch. Code to implement the kill switch traffic manager for different
server technologies.
– ASPX:
- killswitch.aspx: Page with logic.
- web.config: Configuration file that is used by the page.
– JSP:
- killswitch.jsp: Page with logic.
- config.properties: Configuration file that is used by the page.
2
IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide
– PHP
- killswitch.php: Page with logic.
- config.ini: Configuration file that is used by the page.
v Tealeaf Mod:
– eocore.jar: Android Core library JAR file used by module system.
– tealeafmod.jar: Android library JAR file that contains the CX Mobile
Android SDK.
– EOCoreBasicConfig.properties: Configuration file.
– TealeafBasicConfig.properties: Configuration file.
– EOCoreAdvancedConfig.json: Configuration file.
– TealeafAdvancedConfig.json: Configuration file.
v SampleCode: Contains the following versions of a sample Android application.
– DarkHoloAuto: An Android application with IBM Tealeaf CX Mobile Android
SDK integrated and auto-instrumentation.
– DarkHoloManual: An Android application with IBM Tealeaf CX Mobile
Android SDK integrated which requires manual instrumentation.
– HybridHTMLEmbedded: An Android application with IBM Tealeaf CX Mobile
Android SDK integrated with a hybrid application.
See "Sample Code" in the IBM Tealeaf Android SDK Guide.
v AndroidEclipsePlugin: An Eclipse plug-in to assist with Tealeaf integration.
– tealeaf.plugin.android.site-1.0.0-SNAPSHOT.zip: The plug-in archive to be
added to your Eclipse IDE.
– tealeafandroidsdk.jar: Android library JAR file that contains
pre-instrumented Tealeaf widgets.
v TealeafTargetSimulator
– target_sim.js: Image extractor from posts in real time.
v AndroidImageCaptureTool
– Rakefile.rb: Image extractor and tagger for replay.
v TeaCuts
– teacuts.jar: Automation library.
– TeaCutsBasicConfig.properties: Configuration file that stores basic
configuration settings to assist with auto instrumentation.
– TeaCutsAdvancedConfig.json: Configuration file that stores advanced library
settings to assist with auto instrumentation.
Tealeaf sample application
You deploy the sample application that is provided by IBM 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 IBM Tealeaf.
See Chapter 4, “Sample applications,” on page 109.
Android development environment requirements
To develop Android applications with the Android SDK, follow these system and
software requirements.
Chapter 1. Tealeaf installation and implementation in an Android application
3
Minimum requirements
Develop Android applications with a minimum Android 4.1 or later.
Consult the Google Android Dev Center for the latest Android technical
documentation and tools.
IBM Tealeaf client frameworks do not support forwarding of application data to
third-party systems. Application data must be forwarded to the server that hosts
the native application.
Supported operating systems
Tealeaf supports these versions of the Windows, Mac, and Linux operating
systems:
v Windows XP (32-bit), Vista (32- or 64-bit), or Windows 7 (32- or 64-bit)
v Mac OS X 10.5.8 or later (x86 only)
v Linux (tested on Ubuntu Linux, Lucid Lynx)
– GNU C Library (glibc) 2.7 or later is required.
– On Ubuntu Linux, version 8.04 or later is required.
– 64-bit distributions must be able to run 32-bit applications. For information
about how to add support for 32-bit applications, see the Ubuntu Linux
installation notes.
Android Studio
Tealeaf supports the latest version of Android Studio.
Android Framework API
Tealeaf requires Android Framework API level 23 or higher.
Tealeaf impact on Android device resources
In benchmark tests, the Android SDK has the following effects on resources of the
visitor's device.
v 2-3% more memory consumption
Note: If the Tealeaf server is unreachable, the SDK saves Tealeaf data to memory
until the Tealeaf 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.
v Minimal effect on battery life
Installing the IBM Tealeaf Android SDK with Rakefile
You can use Rakefile to install the IBM Tealeaf Android SDK into an Android
application as a package.
Using Rakefile to install the SDK eases the installation and integration process by
automatically performing most integration steps that would otherwise be
performed manually.
4
IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide
The following items must already be installed before you can use Rakefile to install
the Android SDK:
v Ruby v1.9.3
v Ruby gems
For more information on these requirements, see https://www.ruby-lang.org/en/
documentation/installation/ and https://rubygems.org/pages/download.
IBM Tealeaf (on-premises): From a command line, use the following Rakefile
command to complete a new SDK integration with Android Studio for an IBM
Tealeaf on-premises installation.
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"
Tealeaf Customer Experience on Cloud: From a command line, use the following
Rakefile command to complete a new SDK integration with Android Studio for an
Tealeaf Customer Experience on Cloud installation.
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"
appKey="111111111111111111111"
Where:
v modulePath: Defines the path where Android Studio module is located.
Note: In the example, replace <username> with the active user name.
v 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.
v killSwitchUrl: Points to the URL of the kill switch.
Note: In the example, replace <target_URL> with the URL for the kill switch.
v appKey: Defines the application key value for Tealeaf Customer Experience on
Cloud.
Android Auto Instrumentation (AAI)
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 Tealeaf.
By implementing the library, the application developer does not need to add
additional code to troubleshoot errors that are related to:
TeaCuts library
The TeaCuts library is part of the Tealeaf 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.
Chapter 1. Tealeaf installation and implementation in an Android application
5
Supported aspects
The TeaCuts library incorporates logging functions for:
v Navigation logging (Type 10 screen layout)
v UI event logging (Type 4 UI events)
Implementing Auto Instrumentation into your application project
Complete the following steps before you 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:
v AndroidRelease/Tealeaf/TealeafMod/eocore.jar
v AndroidRelease/Tealeaf/TealeafMod/tealeafmod.jar
v 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:
v AndroidRelease/Tealeaf/TealeafMod/eocore.jar
v AndroidRelease/Tealeaf/TealeafMod/tealeafmod.jar
v AndroidRelease/Tealeaf/TeaCuts/teacuts.jar
2. Install and setup the required Tealeaf libraries in the gradle file (build.gradle):
a. Insert the following imports to the top of build.gradle:
v import org.aspectj.bridge.IMessage
v import org.aspectj.bridge.MessageHandler
v import org.aspectj.tools.ajc.Main
b. Insert the following snippet into the dependencies section:
6
IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide
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.
c. Insert the following snippet to use jars that are managed by Maven Central.
buildscript {
repositories {
mavenCentral()
}
dependencies {
classpath ’org.aspectj:aspectjtools:1.8.8’
}
}
d. 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.5",
"-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)
def log = project.logger
for (IMessage message : handler.getMessages(null, true)) {
switch (message.getKind()) {
case IMessage.ABORT:
case IMessage.ERROR:
case IMessage.FAIL:
log.error message.message,message.thrown
break;
case IMessage.WARNING:
case IMessage.INFO:
log.info message.message, message.thrown
break;
case IMessage.DEBUG:
log.debug message.message, message.thrown
break;
}
}
}
}
Overriding standard classes with Tealeaf AAI classes
Extending and overriding standard classes to enable the Tealeaf AAI hook into the
application and activity lifecycle events. If you want to trace events through
Tealeaf 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:
v AndroidRelease/Tealeaf/TealeafMod/TealeafBasicConfig.properties
Chapter 1. Tealeaf installation and implementation in an Android application
7
v AndroidRelease/Tealeaf/TealeafMod/EOCoreBasicConfig.properties
v AndroidRelease/Tealeaf/TealeafMod/TealeafAdvancedConfig.json
v AndroidRelease/Tealeaf/TealeafMod/EOCoreAdvancedConfig.json
v AndroidRelease/Tealeaf/TeaCuts/TeaCutsAdvancedConfig.json
v 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)
}
@Override
public void onLowMemory() {
super.onLowMemory();
}
@Override
public void onTerminate() {
super.onTerminate();
}
}
Sample base Activity class
public class BaseActivity extends Activity {
private String logicalPageName;
/**
* Logical page name of the Activity.
*
* @return Logical page name of the Activity.
*/
public final String getLogicalPageName() {
if ((this.logicalPageName == null) || (this.logicalPageName.equals(""))) {
this.logicalPageName = BaseActivity.class.getSimpleName();
}
return this.logicalPageName;
}
/**
* Logical page name of the Activity.
*
* @param logicalPageName
* Logical page name of the Activity.
*/
public final void setLogicalPageName(final String logicalPageName) {
this.logicalPageName = logicalPageName;
}
/**
* {@inheritDoc}
*/
public void onPause() {
super.onPause();
}
/**
* {@inheritDoc}
*/
public void onResume() {
super.onResume();
}
/**
* {@inheritDoc}
8
IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide
*/
public void onDestroy() {
super.onDestroy();
}
}
Once the Tealeaf 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."
Disabling 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.
The following example shows two activity classes which override the lifecycle
events.
// Base Activity
public class BaseActivity extends Activity {
public void onPause() {
super.onPause();
}
public void onResume() {
super.onResume();
// Business logic
}
public void onDestroy() {
super.onDestroy();
// Business logic
}
}
// ControlsActivity1
public class ControlsActivity1 extends BaseActivity {
public void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.controls1);
}
public void onPause() {
super.onPause();
}
public void onResume() {
super.onResume();
}
Chapter 1. Tealeaf installation and implementation in an Android application
9
public void onDestroy() {
super.onDestroy();
}
}
Using 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 IBM 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.
Each AutoLayout entry has the following sub entries:
Table 1. AutoLayout sub entries.
Sub entry
Description
do
Boolean value
Indicates if the screen should be logged or not.
v true: Logs the screen.
v false: Does not log the screen.
Eaxmple: "do": true enables logging for the screen.
screenViewName
String value
Used to provide a custom identifying name that is assigned to the
logged screen in JSON. For example, the screenViewName for a
login screen might be "LoginScreen".
Example: screenViewName": "LoginScreen" sets the value of
screenViewName to LoginScreen.
delay
Numeric value
The amount of time, in milliseconds, that is used to delay the
screen logging action. Increasing the value of this setting increases
the amount of time that must pass between when the screen is
loaded and when the screen logging action occurs. The delay value
is used for do and takeScreenShot.
Example: "delay": 500 sets the delay between screen load and
screen logging to 500 milliseconds.
10
IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide
Table 1. AutoLayout sub entries. (continued)
Sub entry
Description
takeScreenShot
Boolean
Indicates if a screen capture should be taken for the controller
class.
v true: Performs a screen capture.
v false: Does not perform a screen capture.
Example: "takeScreenShot": true turns on screen capturing for
the screen activity.
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": {
"UICAndroidControlsAppActivity": {
"do": false,
"screenViewName": "UICAndroidControlsAppActivity",
"delay": 1,
"takeScreenShot": false
},
"ControlsActivity1": {
"do": true,
"screenViewName": "CA1",
"delay": 500,
"takeScreenShot": false
},
"ControlsActivity2": {
"do": true,
"screenViewName": "CA2",
"delay": 1,
"takeScreenShot": false
},
"ControlsActivity3": {
"do": true,
"screenViewName": "CA3",
"delay": 1,
Chapter 1. Tealeaf installation and implementation in an Android application
11
"takeScreenShot": false
},
"ControlsActivity4": {
"do": true,
"screenViewName": "CA4",
"delay": 1,
"takeScreenShot": false
},
"ControlsActivity5": {
"do": true,
"screenViewName": "CA5",
"delay": 1,
"takeScreenShot": false
},
"ControlsActivity6": {
"do": true,
"screenViewName": "CA6",
"delay": 1,
"takeScreenShot": false
},
"ControlsActivity7": {
"do": true,
"screenViewName": "CA7",
"delay": 1,
"takeScreenShot": false
},
"ControlsActivity8": {
"do": true,
"screenViewName": "CA8",
"delay": 1,
"takeScreenShot": false
}
},
"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"
}
}
}
},
Installing IBM Tealeaf Android SDK manually
After you acquire IBM Tealeaf Android SDK, you can install the SDK as a package
using Rakefile or you can manually install the SDK into your application project.
Complete the following steps to manually install the Android SDK libraries into an
Android application project. Your Eclipse project must include the frameworks that
follow.
Install the EOCore.jar and TealeafMod.jar
Install EOcore.jar and TealeafMod.jar in to 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.
Integrate Tealeaf SDK files into your Android project
Integrate the SDK files into your Android project by copying the following Tealeaf
SDK files to the specified folder for your Android project.
12
IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide
Table 2. SDK integration files
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.
dependencies {
compile ’com.android.support:appcompat-v7:xx.x.x’
compile files(’libs/eocore.jar’)
compile files(’libs/tealeafmod.jar’)}
Replace xx.x.x with the version number of the Android library instance.
Register the Tealeaf SDK in AndroidManifest.xml
After you have integrated the Tealeaf SDK files with your Android project, use the
following procedure to register the Tealeaf SDK files in AndroidManifest.xml.
1. Open AndroidManifest.xml in an editor.
2. Add the following permissions:
<uses-permission
<uses-permission
<uses-permission
<uses-permission
android:name="android.permission.INTERNET" />
android:name="android.permission.ACCESS_NETWORK_STATE" />
android:name="android.permission.ACCESS_WIFI_STATE" />
android:name="android.permission.READ_PHONE_STATE"/>
3. If you want to enable geolocation data, add the following permission:
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"
/>
4. If you want to enable debugging, add the following permission:
<uses-permission android:name="android.permission.SET_DEBUG_APP" />
5. Save and close AndroidManifest.xml.
How log levels work
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:
v 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.
v If a device is set to a log level of 1:
Chapter 1. Tealeaf installation and implementation in an Android application
13
– 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.
v If the device configured for WIFI and cellular data, then WIFI will assign log
level.
v If the device is configured for WIFI only, then WIFI will assign log level.
v If the device is configured for cellular only, then cellular will assign log level.
v 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.
Configure Tealeaf properties
You must configure several items for your app for use with Tealeaf, including how
screen layouts are logged, target-page location, kill-switch location, and whether to
log gestures.
EOCoreBasicConfig.properties and TealeafBasicConfig.properties are located in
the Assets folder and contain configuration settings. To customize your
configuration, you can use a text editor to modify the values for each property in
EOCoreBasicConfig.properties and TealeafBasicConfig.properties.
Note: The following table provides a list of Tealeaf properties that must be
configured to work with your application:
Table 3. Tealeaf properties that must be configured.
Required Tealeaf property
Description
Whether to display logcat messages.
This setting is enabled or disabled with the
DisplayLogging property in
EOCoreBasicConfig.properties.
v To display logcat messages, set
DisplayLogging=true.
v 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:
v 0 turns off logging.
v 1 is the lowest logging level.
LoggingLevel=1 is the default setting.
v 3 is the highest logging level.
14
IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide
Table 3. Tealeaf properties that must be configured. (continued)
Required Tealeaf property
Description
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
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.
v To enable the kill switch:
1. Set KillSwitchEnabled=true.
2. Set KillSwitchUrl=<URL> to the URL
for the kill switch for your application.
v 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 Tealeaf. The person that sets up Tealeaf
on the server creates the target page. The
target page is set with the PostMessageUrl
property in TealeafBasicConfig.properties.
Set how screen layouts are logged
Tealeaf can log screen images as Base64 or
as MD5 checksum with PNG or JPG images.
v To capture Base64 data, set
GetImageDataOnScreenLayout=true in
TealeafBasicConfig.properties.
v 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
Tealeaf. You must apply instrumentation as
part of your application development.
Configuring Tealeaf properties for your application
You configure Tealeaf to use specific URLS for logging events and to control
message flow, set how screen layouts are logged, modify logging levels.
Chapter 1. Tealeaf installation and implementation in an Android application
15
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.
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.
Extended Android classes
You extend Android classes to provide logging for components in your application.
You can extend the classes with the IBM Tealeaf extended classes or you can
manually change your files to integrate Tealeaf snippets into the library. If you
install the Tealeaf SDK, you must extend the Application and Activity classes.
When you install the Eclipse Tealeaf plug-in, you must extend only the Activity
class. How you extend the classes depends on whether you have custom
Application or Activity classes.
Application class
You extend the Activity class to automatically capture points the lifecycle of a
native Android application page. Tealeaf listens to these events:
v onLowMemory - disable the library when you get a LowMemory warning
v onCreate - initialize the library when the application starts
v 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:
v Do not
Tealeaf
Tealeaf
Tealeaf
have a custom Application class for your application, use the IBM
class UIApplication. You do this only if you are not using the Eclipse
plug-in. The plug-in automatically extends the Application class with the
UICApplication class.
v Have a custom Activity class for your application, modify your custom
Application class to point to the Tealeaf UICApplication class.
Application class and the Eclipse Tealeaf plug-in
After you install the Eclipse Tealeaf 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.
16
IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide
Activity class
You extend the Activity class to automatically capture points the lifecycle of a
native Android application page. Tealeaf listens to these events:
v onPause - what happens when the application goes to the background
v onResume - what happens when the application goes to the foreground
v 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:
v Do not have a custom Activity class for your application, use the Tealeaf
UIActivity class.
v Have a custom Activity class for your application, modify your custom Activity
class to point to the Tealeaf UICActivity class.
Extending the Application class with the Tealeaf UICApplication
class
If you do not have a custom Application class, you can use the IBM Tealeaf
UICApplication class to extend the Application class. The application file manages
the lifecycle of an Android application. IBM 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.
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:
a. import com.tl.uic.Tealeaf;
b. 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" />
This example shows the lines that you add to the AdroidManifest.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();
}
}
Chapter 1. Tealeaf installation and implementation in an Android application
17
Extending the Activity class with the 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. IBM 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 IBM 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.
For hybrid applications, screen captures might be missing or out of order due to
timing issues.
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. See "Reference"
in the IBM Tealeaf Android SDK Guide.
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.
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:
a. Import com.tl.uic.Tealeaf;
b. Import com.tl.uic.app.UICApplication;
3. In the onCreate() method, add:
a. Add this.setTakeSnapshotAfterCreate(true); //To enable automatic
screen shots.
b. Add setLogicalPageName("LoginPage") //Recommended to identify page.
c. Add setImageBackground(-16777216) //To set to black background of
screenshot because the screen capture background is transparent.
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);
18
IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide
Extending your custom Application class to point to the Tealeaf
UICApplication class
If you have a custom Application class in your application, point your custom class
to the Tealeaf UICApplication class. The application file manages the lifecycle of an
Android application. IBM 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. .
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():
a. Add Tealeaf tealeaf = new Tealeaf(this);, which initializes the IBM
Tealeaf library with a reference to application instrumented.
b. Add Tealeaf.enable(); that initializes capture of user actions in the
application.
4. In onLowMemory():
a. Add Tealeaf.onLowMemory(); before super so it can adjust the library due
to low memory.
5. In onTerminate():
a. 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" />
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();
}
}
Chapter 1. Tealeaf installation and implementation in an Android application
19
Extending your custom Activity class to point to the Tealeaf
UICActivity class
If you have a custom Activity class, extend it to point to the 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. IBM 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.
Each activity needs a logical page name that helps indicate what activity is being
displayed. If no logical page name is given, IBM Tealeaf recommends using class
name that gives some indication what activity is being displayed.
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 this import:
a. Import com.tl.uic.Tealeaf;
3. Add the logical page name to the class:
private String logicalPageName;
public final String getLogicalPageName() {
if ((this.logicalPageName == null) ||
(this.logicalPageName.equals(""))) {
this.logicalPageName =
this.getClass().getName().substring(this.getClass()
.getName().lastIndexOf(".") + 1);
}
return this.logicalPageName;
}
4. In the onPause() method, add:
a. Add Tealeaf.onPause(this, getLogicalPageName());
5. In the onResume() method, add:
a. Add Tealeaf.onResume(this, getLogicalPageName());
6. In the onDestroy() method, add:
a. Add Tealeaf.onDestroy(this, getLogicalPageName());
This example shows the lines that you add to the file that extends your custom
Activity class:
import com.tl.uic.Tealeaf;
public class BaseActivity extends Activity {
private String logicalPageName;
/**
* Logical page name of the Activity.
*
* @return Logical page name of the Activity.
*/
public final String getLogicalPageName() {
if ((this.logicalPageName == null) ||
(this.logicalPageName.equals(""))) {
this.logicalPageName =
this.getClass().getName().substring(this.getClass().
getName().lastIndexOf(".") + 1);
}
return this.logicalPageName;
}
/**
20
IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide
* Logical page name of the Activity.
*
* @param logicalPageName
*
Logical page name of the Activity.
*/
public final void setLogicalPageName(final String logicalPageName) {
this.logicalPageName = logicalPageName;
}
protected void onPause() {
Tealeaf.onPause(this, getLogicalPageName());
super.onPause();
}
protected void onResume() {
Tealeaf.onResume(this, getLogicalPageName());
super.onResume();
}
protected void onDestroy() {
Tealeaf.onDestroy(this, getLogicalPageName());
super.onDestroy();
}
}
Enabling screen logging in fragments
IBM 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);
}
Implement Tealeaf
After you install Tealeaf, you complete several tasks to implement Tealeaf functions
in your application. These tasks involve modifying your application to capture
controls, events, and screen views.
Implementation tasks
After you install the SDK, you must complete more tasks to implement the SDK.
All of these tasks must be done for both the Tealeaf SDK and Eclipse Tealeaf
plug-in for Tealeaf to work. All of these tasks are manual.
This table lists and describes the tasks that you complete to implement Tealeaf in
your application:
Chapter 1. Tealeaf installation and implementation in an Android application
21
Task
Description
Log Screen Layout for Android Mobile App
Replay
Configure logging screen layout to use JSON
data not screen captures. Includes
configuring logical pages names, alert
dialogs, and keyboard events.
Tealeaf SDK ONLY
Integrate Cordova, PhoneGap, and IBM
Worklight applications in your application.
Includes extending the Application class for
onCreate, onLowMemory, onTerminate
methods and onPause, on'Resume, and
onDestroy methods for Cordova.
Integration for Apache Cordova, PhoneGap,
and IBM Worklight® applications that use
Android classes without IBM Tealeaf classes
Implementing screenViews
Implementing screenViews as segments for
pages in which the state or context can be
switched without rerendering the page.
Target page configuration
Set up the target page that acknowledges
that events are captured.
Data privacy
Specify the fields that are blocked or masked
during capture.
Configuring sessionization for Android
applications on the client
Configure how session IDs are generated.
Network traffic that is used in application
contains requests only
Tealeaf supports network traffic that is used
in applications that contain requests only.
Configure requests in Android application
Configure Tealeaf to put session identifiers
in cookies.
Uses non-IBM Tealeaf session ID
Configure your generated session IDs to be
used when sessions are enabled or new
sessions started.
Hybrid application
Configure your application to log request
activity if you have a WebView in your
application.
Log screen layout for mobile app session replay
IBM 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 IBM 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.
v 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.
v 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.
22
IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide
v Draw user interactions (UI events) onto the HTML pages that are created from
the JSON data.
For more information on mobile app session replay templates, see "Native app
session replay customization" in the IBM Tealeaf CX Configuration Manual.
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/activitylifecycle/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 IBM 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.
Each AutoLayout entry has the following sub entries:
Chapter 1. Tealeaf installation and implementation in an Android application
23
Table 4. AutoLayout sub entries.
Sub entry
Description
do
Boolean value
Indicates if the screen should be logged or not.
v true: Logs the screen.
v false: Does not log the screen.
Eaxmple: "do": true enables logging for the screen.
screenViewName
String value
Used to provide a custom identifying name that is assigned to the
logged screen in JSON. For example, the screenViewName for a
login screen might be "LoginScreen".
Example: screenViewName": "LoginScreen" sets the value of
screenViewName to LoginScreen.
delay
Numeric value
The amount of time, in milliseconds, that is used to delay the
screen logging action. Increasing the value of this setting increases
the amount of time that must pass between when the screen is
loaded and when the screen logging action occurs. The delay value
is used for do and takeScreenShot.
Example: "delay": 500 sets the delay between screen load and
screen logging to 500 milliseconds.
takeScreenShot
Boolean
Indicates if a screen capture should be taken for the controller
class.
v true: Performs a screen capture.
v false: Does not perform a screen capture.
Example: "takeScreenShot": true turns on screen capturing for
the screen activity.
24
IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide
Table 4. AutoLayout sub entries. (continued)
Sub entry
Description
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": {
"UICAndroidControlsAppActivity": {
"do": false,
"screenViewName": "UICAndroidControlsAppActivity",
"delay": 1,
"takeScreenShot": false
},
"ControlsActivity1": {
"do": true,
"screenViewName": "CA1",
"delay": 500,
"takeScreenShot": false
},
"ControlsActivity2": {
"do": true,
"screenViewName": "CA2",
"delay": 1,
"takeScreenShot": false
},
"ControlsActivity3": {
"do": true,
"screenViewName": "CA3",
"delay": 1,
"takeScreenShot": false
},
"ControlsActivity4": {
"do": true,
"screenViewName": "CA4",
"delay": 1,
"takeScreenShot": false
},
"ControlsActivity5": {
"do": true,
Chapter 1. Tealeaf installation and implementation in an Android application
25
"screenViewName": "CA5",
"delay": 1,
"takeScreenShot": false
},
"ControlsActivity6": {
"do": true,
"screenViewName": "CA6",
"delay": 1,
"takeScreenShot": false
},
"ControlsActivity7": {
"do": true,
"screenViewName": "CA7",
"delay": 1,
"takeScreenShot": false
},
"ControlsActivity8": {
"do": true,
"screenViewName": "CA8",
"delay": 1,
"takeScreenShot": false
}
},
"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"
}
}
}
},
You can also manually configure a screen to log a layout by adding the following
code snippet.
Tealeaf.logScreenLayout(activity, "Name", delayInMS);
Replaying AlertDialogs
You need to know when an alert dialog is displayed so that it can be captured
when the IBM Tealeaf API is called. The following examples show how to log the
AlertDialog.
The following example shows how to log the AlertDialog if you have defined a
onShowListener:
AlertDialog.Builder alertDialogBuilder = new AlertDialog.Builder(mContext);
setCancelable(false);
alertDialogBuilder.setNegativeButton("OK", new DialogInterface.OnClickListener()
{
@Override
public void onClick(DialogInterface dialog, int which) {
Tealeaf.logDialogEvent(dialog, which, "DialogButtonClick");
dialog.dismiss();
Tealeaf.logScreenLayout(activity.getParent(), "pageName", 10);
}
});
AlertDialog dialog = alertDialogBuilder.create();
dialog.setOnShowListener(new OnShowListener() {
@Override
public void onShow(DialogInterface dialog) {
26
IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide
// Tealeaf API to log AlertDialog’s layout
final DialogLogScreenTask dialogLogScreenTask = new DialogLogScreenTask
(getActivity().getParent(), "AlertDialog", (Dialog)dialog);
dialogLogScreenTask.execute();
}
});
The following example shows how to log the AlertDialog if you have not defined
a onShowListener:
AlertDialog.Builder alertDialogBuilder = new AlertDialog.Builder(mContext);
setCancelable(false);
alertDialogBuilder.setNegativeButton("Ok", new DialogInterface.OnClickListener()
{
@Override
public void onClick(DialogInterface dialog, int which) {
Tealeaf.logDialogEvent(dialog, which, "DialogButtonClick");
dialog.dismiss();
Tealeaf.logScreenLayout(activity.getParent(), "pageName", 10);
}
});
AlertDialog dialog = alertDialogBuilder.create();
// Tealeaf API hooks into the onShowListener and logs the AlertDialog’s layout
Tealeaf.logScreenLayoutSetOnShowListener(activity.getParent(), dialog);
dialog.show();
Additional sample projects are included with the distribution in the
AndroidRelease/Tealeaf/SampleCode/EclipseProjects folder.
Replaying keyboard events
Android does not provide an event to understand when a soft keyboard appears
and disappears. Follow this example to make the necessary adjustments to
TextView based controls.
public static void addFocusAndRegister(TextView textView, Activity activity) {
textView.setOnFocusChangeListener(new OnFocusChangeListener() {
@Override
public void onFocusChange(View v, boolean hasFocus) {
if (hasFocus) {
InputMethodManager imm = (InputMethodManager) v.getContext()
.getSystemService(Context.INPUT_METHOD_SERVICE);
imm.showSoftInput(v, InputMethodManager.SHOW_FORCED);
KeyboardView keyboardView = new KeyboardView(v.getContext()
.getApplicationContext(), null);
Tealeaf.logEvent(keyboardView , Tealeaf.TLF_UI_KEYBOARD_
DID_SHOW_NOTIFICATION);
Tealeaf.logEvent(v, Tealeaf.TLF_ON_FOCUS_CHANGE_IN);
} else {
Tealeaf.logEvent(v, com.tl.uic.Tealeaf.TLF_ON_FOCUS_CHANGE_OUT);
InputMethodManager imm = (InputMethodManager) v.getContext()
.getSystemService(Context.INPUT_METHOD_SERVICE);
imm.hideSoftInputFromWindow(v.getWindowToken(), 0);
KeyboardView keyboardView = new KeyboardView(v.getContext()
.getApplicationContext(), null);
Tealeaf.logEvent(keyboardView , Tealeaf.TLF_UI_KEYBOARD
_DID_HIDE_NOTIFICATION);
}
}
});
Chapter 1. Tealeaf installation and implementation in an Android application
27
Tealeaf.registerFormField(textView, activity);
}
EditText et = (EditText) findViewById(R.id.editText1);
addFocusAndRegister(et, this);
For more information, review ControlsActivity3.java in the Sample Code project,
UICAndroidControlsAppdarkHolo.
Supported controls
IBM Tealeaf replays the controls that are extended from the following controls. For
each control, IBM Tealeaf fills in the tlType value in the json object that is sent
back to the server.
Control
Description
ToggleButton and Switch
Uses switch template
Note: At the time of this publication, Switch
is not supported with replay when using an
IBM Tealeaf on-premise Replay server.
RadioGroup and RadioButton
Uses RadioButton template
Note: At the time of this publication,
RadioButton is not supported with replay
when using an IBM Tealeaf on-premise
Replay server.
CheckBox
Uses checkBox template
Button
Uses button template
Scroller, HorizontalScrollView, ScrollView
Uses scroll template
AbsSeekBar
Uses slider template
ProgressBar
Uses progressSpinner or progressBar
template
AbsSpinner
Uses selectList template
EditText
Uses label template
TextView
Uses switch template
ImageView
Uses image template
FrameLayout, LinearLayout, ViewStub, View Uses canvas template
AbsListView
Uses grid template
AlertDialog
Uses alert template
TabWidget
Uses tabBar template
TabHost
Uses tabContainer template
Integrate Tealeaf and IBM MobileFirst Platform Foundation with
Eclipse
IBM MobileFirst™ Platform Foundation is IBM's MobileFirst Platform for
developing both hybrid and native applications on multiple mobile platforms. IBM
MobileFirst Platform Foundation provides an Eclipse plug-in called "IBM
MobileFirst Platform Foundation Developer Studio" to help Developers create
Mobile Apps more productively. For logging activities on your application, you
might want to integrate the Tealeaf library with your MobileFirst "Hybrid"
application.
28
IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide
Use the following steps to integrate Tealeaf and IBM MobileFirst into an Eclipse
development environment.
1. Install and setup Eclipse.
2. Install and setup your MobileFirst development environment with Eclipse. For
more information on how to setup your development environment, see
https://mobilefirstplatform.ibmcloud.com/tutorials/en/foundation/7.1/
setting-up-your-development-environment/setting-up-the-mobilefirstdevelopment-environment/.
3. In Eclipse, import your MobileFirst project into Eclipse. Right-click Project
Explorer and select Import > Import > Existing Projects into Workspace; then,
select your MobileFirst project.
4. Copy the Tealeaf defaultConfiguration.js file to the \apps\demoApp\common
folder. Static assets are located in \apps\demoApp\common and are shared across
all hybrid applications. Additionally, .css and image files are located in
\apps\demoApp\common.
5. Add a reference to defaultConfiguration.js in your index.html file so that it
loads when the application starts.
6. Copy the contents of \apps\demoApp\common to the Replay server. For most
installations, copy the contents to the \Apps\App_name\App_version\www\default
on the Replay server. The files are referenced during Replay.
7. Build the project for your preferred mobile platform. As part of the build
process, MobileFirst generates a separate project.
8. Test the new application by running the MobileFirst project that was created in
step 7.
Note: In order for replay to work with your MobileFirst application, make sure
that the contents of \apps\demoApp\common are copied to the Replay server. For
most Tealeaf installations, copy the contents to the \Apps\App_name\App_version\
www\default on the Replay server.
Complete the integration with Tealeaf by extending the Java classes.
Extending the MobileFirst Java classes for Tealeaf:
After your MobileFirst development environment is configured, you need to
extend the Java classes for integration with Tealeaf.
Use the following snippets to extend the Java classes for Tealeaf integration with
MobileFirst.
1. Extend the org.apache.cordova.CordovaChromeClient class using the following
snippet.
public class MyChromeClient extends CordovaChromeClient {
/**
* Constructor.
*
* @param cordova
*/
public MyChromeClient(CordovaInterface cordova) {
super(cordova);
}
/**
* Constructor.
*
* @param ctx
* @param app
*/
Chapter 1. Tealeaf installation and implementation in an Android application
29
public MyChromeClient(CordovaInterface ctx, CordovaWebView app) {
super(ctx, app);
}
/**
* {@inheritDoc}
*/
public final void onConsoleMessage(final String message, final int lineNumber, final String sourceID) {
super.onConsoleMessage(message, lineNumber, sourceID);
LogInternal.log("WebView: " + message + " -- From line " + lineNumber + " of" + sourceID);
}
}
2. Extend the Extendorg.apache.cordova.CordovaWebView class using the following
snippet.
public class MyWebView extends CordovaWebView {
private PropertyName webViewId;
private MyWebViewClient myWebViewClient;
private MyChromeClient myChromeClient;
/**
* @param context
*/
public MyWebView(Context context) {
super(context);
init();
}
/**
* @param context
* @param attrs
*/
public MyWebView(Context context, AttributeSet attrs) {
super(context, attrs);
init();
}
/**
* @param context
* @param attrs
* @param defStyle
*/
public MyWebView(Context context, AttributeSet attrs, int defStyle) {
super(context, attrs, defStyle);
init();
}
/**
* Get webview id.
*
* @return Webview id.
*/
public final PropertyName getWebViewId() {
return webViewId;
}
/**
* Set webview id.
*
* @param webviewId Webview id.
*/
public final void setWebViewId(final PropertyName webviewId) {
this.webViewId = webviewId;
}
30
IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide
/**
* {@Override}
*/
public void loadUrl(final String url) {
loadUrl(url, null);
}
/**
* {@inheritDoc}
*/
public final void loadUrl(final String url, final Map<String, String> extraHeaders) {
Tealeaf.setTLCookie(url);
super.loadUrl(url, extraHeaders);
}
public MyWebViewClient getMyWebViewClient() {
return myWebViewClient;
}
public MyChromeClient getMyChromeClient() {
return myChromeClient;
}
/**
* Initializes WebView.
*/
private void init() {
CordovaInterface cordovaInterface = (CordovaInterface)this.getContext();
this.myWebViewClient = new MyWebViewClient(cordovaInterface, this);
this.myChromeClient = new MyChromeClient(cordovaInterface, this);
this.setWebViewClient(this.myWebViewClient);
this.setWebChromeClient(this.myChromeClient);
this.setWebViewId(Tealeaf.getPropertyName(this));
// This sets up the javascript bridge to communicate from web to native to collect data
this.addJavascriptInterface(new JavaScriptInterface(this.getContext(),
getWebViewId().getId()), "tlBridge");
}
}
3. Extend the Extend org.apache.cordova.CordovaWebViewClient class using the
following snippet.
public class MyWebViewClient extends CordovaWebViewClient {
public MyWebViewClient(CordovaInterface cordova, CordovaWebView view) {
super(cordova, view);
}
/**
* {@inheritDoc}
*/
@Override
public void onPageFinished(final WebView view, final String url) {
view.loadUrl("javascript:TLT.registerBridgeCallbacks([
"
+ "{enabled: true, cbType: ’screenCapture’, cbFunction: function()
{tlBridge.screenCapture();}},"
+ "
{enabled: true, cbType: ’messageRedirect’, cbFunction: function (data)
{tlBridge.addMessage(data);}}]);");
}
}
4. Integrate your WebView into your CordovaActivity with the following snippet.
@Override
public void onCreate(Bundle savedInstanceState){
super.onCreate(savedInstanceState);
//Tealeaf Integration
MyWebView myWebView = new MyWebView(this);
Chapter 1. Tealeaf installation and implementation in an Android application
31
MyWebViewClient myWebViewClient = myWebView.getMyWebViewClient();
MyChromeClient myChromeClient = myWebView.getMyChromeClient();
super.init(myWebView, myWebViewClient, myChromeClient);
WL.createInstance(this);
WL.getInstance().showSplashScreen(this);
WL.getInstance().initializeWebFramework(getApplicationContext(), this);
}
5. Integrate the Tealeaf ScreenLayout API call into your CordovaActivity with the
following snippet.
/**
* The IBM MobileFirst Platform calls this method after its initialization is complete
and web resources are ready to be used.
*/
public void onInitWebFrameworkComplete(WLInitWebFrameworkResult result){
if (result.getStatusCode() == WLInitWebFrameworkResult.SUCCESS){
super.loadUrl(WL.getInstance().getMainHtmlFilePath());
//Tealeaf Integration
Tealeaf.logScreenLayout(this, this.getClass().getName(), 30000);
} else {
handleWebFrameworkInitFailure(result);
}
}
6. Add the standard Tealeaf callbacks with the following snippet.
//Tealeaf Integration
public void onResume() {
// Handle Tealeaf during onResume event
Tealeaf.onResume(this, this.getClass().getName());
super.onResume();
}
public void onPause(){
// Handle Tealeaf during onPause event
Tealeaf.onPause(this, this.getClass().getName());
super.onPause();
}
public void onDestroy() {
// Handle Tealeaf during
onResume event
Tealeaf.onDestroy(this, this.getClass().getName());
super.onDestroy();
}
Implementing screenViews
For pages in which the state or context can be switched without re-rendering the
page, IBM Tealeaf segments the data between states by using a screenView object.
For example, if a page contains multiple tabs, each of which represents a different
stage in a checkout process, you instrument each tab in the page as a distinct
screenView.
To implement a screenView for a page, complete the following steps.
1. If you are extending from UICActivity, set a logicalPageName to indicate the
use of the activity. Otherwise, logicalPageName is set to the name of the class of
the activity.
2. If the prior step is not complete, call Tealeaf.logScreenview and pass the
logicalPageName. You must also indicate if the page being loaded and unloaded
is optional. For example:
Tealeaf.logScreenview(activity, logicalPageName, ScreenviewType.LOAD);
Tealeaf.logScreenview(activity, logicalPageName, ScreenviewType.UNLOAD);
32
IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide
Basic configuration
You must set up a target page on your web server.
See “Quick start for server configuration” on page 89.
Set the target page's address in the TealeafBasicConfig.properties configuration
file under the key PostMessageUrl.
See "Configuration File" in the IBM Tealeaf Android SDK Guide.
Data privacy
IBM Tealeaf provides mechanisms for masking or blocking sensitive customer
information, such as credit card numbers, from being transmitted and captured by
IBM Tealeaf. Through the Android SDK, you can specify the fields that need to be
blocked or masked in your web application.
When applied, data privacy ensures that these data elements are never transmitted
to IBM Tealeaf.
Note: Due to changes in how client framework data is submitted to IBM Tealeaf
for capture, the best method for masking or blocking sensitive data is to apply the
filtering through the capturing client framework. While other IBM Tealeaf features
to manage data privacy can be deployed, they are not easy to implement on the
new format of data captured from the client frameworks. IBM Tealeaf recommends
using the methods referenced below.
v See "Configuration File" in the IBM Tealeaf Android SDK Guide.
v For more information about handling sensitive data in general, see "Managing
Data Privacy in Tealeaf CX" in the IBM Tealeaf CX Installation Manual.
Configuring sessionization for Android applications on the client
The Android SDK auto-generates a session ID if one is not provided. This session
ID is used to identify the session on the IBM Tealeaf server.
IBM Tealeaf injects cookies to create session in the IBM Tealeaf system.
Note: When an Android native or hybrid application is placed into background,
the library flushes the collected data and sleeps, instead of disabling it. This
happens unless the session expired due to the session timeout property. The
timeout property is indicated with SessionTimeout in
TealeafBasicConfig.properties. The default value for this property is 30 minutes.
After a 30-minute timeout, a new session identifier is created.
There are two ways to configure sessionization; either through TLTSID provide by
IBM Tealeaf, or through customer session ID, called JSESSIONID. Both methods
function as a unique session identifier within the Android SDK environment for
IBM Tealeaf to track on customer sessions. CookieParam can be set to use customer
session ID or JSESSIONID.
The following is a typical setting in TealeafBasicConfig.properties using
customer session ID.
#Sessionization settings on customer cookies
CookieUrl = http://www.sample.com
CookieDomain = .sample.com
CookiePath = /
Chapter 1. Tealeaf installation and implementation in an Android application
33
CookieParam = JSESSIONID
CookieExpires = false
SessionTimeout=30
SessoinTimeoutKillSwitch=false
In this example, the cookie expires 30 minutes from current time. When the session
timeout occurs, Android SDK retrieves the new cookie from your application
server and posts the rest of request to application server using this new acquired
cookie in request header. PCA groups all the used JSESSIONIDs into one single
session even though the JSESSIONID was consistently changing. When using
cookies generated from customer application server, SessoinTimeoutKillSwitch can
be set to true or false. Setting the SessoinTimeoutKillSwitch to false means the
session timeout user does not go to recheck on KillSwitchUrl to see if it is
responding.
Network traffic used in application contains requests only:
Android SDK uses cookies to add values to the TLFConfigurableItems.properties
file.
Uses session ID generated by IBM Tealeaf Android SDK
Android SDK uses cookies to add the following values in
TLFConfigurableItems.properties.
v CookieUrl is for url of site that is posted and getting cookie to sessionize on.
v CookieParam is the parameter that has a session id.
v CookiePath is the path of the cookie.
v CookieDomain is the domain that the cookie belongs to.
v CookieSecure is to add a secure cookie that can only be posted to an https url
that has a valid certificate.
v CookieExpiresFormat can have the date format of ASCTIME, RFC1036, or
RFC1123, which will have an expiration date of current time + session timeout
indicated in the variable below.
v SessionTimeout is session timeout is in minutes. When this value expires a new
session id is created.
An example follows.
#Sessionization settings
CookieUrl=http://m.ibm.com
CookieParam=TLTSID
CookiePath=/
CookieDomain=.ibm.com
#Whether you want to create a secure cookie which can only be sent using a
https url in PostMessageUrl.
CookieSecure=false
#Valid date formats: ASCTIME, RFC1036, RFC1123
CookieExpiresFormat=ASCTIME
#When post is sent, expiration of cookie will be current time + session timeout
#Session timeout is in minutes
SessionTimeout=30
Note: It is important to first call your server to get first cookie to sessionize on,
which is automatically obtained when you enable the kill switch URL on the
application. This is used to aggregate all the data on CX Passive Capture
Application capture.
34
IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide
Configure requests in Android application
IBM Tealeaf needs all the requests to have the session id to be placed in the
cookies of the request. This enables the IBM Tealeaf CX PCA to collect all the
resources together in a single captured session.
Add the following cookie into the GET and POST requests to enable the PCA to
listen to requests and responses.
httpClient.setRequestProperty("Cookie", Tealeaf.getTLCookie(Tealeaf.getCurrentSessionId()));
Uses non IBM Tealeaf session ID
You must get your generated session ID and use it when you enable or start a new
session in Android SDK.
// If enabling of Android Logging Framework use
Tealeaf.enable();
Tealeaf.enable("your session id");
// If Android Logging Framework is enabled and a new session is to be created use
Tealeaf.startSession();
Tealeaf.startSession("your session id");
Android application gestures
You can capture gestures that the users make on your Android application. Several
types of gestures are captured.
Configuration
For any Activity class that you want Gesture logging, you edit
TealeafBasicConfig.properties file and set the SetGestureDetector property to
true.
Touch event methods
You add your variables to one of these methods:
v onTouchEvent - use this method if your activity is not using a customized gesture
view.
v dispatchTouchEvent - use this method if your activity is using a customized
gesture view.
If your application uses a customized gesture view, onTouchEvent does not detect
the gestures because they are already captured by the customized gesture view. If
you are using a customized gesture view, you must use dispatchTouchEvent.
You can use either the onTouchEvent or the dispatchTouchEvent. If you use both,
the gestures are captured twice.
Gesture events captured:
Gestures that are used to select items in an application or to adjust views in the
application are captured by Tealeaf.
Tap gestures
This table lists and describes the tap gestures that are captured from web and
mobile apps.
Note: The arrows that illustrate the direction of a swipe or pinch gesture are not
supported by the Internet Explorer browser.
Chapter 1. Tealeaf installation and implementation in an Android application
35
Table 5. Tap gestures.
Gesture name
Description
Tap
This gesture is a one-finger gesture.
Image displayed in Replay
For a tap gesture, one-finger taps and lifts
from the screen in 1 location.
Tap and Hold
This gesture is a one-finger gesture.
For a Tap and Hold gesture, one-finger
presses and stays on the screen until
information is displayed or an action
occurs.
Note: The response to a Tap and Hold
gesture can vary from one application to
another. For example, a Tap and Hold
gesture might display an information
bubble, magnify content under the finger,
or present the user with a context menu.
Double tap
This gesture is a one-finger gesture.
For a double tap gesture, one-finger taps
twice in close succession in 1 location of the
screen.
Swipe gestures
This table lists and describes the swipe gestures that are captured from web and
mobile apps:
Table 6. Swipe gestures
Gesture name Description
Swipe
vertically
This gesture is a one-finger gesture.
For a swipe vertically gesture, one-finger:
1. taps and holds in 1 location of screen,
2. continues to engage screen while it moves
up or down
3. lifts from the screen in different location.
Note: The initial tap becomes lighter in color,
while the destination is highlighted by a
darker color
36
IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide
Image displayed in Replay
Table 6. Swipe gestures (continued)
Gesture name Description
Swipe
horizontally
Image displayed in Replay
This gesture is a one-finger gesture.
For a swipe horizontally gesture, one-finger:
1. taps and holds in 1 location of screen,
2. continues to engage screen while it moves
left or right
3. lifts from the screen in different location.
Note: The initial tap becomes lighter in color,
while the destination is highlighted by a
darker color
Resize gestures
This table lists and describes the resize gestures that are captured from web and
mobile apps:
Note: See the IBM Tealeaf Customer Experience 9.0.1 Release Notes for information
about a known limitation for handling some iOS pinch gestures.
Table 7. Resize gestures
Gesture name
Description
Image displayed in Replay
Pinch open
Sometimes referred to as a spread gesture,
this is a two-finger gesture.
For a pinch open gesture, 2 fingers:
1. tap and hold in 1 location of the screen,
2. maintain contact with the screen while
the fingers move apart from each other
in any direction,
Note: Accompanying arrows indicate the direction
(open or close) of the pinch
3. lift from the screen at a new location.
Pinch close
This gesture is a two-finger gesture.
For a pinch close resize gesture, 2 fingers:
1. tap and hold in 1 location on the screen,
2. maintain contact with the screen while
the fingers move toward each other,
3. lift from the screen at a new location.
Note: Accompanying arrows indicate the direction
(open or close) of the pinch
Unresponsive gesture events captured
Unresponsive gestures are gestures that do not respond when a user tries to select
items in an application or tries to adjust views in the application. Like other
gesture events, unresponsive gestures are captured by Tealeaf.
Unresponsive gestures are displayed graphically in BBR as orange outlined icons
accompanied by a circled "X" . The circled "X" denotes that the gesture was
unresponsive. For example, if a double tap gesture did not yield a response in the
mobile application, then at replay time that gesture is displayed with the following
icon in BBR:
Chapter 1. Tealeaf installation and implementation in an Android application
37
The following table lists the unresponsive gestures that are captured from web and
mobile apps and shows the images that are displayed in BBR:
Table 8. Unresponsive gestures and icons
Unresponsive Gesture
Image displayed in Replay
Tap gestures
Unresponsive tap
Unresponsive double tap
Unresponsive tap and hold
Swipe gestures
Swipe vertically
Note: Accompanying arrows indicate the direction of the swipe.
Swipe horizontally
Note: Accompanying arrows indicate the direction of the swipe.
38
IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide
Table 8. Unresponsive gestures and icons (continued)
Unresponsive Gesture
Image displayed in Replay
Tap gestures
Resize gestures
Pinch open
Note: Accompanying arrows indicate the direction of the pinch.
Pinch close
Note: Accompanying arrows indicate the direction of the pinch.
Instrumenting your application for Android gestures:
You can enable your application to capture gestures that the user makes on your
application. To enable gestures for an Activity class, you modify the Activity class.
For example, you modify the MainActivity.java file and call the
Tealeaf.dispatchTouchEvent method inside dispatchTouchEvent or onTouchEvent
method.
To use the Android gestures module, you must the Android Support Library
android-support-v4.jar together with Tealeaf SDK uicandroid.jar. The
android-support-v4.jar is distributed within Android SDK. Download and install
the Android Support Library from the Android Support Library site. The
installation installs the android-support-v4.jar at ${your Android SDK
location}/extras/android/support/v4/android-support-v4.jar
1. Open the MainActivity.java file for your application.
2. Override either the dispatchTouchEvent or the onTouchEvent method,
depending on how you are using gestures in your application:
IF your application is...
THEN...
using a customized gesture view
Override the dispatchTouchEvent
publc boolean dispatchTouchEvent
( MotionEvent e) {
Tealeaf.dispatchTouchEvent(this, e);
return super.dispatchTouchEvent(e);
}
Chapter 1. Tealeaf installation and implementation in an Android application
39
IF your application is...
THEN...
not using a customized gesture view
Override the onTouchEvent
publc boolean onTouchEvent
( MotionEvent e) {
Tealeaf.dispatchTouchEvent(this, e);
return super.onTouchEvent(e);
}
This example shows the code snippets that are added in this task for an
application that does not use a customized gesture view:
mport com.tl.uic.Tealeaf;
import com.tl.uic.app.UICActivity;
import android.os.Bundle;
import android.view.MotionEvent;
public class MainActivity extends UICActivity{
@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_main);
Tealeaf.logScreenLayout(this, this.getLogicalPageName(), 1000);
}
public boolean dispatchTouchEvent( MotionEvent e) {
Tealeaf.dispatchTouchEvent(this,e);
return super.dispatchTouchEvent(e);
}
}
Modifying the TealeafBasicConfig.properties file for gestures:
After you define the variables for gestures in your Activity class, you enable
gesture capture by modifying the TLFConfiguratableItems.properties file.
1. Edit the TealeafBasicConfig.properties file.
2. Set SetGestureDetector to true.
3. Save and exit the TealeafBasicConfig.properties file.
Log exceptions
Exceptions are the way that a system or framework communicates to the
application that something is wrong. Tealeaf provides two mechanisms to log
exceptions. You can manually log exceptions by using the logException API, or
Tealeaf SDK will automatically log uncaught exceptions. The exception information
can be used for analytics.
Automatically log exceptions
When your application throws an uncaught exception, Tealeaf Android SDK
records the stack trace and state of the device at the time the exception was
thrown. Tealeaf Android SDK sends the crash information to your target servers
for processing.
40
IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide
Manually log exceptions
In the Android SDK, you modify your catch block to report caught exceptions to
the target server for processing. When you modify your catch block, you get the
full stack trace and same device information that Tealeaf collects for fatal crashes.
This table shows the method that is used to log exceptions and describes the
parameters that are used in the method:
Method
Parameters
public static Boolean
logException(final
Throwable exception, final
HashMap<String, String> data,
final Boolean unhandled)
Where:
v @param exception - the exception to be
logged.
v @param data - the value to be given to
event.
v @param unhandled - whether the
exception is unhandled.
v @return - whether exception was logged.
Example
In this example, you have a method that causes an exception:
public void clientMethod1( ) {
}
You add an @try , @catch, and the Tealeaf.logException(e, data, false) method
to handle the exception:
public void clientMethod1( ) {
try {
int[] array = new int[1];
int i = array[2]; // Index out of bound exception
} Catch (Exception e) {
HashMap<String, String> data = new HashMap<String, String>();
data.put("extraMessage", "custom value1");
Tealeaf.logException(e, data, false);
}
}
Logging exceptions:
Use the examples in this task as a guide to adding exception logging to your
application.
1. Determine the method for which you want to log exceptions. For example, you
have a method:
public void clientMethod1( ) {
}
2. Optional: Add the exception method to the method for which you want to log
the exceptions.
Add @try , @catch, and the Tealeaf.logException(e, data, false) method to
handle the exception:
public void clientMethod1( ) {
try {
int[] array = new int[1];
int i = array[2]; // Index out of bound exception
Chapter 1. Tealeaf installation and implementation in an Android application
41
} Catch (Exception e) {
HashMap<String, String> data = new HashMap<String, String>();
data.put("extraMessage", "custom value1");
Tealeaf.logException(e, data, false);
}
}
Android application geolocation
You can log geolocation information for the users of your applications. You can
configure automatic geolocation logging when the application starts or you can use
APIs to log geolocation information at specific places in your application. Replay
and reporting of geolocation data is not available currently.
Automatic logging
You configure automatic logging with the TealeafBasicConfig.properties file and
the manifest file.
To give permission to the device to log geolocation data, add <uses-permission
android:name="android.permission.ACCESS_FINE_LOCATION" > and
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION"/>
to the android manifest file. For example:
<uses-permission
<uses-permission
<uses-permission
<uses-permission
<uses-permission
<uses-permission
android:name="android.permission.INTERNET" />
android:name="android.permission.ACCESS_NETWORK_STATE" />
android:name="android.permission.ACCESS_WIFI_STATE" />
android:name="android.permission.ACCESS_FINE_LOCATION" />
android:name="android.permission.ACCESS_COARSE_LOCATION"/>
android:name="android.permission.READ_PHONE_STATE" />
There are three configurable items you can set in the
TealeafBasicConfig.properties:
Property
Description
LogLocationEnabled
Use this property to enable geolocation
logging. Values are:
v True - logging is enabled
v False - logging is not enabled
LogLocationTries
Use this property to set the number of times
the device tries to get the geolocation
information when the device's signal is
weak.
LogLocationTimeout
Use this property to set the amount of time
between retries for the device to get the
geolocation information when the device's
signal is weak.
For example, when the device signal is weak you want the device to try 3 times to
get the geolocation signal and for the device to wait 30 seconds between retries,
you set the configurable items to these values:
#Auto Geolocation logging enabled or not
LogLocationEnabled=true
LogLocationTries=3
LogLocationTimeout=30
42
IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide
APIs
There are three APIs you can use to manually enable geolocation information
logging in your application:
v public static Boolean logGeolocation() - Use this API at a specific point in
your application to log geolocation only at that point.
v public static GeoLocation logGeolocation(final Boolean getGeolocation) Use this API at a specific point in your application to return a geolocation object
that contains latitude, longitude, and accuracy values.
v public static Boolean logGeolocation(final int logLevel) - Use this API at
a specific point in your application to log geolocation information based on log
level.
Disable geolocation capture in the Web application
Note: The UI Capture library typically tracks geolocation information within the
Web application. When geolocation is enabled in a hybrid mobile application, the
geolocation tracking feature in the Web application should be disabled and the
application should use the native SDK capture the geolocation information.
To disable geolocation capture in the Web application:
1. Locate the UI Capture library configuration. The configuration is typically at
the end of the UI Capture SDK file as part of the call to the TLT.init() API.
2. Locate the geolocation configuration section in the replay module configuration
object (modules.replay.geolocation).
3. If the geolocation configuration section does not exist, the feature is disabled
automatically. If the section does exist, then ensure that the enabled setting is
set to false. The following example shows the geolocation section for the UI
Capture SDK with geolocation disabled.
geolocation: {
enabled: false,
triggers: [
{
event: "load"
}
]
},
Logging geolocation information in your application automatically:
Before you begin this task you need to know:
v The number of times you want the application to try to get the geolocation
information when the signal is weak.
v The amount of time, in seconds, that you want the application to wait before
again trying to get the geolocation information.
1. In your application in Eclipse, open the TealeafBasicConfig.properties file.
a. Set LogLocationEnabled to true.
b. Set LogLocationTries to the number of times you want the application to
try log the geolocation information.
c. Set LogLocationTimeout to the number of seconds that the device should
retry when the signal is weak.
d. Save and exit the file.
2. In your application in Eclipse, open the AndroidManifest.xml file.
Chapter 1. Tealeaf installation and implementation in an Android application
43
a. Add this line <uses-permission
android:name="android.permission.ACCESS_FINE_LOCATION" > to the file.
b. Save and exit the file.
Hybrid applications
An application is considered to be hybrid if it contains a WebView in the Android
application.
If you use a WebView, you must use UICWebView to log request activity in the
WebView. UICWebView extends the base WebView from the Android Framework,
which inserts the IBM Tealeaf header with the current session ID for sessionization.
If you decide not to use UICWebView, then you need to extend a Webview to add
sessionization.
See "UICWebView Class" in the IBM Tealeaf Android SDK Guide.
Extend android.webkit.WebView:
This sample code shows how the base Android WebView is extended with
UICWebView.
/*******************************************************************************
* Licensed Materials - Property of IBM
* (C) Copyright IBM Corp. 2015
* US Government Users Restricted Rights - Use, duplication or disclosure
* restricted by GSA ADP Schedule Contract with IBM Corp.
******************************************************************************/
package com.tl.uic.webkit;
import java.util.Date;
import java.util.Map;
import org.apache.http.HttpResponse;
import
import
import
import
import
android.annotation.SuppressLint;
android.app.Activity;
android.content.Context;
android.util.AttributeSet;
android.webkit.WebView;
import
import
import
import
com.tl.uic.TLFCache;
com.tl.uic.Tealeaf;
com.tl.uic.javascript.JavaScriptInterface;
com.tl.uic.model.PropertyName;
/**
* @author ohernandezltmac
*/
public class UICWebView extends WebView {
private Date endLoad;
private Date startLoad;
private String url;
private HttpResponse httpResponse;
private Date initTime;
private long responseTime;
private long connectionInitFromSession;
private PropertyName webViewId;
/**
* @param context Android context.
*/
public UICWebView(final Context context) {
super(context);
init();
44
IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide
}
/**
* @param context Android context.
* @param attrs an AttributeSet passed to our parent.
*/
public UICWebView(final Context context, final AttributeSet attrs) {
super(context, attrs);
init();
}
/**
* @param context Android context.
* @param attrs an AttributeSet passed to our parent.
* @param defStyle the default style resource ID.
*/
public UICWebView(final Context context, final AttributeSet attrs, final
int defStyle) {
super(context, attrs, defStyle);
init();
}
/**
* When page finished loading.
*
* @return When page finished loading.
*/
public final Date getEndLoad() {
return endLoad;
}
/**
* When page finished loading.
*
* @param endLoad When page finished loading.
*/
public final void setEndLoad(final Date endLoad) {
this.endLoad = endLoad;
}
/**
* When page starts loading.
*
* @return When page starts loading.
*/
public final Date getStartLoad() {
return startLoad;
}
/**
* When page starts loading.
*
* @param startLoad When page starts loading.
*/
public final void setStartLoad(final Date startLoad) {
this.startLoad = startLoad;
}
/**
* HttpResponse from the connection.
*
* @return HttpResponse from the connection.
*/
public final HttpResponse getHttpResponse() {
return httpResponse;
}
Chapter 1. Tealeaf installation and implementation in an Android application
45
/**
* HttpResponse from the connection.
*
* @param httpResponse HttpResponse from the connection.
*/
public final void setHttpResponse(final HttpResponse httpResponse) {
this.httpResponse = httpResponse;
}
/**
* Initial time from the connection.
*
* @return Initial time from the connection.
*/
public final Date getInitTime() {
return initTime;
}
/**
* Initial time from the connection.
*
* @param initTime Initial time from the connection.
*/
public final void setInitTime(final Date initTime) {
this.initTime = initTime;
this.connectionInitFromSession = TLFCache.timestampFromSession();
}
/**
* Response time from the connection.
*
* @return Response time from the connection.
*/
public final long getResponseTime() {
return responseTime;
}
/**
* Response time from the connection.
*
* @param responseTime Response time from the connection.
*/
public final void setResponseTime(final long responseTime) {
this.responseTime = responseTime;
}
/**
* Get webview id.
*
* @return Webview id.
*/
public final PropertyName getWebViewId() {
return webViewId;
}
/**
* Set webview id.
*
* @param webviewId Webview id.
*/
public final void setWebViewId(final PropertyName webviewId) {
this.webViewId = webviewId;
}
/**
* {@inheritDoc}
*/
46
IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide
@SuppressWarnings("PMD.NullAssignment")
@Override
public void loadData(final String data, final String mimeType,
final String encoding) {
this.url = null;
this.initTime = null;
this.connectionInitFromSession = 0;
this.responseTime = 0;
this.httpResponse = null;
this.startLoad = new Date();
super.loadDataWithBaseURL(this.url, data, mimeType, encoding, "");
}
/**
* {@inheritDoc}
*/
@SuppressLint("NewApi")
@Override
public void loadUrl(final String url) {
loadUrl(url, null);
}
/**
* {@inheritDoc}
*/
public final void loadUrl(final String url, final Map<String, String>
extraHeaders) {
this.url = url;
Tealeaf.setTLCookie(this.url);
super.loadUrl(url, extraHeaders);
}
/**
* Initializes WebView.
*/
private void init() {
setStartLoad(new Date());
// Need it when in Eclipse editor mode
if (!this.isInEditMode()) {
this.setWebViewClient(new UICWebViewClient());
this.setWebChromeClient(new UICWebChromeClient((Activity)
this.getContext()));
this.setWebViewId(Tealeaf.getPropertyName(this));
this.addJavascriptInterface(new JavaScriptInterface(this.getContext(),
getWebViewId().getId()), "tlBridge");
}
}
/**
* Log the load time of the WebView.
*
* @return If log connection was added to queue.
*/
public final Boolean logConnection() {
final long endTime = this.getEndLoad() != null ?
this.getEndLoad().getTime() : 0;
final long startTime = this.getStartLoad() != null ?
this.getStartLoad().getTime() : 0;
final long loadTime = endTime - startTime;
return Tealeaf.logConnection(this.url, this.httpResponse,
this.connectionInitFromSession, loadTime, this.responseTime);
}
}
Chapter 1. Tealeaf installation and implementation in an Android application
47
Extend android.webkit.WebViewClient:
The sample code that follows extends the base Android WebViewClient with
UICWebViewClient.
/*******************************************************************************
* Licensed Materials - Property of IBM
* (C) Copyright IBM Corp. 2015
* US Government Users Restricted Rights - Use, duplication or disclosure
* restricted by GSA ADP Schedule Contract with IBM Corp.
******************************************************************************/
package com.tl.uic.webkit;
import
import
import
import
android.annotation.SuppressLint;
android.os.Build;
android.webkit.WebView;
android.webkit.WebViewClient;
/**
* @author ohernandezltmac
*
*/
public class UICWebViewClient extends WebViewClient {
/**
* {@inheritDoc}
*/
@Override
public boolean shouldOverrideUrlLoading(final WebView view, final String url) {
view.loadUrl(url);
return true;
}
/**
* {@inheritDoc}
*/
@SuppressLint("NewApi")
@Override
public void onPageFinished(final WebView view, final String url) {
// Get the call back mapping string to be evaluated/loaded as
Javascript code
final String javascriptString = com.tl.uic.javascript.JavaScriptInterface.
hybridBridgeRegisterCallback();
if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.KITKAT) {
view.evaluateJavascript(javascriptString, null);
} else {
view.loadUrl("javascript:" + javascriptString);
}
}
}
Sessionization for PhoneGap based Applications:
Since there are no requests and responses being sent back to the server, IBM
Tealeaf does not require extending of WebView to add sessionization.
Configuring DOM Capture and Replay for native Android applications that
cannot use PCA:
You configure DOM capture for a native Android application that cannot use PCA
by modifying the defaultconfiguration.js file. If the HTML page in the webview
does not fire on page load or if the page changes dramatically, you need to fire
DOM capture from within your native Android application.
48
IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide
Before you do this task you must install the UIC library in your native application.
All of the modifications that you make are in your native Android application.
1. Modify the defaultconfiguration.js file and set the DOM Capture options
that you want to use:
replay: {
// DOM Capture configuration
domCapture: {
/**
* NOTE: Enabling DOM Capture has significant implications on data
* transmission and infrastructure. This feature should be enabled
* judiciously. If enabled, it requires further configuration
* to only perform the DOM Capture based on specific events and
* elements. Refer to the documentation for more details.
*/
enabled: true,
triggers: [
{
event: "load"
}
]
}
}
Note: In UI Capture version 5.0.0 and later, DOM Diff is automatically enabled
when DOM Capture is enabled. DOM diff is not supported with Hybrid Mobile
replay. Complete the following steps to disable DOM Diff:
a. In the UI Capture SDK configuration, locate the domCapture service
configuration object in the services object.
b. Set the diffEnabled flag to false.
Example:
domCapture: {
diffEnabled: false,
// DOM Capture options
options: {
maxLength: 1000000,
captureFrames: true,
removeScripts: true
// If this threshold is exceeded,
the snapshot will not be sent
// Should child frames/iframes
be captured
// Should script tags be removed
from the captured snapshot
}
}
2. If DOM Capture does not fire on load, set DOM Capture to fire from your
application by adding this code to your native Android application for the
screenview that you want to capture:
if (TLT === undefined) {
console.log(’TLT is undefined!’);
} else {
if (TLT.logScreenviewLoad === undefined) {
console.log(’Could not invoke TLT.logScreenviewLoad API!’);
} else {
TLT.logScreenviewLoad("root");
console.log(’logScreenviewLoad:’);
}
if (TLT.logDOMCapture === undefined) {
console.log(’Could not invoke TLT.logDOMCapture API!’);
} else {
dcid = TLT.logDOMCapture(window.document, {});
console.log(’logDOMCapture:’ + dcid);
}
}
Chapter 1. Tealeaf installation and implementation in an Android application
49
Hybrid application bridge for Android APIs:
An Android hybrid application is a native application that uses WebView control
as part of the UI components. Tealeaf Android SDK provides JavaScript interface
APIs integrated with CX UI Capture j2, which can be started from JavaScript
functions to access native methods in hybrid application.
Tealeaf Android SDK APIs available to JavaScript
When you develop hybrid applications, you embed WebView component within a
larger Android application. You can access exposed Android native methods from
the UI Capture j2 global JavaScript object called "TLT" with methods that you use
in your JavaScript code. This table lists and gives examples of the methods that
you can include in your JavaScript code:
50
Method
Example
Enable Tealeaf Framework
/**
* Public API to enable Tealeaf
framework.
* @returns {void}
*/
enableTealeafFramework();
Disable Tealeaf Framework
/**
* Public API to disable Tealeaf
framework.
* @returns {void}
*/
disableTealeafFramework();
Log Screen Capture
/**
* Public API to add a screenshot
capture.
* @returns {void}
*/
logScreenCapture();
Start New Tealeaf Session
/**
* Public API to start a new Tealeaf
session.
* @returns {void}
*/
startNewTLFSession();
Current Session ID
/**
* Public API to start get current
Tealeaf session Id.
* @returns {String} Current session
Id
*/
currentSessionId();
Default Value for Configurable Item
/**
* Public API to get default value of
a configurable item in
* TLFConfigurableItems.properties
file.
* @param {String} configItem This
is the name of the configurable item.
* @returns {String} The value for the
item.
*/
defaultValueForConfigurableItem
(configItem);
IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide
Method
Example
Value for Configurable Item
/**
* Public API to get the value of
a configurable item either from
* TLFConfigurableItems.properties
file
* or in memory data structure.
* @param {String} configItem This
is the name of the configurable item.
* @returns {String} The value for the
item.
*/
valueForConfigurableItem(configItem);
Set Configurable Item
/**
* Public API to set the value of
a configurable item in
TLFConfigurableItems.properties
* file.
* @param {String} configItem This
is the name of the configurable item.
* @param {String} value The value
assign to the configItem.
* @returns {boolean} Wether item
was set.
*/
setConfigurableItem(configItem, value);
Add Additional HTTP Header
/**
* Public API to add additional http
header.
* @param {String} key This is the
key of the configurable item.
* @param {String} value The value
assign to the configItem.
* @returns {boolean} Wether item
was set.
*/
addAdditionalHttpHeader(key, value);
Log Custom Event Bridge
/**
* Public API to log custom event.
* @param {String} eventName A custom
event name.
* @param {String} jsonData JSON data
string.
* @param {int} logLevel Tealeaf
library logging level for the event.
* @returns {boolean} Wether item
was set.
*/
logCustomEventBridge(eventName,
jsonData,
logLevel);
Example of how a native Android API is started
This example shows how to start a native method to enable Tealeaf Framework on
a UI Capture j2 "TLT" instance using JavaScript:
<script type="text/javascript">
// Example of calling the native API to enable Tealeaf Framework
using Javascript
TLT.enableTealeafFramework();
</script>
Chapter 1. Tealeaf installation and implementation in an Android application
51
Sample test HTML file that starts supported native methods in JavaScript
This example is an HTML file that starts supported native methods in JavaScript:
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" >
<head>
<script type="text/javascript" src="js/tealeaf.js"></script>
<script type="text/javascript" src="js/defaultconfiguration.js" ></script>
<title>test APIs</title>
<body>
<h2>Test page for Android bridge APIs in hybrid app</h2>
<h3>Click on below buttons to run tests:</h3>
<input type="button" style="width: 150px; height: 30px; font-size: 20px"
value="Screen Capture" onclick="TLT.logScreenCapture();return false;"/>
<input type="button" style="width: 150px; height: 30px; font-size: 20px"
value="Native APIs" onclick="runBridgeNativeTealeafAPIs();return false;"/>
<p/>
<p>Test native APIs output here:
<div id="queueData"></div>
</body>
<script type="text/javascript">
function htmlConsoleLog(textData, apiRetVal){
var para = document.createElement("p");
var node;
if( apiRetVal !== undefined && apiRetVal !== null )
{
node = document.createTextNode(textData + " returned: " + apiRetVal);
}
else
{
node = document.createTextNode(textData );
}
para.appendChild(node);
var element = document.getElementById("queueData");
element.appendChild(para);
}
function runBridgeNativeTealeafAPIs() {
htmlConsoleLog( ’----- -------------------------------- -----’ );
htmlConsoleLog( ’----- Calling Tealeaf native APIs -----’ );
var apiRetVal = null;
htmlConsoleLog( ’----- Calling enableTealeaf -----’ );
TLT.enableTealeafFramework();
apiRetVal = null;
htmlConsoleLog( ’----- Calling currentSessionId -----’ );
apiRetVal = TLT.currentSessionId();
htmlConsoleLog( ’----- currentSessionId -----’, apiRetVal );
apiRetVal = null;
htmlConsoleLog( ’----- Calling disableTealeaf -----’ );
TLT.disableTealeafFramework();
var apiRetVal = null;
htmlConsoleLog( ’----- Calling enableTealeaf -----’ );
TLT.enableTealeafFramework();
apiRetVal = null;
htmlConsoleLog( ’----- Calling currentSessionId -----’ );
apiRetVal = TLT.currentSessionId();
htmlConsoleLog( ’----- currentSessionId -----’, apiRetVal );
52
IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide
apiRetVal = null;
htmlConsoleLog( ’----- Calling defaultValueForConfigurableItem
(PostMessageUrl) -----’ );
var PostMessageUrlVal = TLT.defaultValueForConfigurableItem
(’PostMessageUrl’);
htmlConsoleLog( ’----- defaultValueForConfigurableItem -----’,
PostMessageUrlVal );
apiRetVal = null;
htmlConsoleLog( ’----- Calling setConfigurableItem("PostMessageUrl",
"aValidPostUrl") -----’ );
apiRetVal = TLT.setConfigurableItem(’PostMessageUrl’, ’aValidPostUrl’);
htmlConsoleLog( ’----- setConfigurableItem -----’, apiRetVal );
apiRetVal = null;
htmlConsoleLog( ’----- Calling valueForConfigurableItem
("PostMessageUrl") -----’ );
apiRetVal = TLT.valueForConfigurableItem(’PostMessageUrl’);
htmlConsoleLog( ’----- valueForConfigurableItem -----’, apiRetVal );
apiRetVal = null;
htmlConsoleLog( ’----- Calling setConfigurableItem(PostMessageUrl,
’ + PostMessageUrlVal + ’) -----’ );
apiRetVal = TLT.setConfigurableItem(’PostMessageUrl’, PostMessageUrlVal );
htmlConsoleLog( ’----- setConfigurableItem -----’, apiRetVal );
apiRetVal = null;
htmlConsoleLog( ’----- Calling valueForConfigurableItem
("PostMessageUrl") -----’ );
apiRetVal = TLT.valueForConfigurableItem(’PostMessageUrl’);
htmlConsoleLog( ’----- valueForConfigurableItem -----’, apiRetVal );
apiRetVal = null;
htmlConsoleLog( ’----- Calling startNewTLFSession -----’ );
apiRetVal = TLT.startNewTLFSession();
htmlConsoleLog( ’----- startNewTLFSession -----’, apiRetVal );
apiRetVal = null;
htmlConsoleLog( ’----- Calling addAdditionalHttpHeader -----’ );
TLT.addAdditionalHttpHeader(’HeaderFromJavaScript’,
’HeaderValueFromJavaScript’);
htmlConsoleLog( ’----- addAdditionalHttpHeader -----’ );
apiRetVal = null;
htmlConsoleLog( ’----- Calling enableTealeaf again -----’ );
TLT.enableTealeafFramework();
apiRetVal = null;
htmlConsoleLog( ’----- Calling currentSessionId -----’ );
apiRetVal = TLT.currentSessionId();
htmlConsoleLog( ’----- currentSessionId -----’, apiRetVal );
apiRetVal = null;
var str = ’{\’key1AndroidBridge\’: \’value1AndroidBridge\’,
\’key2AndroidBridge\’: \’value2AndroidBridge\’}’;
htmlConsoleLog( ’----- Calling logCustomEvent("Test Android Bridge Custom
Event",’ + str +’) -----’ );
apiRetVal = TLT.logCustomEventBridge(’Test Android Bridge Custom Event’,
str, 0);
htmlConsoleLog( ’----- logCustomEvent(Test Android Bridge Event, ’ +
str +’ ) -----’, apiRetVal );
htmlConsoleLog(
htmlConsoleLog(
htmlConsoleLog(
htmlConsoleLog(
’----’----’----’-----
Done Calling Tealeaf native APIs
----------------------------------------------------------------------------------------------
-----’
-----’
-----’
-----’
);
);
);
);
Chapter 1. Tealeaf installation and implementation in an Android application
53
}
</script>
</head>
</html>
Accessing native Android methods with JavaScript with Tealeaf customized WebView:
When you create hybrid applications, you can access native Android methods with
JavaScript, you use the Tealeaf customized WebView.
Before you begin this task, you must:
1. Install the most recent Tealeaf Android SDK.
2. Implement the Android SDK following the instructions in the documentation.
3. Include the most recent UI Capture j2 JavaScript source file.
1. Add WebView to your application. Specify a length, height, weight, and ID that
suits your application:
<WebView
android:id="@+id/my_webview"
android:layout_width="match_parent"
android:layout_height="0dp"
android:layout_weight="1" />
2. In your activity, locate the WebView and load your HTML file:
public class MainActivity extends ActionBarActivity {
private UICWebView mUICWebView;
private String logicalPageName = "BridgeAppActivity";
@Override
protected void onCreate(Bundle savedInstanceState) {
// Initialize tealeaf with a reference to application
Tealeaf tealeaf = new Tealeaf(this.getApplication());
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_main);
// Load HTML file from local resource in the UICWebview
mUICWebView = (UICWebView) findViewById(R.id.uic_webview);
// Modify the Url for your hybrid app
mUICWebView.loadUrl("file:///android_asset/www/test.html");
WebSettings webSettings = mUICWebView.getSettings();
webSettings.setJavaScriptEnabled(true);
}
3. Copy the application's HTML and JavaScript files to the /assets/www folder in
your Android project.
Install the Eclipse Tealeaf plug-in for Android development in your
application
Use of the Tealeaf Logging Frameworks for mobile native applications requires the
Tealeaf CX Mobile license for Mobile App. For more information, contact your
Tealeaf representative. Licensees must implement in their apps code that is
provided by Tealeaf. For more information on downloading IBM Tealeaf, see IBM
Passport Advantage Online.
54
IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide
Install process
Note: The Android SDK is no longer supported with Eclipse. Android Studio
should be used to integrate the Android SDK with your mobile application. The
following references to integrating the Android SDK using Eclipse should only be
used as a reference.
To install and configure the Eclipse Tealeaf plug-in in your Eclipse project you:
1. Add the Eclipse Tealeaf plug-in to your project
2. Convert your project to an Android + Tealeaf project
3. Configure initial Eclipse Tealeaf plug-in properties
4. Extend Android classes with or without the extended IBM Tealeaf classes.
Tealeaf package contents
A single file contains the Android SDK and its software components.
IBM Tealeaf Android SDK is delivered in the IBM Tealeaf Android SDK - iOS
Logging Framework for Windows within the IBM Passport Advantage Online.
The package contains the following software components.
v KillSwitch. Code to implement the kill switch traffic manager for different
server technologies.
– ASPX:
- killswitch.aspx: Page with logic.
- web.config: Configuration file that is used by the page.
– JSP:
- killswitch.jsp: Page with logic.
- config.properties: Configuration file that is used by the page.
– PHP
- killswitch.php: Page with logic.
- config.ini: Configuration file that is used by the page.
v Tealeaf Mod:
– eocore.jar: Android Core library JAR file used by module system.
– tealeafmod.jar: Android library JAR file that contains the CX Mobile
Android SDK.
– EOCoreBasicConfig.properties: Configuration file.
– TealeafBasicConfig.properties: Configuration file.
– EOCoreAdvancedConfig.json: Configuration file.
– TealeafAdvancedConfig.json: Configuration file.
v SampleCode: Contains the following versions of a sample Android application.
– DarkHoloAuto: An Android application with IBM Tealeaf CX Mobile Android
SDK integrated and auto-instrumentation.
– DarkHoloManual: An Android application with IBM Tealeaf CX Mobile
Android SDK integrated which requires manual instrumentation.
– HybridHTMLEmbedded: An Android application with IBM Tealeaf CX Mobile
Android SDK integrated with a hybrid application.
See "Sample Code" in the IBM Tealeaf Android SDK Guide.
v AndroidEclipsePlugin: An Eclipse plug-in to assist with Tealeaf integration.
Chapter 1. Tealeaf installation and implementation in an Android application
55
– tealeaf.plugin.android.site-1.0.0-SNAPSHOT.zip: The plug-in archive to be
added to your Eclipse IDE.
– tealeafandroidsdk.jar: Android library JAR file that contains
pre-instrumented Tealeaf widgets.
v TealeafTargetSimulator
– target_sim.js: Image extractor from posts in real time.
v AndroidImageCaptureTool
– Rakefile.rb: Image extractor and tagger for replay.
v TeaCuts
– teacuts.jar: Automation library.
– TeaCutsBasicConfig.properties: Configuration file that stores basic
configuration settings to assist with auto instrumentation.
– TeaCutsAdvancedConfig.json: Configuration file that stores advanced library
settings to assist with auto instrumentation.
Android development environment requirements
To develop Android applications with the Android SDK, follow these system and
software requirements.
Minimum requirements
Develop Android applications with a minimum Android 4.1 or later.
Consult the Google Android Dev Center for the latest Android technical
documentation and tools.
IBM Tealeaf client frameworks do not support forwarding of application data to
third-party systems. Application data must be forwarded to the server that hosts
the native application.
Supported operating systems
Tealeaf supports these versions of the Windows, Mac, and Linux operating
systems:
v Windows XP (32-bit), Vista (32- or 64-bit), or Windows 7 (32- or 64-bit)
v Mac OS X 10.5.8 or later (x86 only)
v Linux (tested on Ubuntu Linux, Lucid Lynx)
– GNU C Library (glibc) 2.7 or later is required.
– On Ubuntu Linux, version 8.04 or later is required.
– 64-bit distributions must be able to run 32-bit applications. For information
about how to add support for 32-bit applications, see the Ubuntu Linux
installation notes.
Android Studio
Tealeaf supports the latest version of Android Studio.
Android Framework API
Tealeaf requires Android Framework API level 23 or higher.
56
IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide
Tealeaf impact on Android device resources
In benchmark tests, the Android SDK has the following effects on resources of the
visitor's device.
v 2-3% more memory consumption
Note: If the Tealeaf server is unreachable, the SDK saves Tealeaf data to memory
until the Tealeaf 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.
v Minimal effect on battery life
Add Eclipse Tealeaf plug-in to your Eclipse Android project
After you acquire IBM Tealeaf Android SDK, install the Android SDK libraries into
an Android application project.
Your Eclipse project must include the recommended Android SDK frameworks.
Plug-in installed widgets
When you install the Eclipse Tealeaf plug-in, several widgets are installed. These
widgets already have Tealeaf logging setup. This table lists and describes the
widgets that are installed:
Widget
Description
AutoCompleteTextView
An editable text view that shows completion
suggestions automatically while the user is
typing.
Button
Represents a push-button widget.
CheckBox
A two-states button that can be either
checked or unchecked.
DatePicker
A widget for selecting a date by selecting a
year, month, and day.
EditText
A thin veneer over TextView that configures
itself to be editable.
ExpandableListView
A view that shows items in a vertically
scrolling two-level list.
HorizontalScrollView
Layout container for a view hierarchy that
can be scrolled by the user, allowing it to be
larger than the physical display.
ImageButton
Displays a button with an image (instead of
text) that can be pressed or clicked by the
user.
ImageView
Displays an arbitrary image, such as an icon.
LinearLayout
A Layout that arranges its children in a
single column or a single row.
ListView
A view that shows items in a vertically
scrolling list.
Chapter 1. Tealeaf installation and implementation in an Android application
57
Widget
Description
MultiAutoCompleteTextView
An editable text view, extending
AutoCompleteTextView, that can show
completion suggestions for the substring of
the text where the user is typing instead of
necessarily for the entire thing.
RadioButton
A radio button is a two-states button that
can be either checked or unchecked.
RadioGroup
This class is used to create a
multiple-exclusion scope for a set of radio
buttons. Checking one radio button that
belongs to a radio group clears any
previously checked radio button within the
same group.
RatingBar
An extension of SeekBar and ProgressBar
that shows a rating in stars.
RelativeLayout
A Layout where the positions of the children
can be described in relation to each other or
to the parent.
ScrollView
Layout container for a view hierarchy that
can be scrolled by the user, allowing it to be
larger than the physical display.
SeekBar
An extension of ProgressBar that adds a
draggable thumb.
Spinner
A view that displays one child at a time and
lets the user pick among them.
Switch
A two-state toggle switch widget that can
select between two options.
TextView
Displays text to the user and optionally
allows them to edit it.
TimePicker
A view for selecting the time of day, in
either 24 hour or AM/PM mode.
ToggleButton
Displays checked/unchecked states as a
button with a "light" indicator and by
default is accompanied with the text "ON"
or "OFF".
Adding the Eclipse Tealeaf plug-in to your project
You install the Eclipse Tealeaf plug-in JAR file in your Eclipse project to use Tealeaf
with your project.
Before you begin, you must install:
v Eclipse
v Java
v Android Development Toolkit
You must also have the location of the Eclipse Tealeaf plug-in installation files.
At the end of this task you are asked to restart Eclipse. Do this task when
restarting Eclipse will not impact your work.
1. Extract the TLFLibRelease.zip file. The Tealeaf folder is extracted. The Tealeaf
folder contains all necessary files for the Android SDK and the plug-in.
58
IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide
2. Open your project in Eclipse.
3. From the Help menu, select Install New Software...
4. In the Install window, select Add....
5. In the Add window define the repository for the Eclipse Tealeaf plug-in files:
a. Enter a name for the Tealeaf and plug-in repository that you are creating.
b. Enter the location of the files. If the files are on your local machine, select
Local... and navigate to the files. If the files are in a compressed file or JAR
file on your local machine, select Archive... and navigate to the files. If the
files are on a website, enter the URL for the website in the Location: field.
c. Click OK.
6. In the Install window, select the files to install and click Next.
7. Accept the license agreement.
8. Click Finish to complete the installation.
9. When prompted, restart Eclipse.
Converting your project to Android+Tealeaf
After you install the Tealeaf software in Eclipse and restart Eclipse, you convert
your project to an Android + Tealeaf project. The convert process installs JAR and
properties files in your project and installs a custom widgets library that you can
use with your project. The first time you convert a project, you are prompted for
the JAR file that installs the Tealeaf Android library file.
1. Open your project in Eclipse.
2. Right-click on your project and select Configure > Convert to Android +
Tealeaf project.
3. If this is the first time that you are using the plug-in you are asked for the
Tealeaf SDK:
a. Navigate to the repository where the Tealeaf software is located.
b. Select the tealeafandroidsdk.jar file.
c. Click Open.
4. In your project, open the Custom & Library Views.
5. Click Refresh to see the custom widgets that were added.
Configure Tealeaf properties
You must configure several items for your app for use with Tealeaf, including how
screen layouts are logged, target-page location, kill-switch location, and whether to
log gestures.
EOCoreBasicConfig.properties and TealeafBasicConfig.properties are located in
the Assets folder and contain configuration settings. To customize your
configuration, you can use a text editor to modify the values for each property in
EOCoreBasicConfig.properties and TealeafBasicConfig.properties.
Note: The following table provides a list of Tealeaf properties that must be
configured to work with your application:
Chapter 1. Tealeaf installation and implementation in an Android application
59
Table 9. Tealeaf properties that must be configured.
Required Tealeaf property
Description
Whether to display logcat messages.
This setting is enabled or disabled with the
DisplayLogging property in
EOCoreBasicConfig.properties.
v To display logcat messages, set
DisplayLogging=true.
v 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:
v 0 turns off logging.
v 1 is the lowest logging level.
LoggingLevel=1 is the default setting.
v 3 is the highest logging level.
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
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.
v To enable the kill switch:
1. Set KillSwitchEnabled=true.
2. Set KillSwitchUrl=<URL> to the URL
for the kill switch for your application.
v To disable the kill switch, set
KillSwitchEnabled=false.
Set target URL
60
IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide
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 Tealeaf. The person that sets up Tealeaf
on the server creates the target page. The
target page is set with the PostMessageUrl
property in TealeafBasicConfig.properties.
Table 9. Tealeaf properties that must be configured. (continued)
Required Tealeaf property
Description
Set how screen layouts are logged
Tealeaf can log screen images as Base64 or
as MD5 checksum with PNG or JPG images.
v To capture Base64 data, set
GetImageDataOnScreenLayout=true in
TealeafBasicConfig.properties.
v 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
Tealeaf. You must apply instrumentation as
part of your application development.
Configuring Tealeaf properties for your application
You configure Tealeaf to use specific URLS for logging events and to control
message flow, set how screen layouts are logged, modify 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.
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.
How to dynamically update configuration values
You can manually update configuration values by editing
EOCoreBasicConfig.properties and TealeafBasicConfig.properties, or you can
dynamically update the 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:
Chapter 1. Tealeaf installation and implementation in an Android application
61
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 a Tealeaf configuration value that is
stored in TealeafBasicConfig.properties:
EOCore.updateConfig(“key”, “value”,
TealeafEOLifecycleObject.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.
Extended Android classes
You extend Android classes to provide logging for components in your application.
You can extend the classes with the IBM Tealeaf extended classes or you can
manually change your files to integrate Tealeaf snippets into the library. If you
install the Tealeaf SDK, you must extend the Application and Activity classes.
When you install the Eclipse Tealeaf plug-in, you must extend only the Activity
class. How you extend the classes depends on whether you have custom
Application or Activity classes.
Application class
You extend the Activity class to automatically capture points the lifecycle of a
native Android application page. Tealeaf listens to these events:
v onLowMemory - disable the library when you get a LowMemory warning
v onCreate - initialize the library when the application starts
v 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:
v Do not have a custom Application class for your application, use the IBM
Tealeaf class UIApplication. You do this only if you are not using the Eclipse
Tealeaf plug-in. The plug-in automatically extends the Application class with the
Tealeaf UICApplication class.
v Have a custom Activity class for your application, modify your custom
Application class to point to the Tealeaf UICApplication class.
Application class and the Eclipse Tealeaf plug-in
After you install the Eclipse Tealeaf 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. Tealeaf listens to these events:
62
IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide
v onPause - what happens when the application goes to the background
v onResume - what happens when the application goes to the foreground
v 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:
v Do not have a custom Activity class for your application, use the Tealeaf
UIActivity class.
v Have a custom Activity class for your application, modify your custom Activity
class to point to the Tealeaf UICActivity class.
Extending the Application class with the Tealeaf UICApplication
class
If you do not have a custom Application class, you can use the IBM Tealeaf
UICApplication class to extend the Application class. The application file manages
the lifecycle of an Android application. IBM 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.
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:
a. import com.tl.uic.Tealeaf;
b. 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" />
This example shows the lines that you add to the AdroidManifest.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 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. IBM Tealeaf listens to the
following events onPause, which happen when application goes to the background,
Chapter 1. Tealeaf installation and implementation in an Android application
63
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 IBM 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.
For hybrid applications, screen captures might be missing or out of order due to
timing issues.
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. See "Reference"
in the IBM Tealeaf Android SDK Guide.
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.
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:
a. Import com.tl.uic.Tealeaf;
b. Import com.tl.uic.app.UICApplication;
3. In the onCreate() method, add:
a. Add this.setTakeSnapshotAfterCreate(true); //To enable automatic
screen shots.
b. Add setLogicalPageName("LoginPage") //Recommended to identify page.
c. Add setImageBackground(-16777216) //To set to black background of
screenshot because the screen capture background is transparent.
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 to point to the Tealeaf
UICApplication class
If you have a custom Application class in your application, point your custom class
to the Tealeaf UICApplication class. The application file manages the lifecycle of an
Android application. IBM Tealeaf manages the library by listening to
64
IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide
onLowMemory to disable library if you get a warning, onTerminate to clean up
library, and onCreate to initialize the library. .
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():
a. Add Tealeaf tealeaf = new Tealeaf(this);, which initializes the IBM
Tealeaf library with a reference to application instrumented.
b. Add Tealeaf.enable(); that initializes capture of user actions in the
application.
4. In onLowMemory():
a. Add Tealeaf.onLowMemory(); before super so it can adjust the library due
to low memory.
5. In onTerminate():
a. 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" />
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();
}
}
Extending your custom Activity class to point to the Tealeaf
UICActivity class
If you have a custom Activity class, extend it to point to the Tealeaf UICActivity
class. The activity file manages the lifecycle of a page in a native Android
Chapter 1. Tealeaf installation and implementation in an Android application
65
application similar to what a page does in a web application. IBM 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.
Each activity needs a logical page name that helps indicate what activity is being
displayed. If no logical page name is given, IBM Tealeaf recommends using class
name that gives some indication what activity is being displayed.
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 this import:
a. Import com.tl.uic.Tealeaf;
3. Add the logical page name to the class:
private String logicalPageName;
public final String getLogicalPageName() {
if ((this.logicalPageName == null) ||
(this.logicalPageName.equals(""))) {
this.logicalPageName =
this.getClass().getName().substring(this.getClass()
.getName().lastIndexOf(".") + 1);
}
return this.logicalPageName;
}
4. In the onPause() method, add:
a. Add Tealeaf.onPause(this, getLogicalPageName());
5. In the onResume() method, add:
a. Add Tealeaf.onResume(this, getLogicalPageName());
6. In the onDestroy() method, add:
a. Add Tealeaf.onDestroy(this, getLogicalPageName());
This example shows the lines that you add to the file that extends your custom
Activity class:
import com.tl.uic.Tealeaf;
public class BaseActivity extends Activity {
private String logicalPageName;
/**
* Logical page name of the Activity.
*
* @return Logical page name of the Activity.
*/
public final String getLogicalPageName() {
if ((this.logicalPageName == null) ||
(this.logicalPageName.equals(""))) {
this.logicalPageName =
this.getClass().getName().substring(this.getClass().
getName().lastIndexOf(".") + 1);
}
return this.logicalPageName;
}
/**
* Logical page name of the Activity.
*
* @param logicalPageName
*
Logical page name of the Activity.
*/
66
IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide
public final void setLogicalPageName(final String logicalPageName) {
this.logicalPageName = logicalPageName;
}
protected void onPause() {
Tealeaf.onPause(this, getLogicalPageName());
super.onPause();
}
protected void onResume() {
Tealeaf.onResume(this, getLogicalPageName());
super.onResume();
}
protected void onDestroy() {
Tealeaf.onDestroy(this, getLogicalPageName());
super.onDestroy();
}
}
Implement Tealeaf
After you install Tealeaf, you complete several tasks to implement Tealeaf functions
in your application. These tasks involve modifying your application to capture
controls, events, and screen views.
Implementation tasks
After you install the SDK, you must complete more tasks to implement the SDK.
All of these tasks must be done for both the Tealeaf SDK and Eclipse Tealeaf
plug-in for Tealeaf to work. All of these tasks are manual.
This table lists and describes the tasks that you complete to implement Tealeaf in
your application:
Task
Description
Log Screen Layout for Android Mobile App
Replay
Configure logging screen layout to use JSON
data not screen captures. Includes
configuring logical pages names, alert
dialogs, and keyboard events.
Tealeaf SDK ONLY
Integrate Cordova, PhoneGap, and IBM
Worklight applications in your application.
Includes extending the Application class for
onCreate, onLowMemory, onTerminate
methods and onPause, on'Resume, and
onDestroy methods for Cordova.
Integration for Apache Cordova, PhoneGap,
and IBM Worklight applications that use
Android classes without IBM Tealeaf classes
Implementing screenViews
Implementing screenViews as segments for
pages in which the state or context can be
switched without rerendering the page.
Target page configuration
Set up the target page that acknowledges
that events are captured.
Data privacy
Specify the fields that are blocked or masked
during capture.
Configuring sessionization for Android
applications on the client
Configure how session IDs are generated.
Network traffic that is used in application
contains requests only
Tealeaf supports network traffic that is used
in applications that contain requests only.
Chapter 1. Tealeaf installation and implementation in an Android application
67
Task
Description
Configure requests in Android application
Configure Tealeaf to put session identifiers
in cookies.
Uses non-IBM Tealeaf session ID
Configure your generated session IDs to be
used when sessions are enabled or new
sessions started.
Hybrid application
Configure your application to log request
activity if you have a WebView in your
application.
Log screen layout for mobile app session replay
IBM 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 IBM 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.
v 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.
v 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.
v Draw user interactions (UI events) onto the HTML pages that are created from
the JSON data.
For more information on mobile app session replay templates, see "Native app
session replay customization" in the IBM Tealeaf CX Configuration Manual.
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
68
IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide
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/activitylifecycle/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 IBM 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.
Each AutoLayout entry has the following sub entries:
Table 10. AutoLayout sub entries.
Sub entry
Description
do
Boolean value
Indicates if the screen should be logged or not.
v true: Logs the screen.
v false: Does not log the screen.
Eaxmple: "do": true enables logging for the screen.
screenViewName
String value
Used to provide a custom identifying name that is assigned to the
logged screen in JSON. For example, the screenViewName for a
login screen might be "LoginScreen".
Example: screenViewName": "LoginScreen" sets the value of
screenViewName to LoginScreen.
Chapter 1. Tealeaf installation and implementation in an Android application
69
Table 10. AutoLayout sub entries. (continued)
Sub entry
Description
delay
Numeric value
The amount of time, in milliseconds, that is used to delay the
screen logging action. Increasing the value of this setting increases
the amount of time that must pass between when the screen is
loaded and when the screen logging action occurs. The delay value
is used for do and takeScreenShot.
Example: "delay": 500 sets the delay between screen load and
screen logging to 500 milliseconds.
takeScreenShot
Boolean
Indicates if a screen capture should be taken for the controller
class.
v true: Performs a screen capture.
v false: Does not perform a screen capture.
Example: "takeScreenShot": true turns on screen capturing for
the screen activity.
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": {
"UICAndroidControlsAppActivity": {
"do": false,
"screenViewName": "UICAndroidControlsAppActivity",
"delay": 1,
"takeScreenShot": false
},
"ControlsActivity1": {
"do": true,
"screenViewName": "CA1",
"delay": 500,
"takeScreenShot": false
70
IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide
},
"ControlsActivity2": {
"do": true,
"screenViewName": "CA2",
"delay": 1,
"takeScreenShot": false
},
"ControlsActivity3": {
"do": true,
"screenViewName": "CA3",
"delay": 1,
"takeScreenShot": false
},
"ControlsActivity4": {
"do": true,
"screenViewName": "CA4",
"delay": 1,
"takeScreenShot": false
},
"ControlsActivity5": {
"do": true,
"screenViewName": "CA5",
"delay": 1,
"takeScreenShot": false
},
"ControlsActivity6": {
"do": true,
"screenViewName": "CA6",
"delay": 1,
"takeScreenShot": false
},
"ControlsActivity7": {
"do": true,
"screenViewName": "CA7",
"delay": 1,
"takeScreenShot": false
},
"ControlsActivity8": {
"do": true,
"screenViewName": "CA8",
"delay": 1,
"takeScreenShot": false
}
},
"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"
}
}
}
},
You can also manually configure a screen to log a layout by adding the following
code snippet.
Tealeaf.logScreenLayout(activity, "Name", delayInMS);
Replaying AlertDialogs
You need to know when an alert dialog is displayed so that it can be captured
when the IBM Tealeaf API is called. The following examples show how to log the
AlertDialog.
Chapter 1. Tealeaf installation and implementation in an Android application
71
The following example shows how to log the AlertDialog if you have defined a
onShowListener:
AlertDialog.Builder alertDialogBuilder = new AlertDialog.Builder(mContext);
setCancelable(false);
alertDialogBuilder.setNegativeButton("OK", new DialogInterface.OnClickListener()
{
@Override
public void onClick(DialogInterface dialog, int which) {
Tealeaf.logDialogEvent(dialog, which, "DialogButtonClick");
dialog.dismiss();
Tealeaf.logScreenLayout(activity.getParent(), "pageName", 10);
}
});
AlertDialog dialog = alertDialogBuilder.create();
dialog.setOnShowListener(new OnShowListener() {
@Override
public void onShow(DialogInterface dialog) {
// Tealeaf API to log AlertDialog’s layout
final DialogLogScreenTask dialogLogScreenTask = new DialogLogScreenTask
(getActivity().getParent(), "AlertDialog", (Dialog)dialog);
dialogLogScreenTask.execute();
}
});
The following example shows how to log the AlertDialog if you have not defined
a onShowListener:
AlertDialog.Builder alertDialogBuilder = new AlertDialog.Builder(mContext);
setCancelable(false);
alertDialogBuilder.setNegativeButton("Ok", new DialogInterface.OnClickListener()
{
@Override
public void onClick(DialogInterface dialog, int which) {
Tealeaf.logDialogEvent(dialog, which, "DialogButtonClick");
dialog.dismiss();
Tealeaf.logScreenLayout(activity.getParent(), "pageName", 10);
}
});
AlertDialog dialog = alertDialogBuilder.create();
// Tealeaf API hooks into the onShowListener and logs the AlertDialog’s layout
Tealeaf.logScreenLayoutSetOnShowListener(activity.getParent(), dialog);
dialog.show();
Additional sample projects are included with the distribution in the
AndroidRelease/Tealeaf/SampleCode/EclipseProjects folder.
Replaying keyboard events
Android does not provide an event to understand when a soft keyboard appears
and disappears. Follow this example to make the necessary adjustments to
TextView based controls.
public static void addFocusAndRegister(TextView textView, Activity activity) {
textView.setOnFocusChangeListener(new OnFocusChangeListener() {
@Override
public void onFocusChange(View v, boolean hasFocus) {
if (hasFocus) {
InputMethodManager imm = (InputMethodManager) v.getContext()
.getSystemService(Context.INPUT_METHOD_SERVICE);
imm.showSoftInput(v, InputMethodManager.SHOW_FORCED);
72
IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide
KeyboardView keyboardView = new KeyboardView(v.getContext()
.getApplicationContext(), null);
Tealeaf.logEvent(keyboardView , Tealeaf.TLF_UI_KEYBOARD_
DID_SHOW_NOTIFICATION);
Tealeaf.logEvent(v, Tealeaf.TLF_ON_FOCUS_CHANGE_IN);
} else {
Tealeaf.logEvent(v, com.tl.uic.Tealeaf.TLF_ON_FOCUS_CHANGE_OUT);
InputMethodManager imm = (InputMethodManager) v.getContext()
.getSystemService(Context.INPUT_METHOD_SERVICE);
imm.hideSoftInputFromWindow(v.getWindowToken(), 0);
KeyboardView keyboardView = new KeyboardView(v.getContext()
.getApplicationContext(), null);
Tealeaf.logEvent(keyboardView , Tealeaf.TLF_UI_KEYBOARD
_DID_HIDE_NOTIFICATION);
}
}
});
Tealeaf.registerFormField(textView, activity);
}
EditText et = (EditText) findViewById(R.id.editText1);
addFocusAndRegister(et, this);
For more information, review ControlsActivity3.java in the Sample Code project,
UICAndroidControlsAppdarkHolo.
Supported controls
IBM Tealeaf replays the controls that are extended from the following controls. For
each control, IBM Tealeaf fills in the tlType value in the json object that is sent
back to the server.
Control
Description
ToggleButton and Switch
Uses switch template
Note: At the time of this publication, Switch
is not supported with replay when using an
IBM Tealeaf on-premise Replay server.
RadioGroup and RadioButton
Uses RadioButton template
Note: At the time of this publication,
RadioButton is not supported with replay
when using an IBM Tealeaf on-premise
Replay server.
CheckBox
Uses checkBox template
Button
Uses button template
Scroller, HorizontalScrollView, ScrollView
Uses scroll template
AbsSeekBar
Uses slider template
ProgressBar
Uses progressSpinner or progressBar
template
AbsSpinner
Uses selectList template
EditText
Uses label template
TextView
Uses switch template
ImageView
Uses image template
FrameLayout, LinearLayout, ViewStub, View Uses canvas template
AbsListView
Uses grid template
AlertDialog
Uses alert template
Chapter 1. Tealeaf installation and implementation in an Android application
73
Control
Description
TabWidget
Uses tabBar template
TabHost
Uses tabContainer template
Integration for Apache Cordova, PhoneGap, and IBM Worklight
applications using Android classes without IBM Tealeaf classes
This method has developers add code snippets that help the IBM Tealeaf capture
library.
android.app.Application file code changes:
The application file manages the lifecycle of an Android application. IBM 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. IBM
Tealeaf recommends this as a best practice.
Locating the file that extends from android.app.Application
This file most likely will not exist so you must create it and add it to listen to the
complete lifecycle of an Android application to control library and log information
needed.
1. Create application class from android.app.Application and add the following.
If application class is found, then continue to the next steps.
2. Open the existing Java file that extends from android.app.Application class.
3. Add the following imports.
a. import com.tl.uic.Tealeaf;
b. import com.tl.uic.app.UICApplication;
4. In onCreate():
a. Add Tealeaf tealeaf = new Tealeaf(this);, which initializes the Tealeaf
library with a reference to application instrumented.
b. Add Tealeaf.enable(); that initializes capture of user actions in the
application.
5. In onLowMemory():
a. Add Tealeaf.onLowMemory(); before super so it can adjust library due to
low memory.
6. In onTerminate()::
a. Add Tealeaf.disable(); before super so it can disable library.
7. Adjust AndroidManifest.xml to indicate application class, by adding
android:name=".MyApplication".
Example in 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();
}
74
IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide
@Override
public void onLowMemory() {
Tealeaf.onLowMemory();
super.onLowMemory();
}
@Override
public void onTerminate() {
Tealeaf.disable();
super.onTerminate();
}
}
Example in AndroidManifest.xml
<application
android:label="@string/app_name"
android:debuggable="true"
android:icon="@drawable/icon"
android:name=".TLWorklightTealeafApplication" >
org.apache.cordova.DroidGap, com.worklight.androidgap.WLDroidGap file code
changes:
The file extends from Activity class, which manages the lifecycle of a page in a
native Android application similar to what a page does in a web application.
IBM 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.
Locating the file that extends from org.apache.cordova.DroidGap,
com.worklight.androidgap.WLDroidGap
1. Open the existing Java file that extends from android.app.Activity.
2. Add the following imports.
a. import com.tl.uic.Tealeaf;
b. import com.tl.uic.app.UICApplication;
c. import com.tl.uic.model.ScreenviewType;
3. Each activity needs a logical page name that helps indicate what activity is
currently being displayed. If no logical page name is given, IBM Tealeaf
recommends to use class name that gives some indication what activity is being
display.
Add the following to class:
private String logicalPageName = "MainPage";
4. In onPause() method:
a. Add Tealeaf.onPause(this, logicalPageName);
5. In onResume() method:
a. Add Tealeaf.onResume(this, logicalPageName);
6. In onDestroy() method:
a. Add Tealeaf.onDestroy(this, logicalPageName);
7. In onCreate(), add after super.onCreate(
a. Tealeaf.logScreenview(this, logicalPageName, ScreenviewType.LOAD);
Chapter 1. Tealeaf installation and implementation in an Android application
75
b.
appView.addJavascriptInterface(new
JavaScriptInterface(this.getContext(),
Tealeaf.getPropertyName(webviewObject).getId()), "tlBridge");
Example from IBM Worklight
package com.TLWorklightTealeaf;
import android.os.Bundle;
import
import
import
import
com.tl.uic.Tealeaf;
com.tl.uic.javascript.JavaScriptInterface;
com.tl.uic.model.ScreenviewType;
com.worklight.androidgap.WLDroidGap;
public class TLWorklightTealeaf extends WLDroidGap {
private String logicalPageName = "MainPage";
@Override
public void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
// Log Screenview for this activity
Tealeaf.logScreenview(this, logicalPageName, ScreenviewType.LOAD);
//DeviceAuthManager.getInstance().setProvisioningDelegate(<Use default
ProvisioningDelegateImpl class or replace with your
IProvisioningDelegate implementation>);
// Add bridge for Tealeaf data to be sent back
appView.addJavascriptInterface(new JavaScriptInterface(this.getContext(),
Tealeaf.getPropertyName(webviewObject).getId()), "tlBridge");
super.loadUrl(getWebMainFilePath());
}
public void onPause() {
// Handle Tealeaf during onPause event
Tealeaf.onPause(this, logicalPageName);
super.onPause();
}
public void onResume() {
// Handle Tealeaf during onResume event
Tealeaf.onResume(this, logicalPageName);
super.onResume();
}
public void onDestroy() {
// Handle Tealeaf during onResume event
Tealeaf.onDestroy(this, logicalPageName);
super.onDestroy();
}
}
Implementing screenViews
For pages in which the state or context can be switched without re-rendering the
page, IBM Tealeaf segments the data between states by using a screenView object.
For example, if a page contains multiple tabs, each of which represents a different
stage in a checkout process, you instrument each tab in the page as a distinct
screenView.
To implement a screenView for a page, complete the following steps.
76
IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide
1. If you are extending from UICActivity, set a logicalPageName to indicate the
use of the activity. Otherwise, logicalPageName is set to the name of the class of
the activity.
2. If the prior step is not complete, call Tealeaf.logScreenview and pass the
logicalPageName. You must also indicate if the page being loaded and unloaded
is optional. For example:
Tealeaf.logScreenview(activity, logicalPageName, ScreenviewType.LOAD);
Tealeaf.logScreenview(activity, logicalPageName, ScreenviewType.UNLOAD);
Basic configuration
You must set up a target page on your web server.
See “Quick start for server configuration” on page 89.
Set the target page's address in the TealeafBasicConfig.properties configuration
file under the key PostMessageUrl.
See "Configuration File" in the IBM Tealeaf Android SDK Guide.
Data privacy
IBM Tealeaf provides mechanisms for masking or blocking sensitive customer
information, such as credit card numbers, from being transmitted and captured by
IBM Tealeaf. Through the Android SDK, you can specify the fields that need to be
blocked or masked in your web application.
When applied, data privacy ensures that these data elements are never transmitted
to IBM Tealeaf.
Note: Due to changes in how client framework data is submitted to IBM Tealeaf
for capture, the best method for masking or blocking sensitive data is to apply the
filtering through the capturing client framework. While other IBM Tealeaf features
to manage data privacy can be deployed, they are not easy to implement on the
new format of data captured from the client frameworks. IBM Tealeaf recommends
using the methods referenced below.
v See "Configuration File" in the IBM Tealeaf Android SDK Guide.
v For more information about handling sensitive data in general, see "Managing
Data Privacy in Tealeaf CX" in the IBM Tealeaf CX Installation Manual.
Configuring sessionization for Android applications on the client
The Android SDK auto-generates a session ID if one is not provided. This session
ID is used to identify the session on the IBM Tealeaf server.
IBM Tealeaf injects cookies to create session in the IBM Tealeaf system.
Note: When an Android native or hybrid application is placed into background,
the library flushes the collected data and sleeps, instead of disabling it. This
happens unless the session expired due to the session timeout property. The
timeout property is indicated with SessionTimeout in
TealeafBasicConfig.properties. The default value for this property is 30 minutes.
After a 30-minute timeout, a new session identifier is created.
There are two ways to configure sessionization; either through TLTSID provide by
IBM Tealeaf, or through customer session ID, called JSESSIONID. Both methods
Chapter 1. Tealeaf installation and implementation in an Android application
77
function as a unique session identifier within the Android SDK environment for
IBM Tealeaf to track on customer sessions. CookieParam can be set to use customer
session ID or JSESSIONID.
The following is a typical setting in TealeafBasicConfig.properties using
customer session ID.
#Sessionization settings on customer cookies
CookieUrl = http://www.sample.com
CookieDomain = .sample.com
CookiePath = /
CookieParam = JSESSIONID
CookieExpires = false
SessionTimeout=30
SessoinTimeoutKillSwitch=false
In this example, the cookie expires 30 minutes from current time. When the session
timeout occurs, Android SDK retrieves the new cookie from your application
server and posts the rest of request to application server using this new acquired
cookie in request header. PCA groups all the used JSESSIONIDs into one single
session even though the JSESSIONID was consistently changing. When using
cookies generated from customer application server, SessoinTimeoutKillSwitch can
be set to true or false. Setting the SessoinTimeoutKillSwitch to false means the
session timeout user does not go to recheck on KillSwitchUrl to see if it is
responding.
Network traffic used in application contains requests only:
Android SDK uses cookies to add values to the TLFConfigurableItems.properties
file.
Uses session ID generated by IBM Tealeaf Android SDK
Android SDK uses cookies to add the following values in
TLFConfigurableItems.properties.
v CookieUrl is for url of site that is posted and getting cookie to sessionize on.
v CookieParam is the parameter that has a session id.
v CookiePath is the path of the cookie.
v CookieDomain is the domain that the cookie belongs to.
v CookieSecure is to add a secure cookie that can only be posted to an https url
that has a valid certificate.
v CookieExpiresFormat can have the date format of ASCTIME, RFC1036, or
RFC1123, which will have an expiration date of current time + session timeout
indicated in the variable below.
v SessionTimeout is session timeout is in minutes. When this value expires a new
session id is created.
An example follows.
#Sessionization settings
CookieUrl=http://m.ibm.com
CookieParam=TLTSID
CookiePath=/
CookieDomain=.ibm.com
#Whether you want to create a secure cookie which can only be sent using a
https url in PostMessageUrl.
CookieSecure=false
#Valid date formats: ASCTIME, RFC1036, RFC1123
78
IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide
CookieExpiresFormat=ASCTIME
#When post is sent, expiration of cookie will be current time + session timeout
#Session timeout is in minutes
SessionTimeout=30
Note: It is important to first call your server to get first cookie to sessionize on,
which is automatically obtained when you enable the kill switch URL on the
application. This is used to aggregate all the data on CX Passive Capture
Application capture.
Configure requests in Android application
IBM Tealeaf needs all the requests to have the session id to be placed in the
cookies of the request. This enables the IBM Tealeaf CX PCA to collect all the
resources together in a single captured session.
Add the following cookie into the GET and POST requests to enable the PCA to
listen to requests and responses.
httpClient.setRequestProperty("Cookie", Tealeaf.getTLCookie(Tealeaf.getCurrentSessionId()));
Extend org.apache.http.impl.client.DefaultHTTPClient:
If you do not use the IBM Tealeaf extended TLDefaultHttpClient class, you must
add the following code to the following classes.
import org.apache.http.conn.ClientConnectionManager;
import org.apache.http.impl.client.DefaultHttpClient;
import org.apache.http.params.HttpParams;
/**
* @author ohernandez
*
*/
public class TLDefaultHttpClient extends DefaultHttpClient {
/**
*
*/
public TLDefaultHttpClient() {
super();
this.init(null);
}
/**
* @param params Http parameters.
*/
public TLDefaultHttpClient(final HttpParams params) {
super(params);
this.init(null);
}
/**
* @param params Http parameters.
* @param sessionId Tealeaf session id.
*/
public TLDefaultHttpClient(final HttpParams params,
final String sessionId) {
super(params);
this.init(sessionId);
}
/**
* @param conman ClientConnectionManager.
* @param params Http parameters.
*/
public TLDefaultHttpClient(final ClientConnectionManager conman,
Chapter 1. Tealeaf installation and implementation in an Android application
79
final HttpParams params) {
super(conman, params);
this.init(null);
}
/**
* @param sessionId Tealeaf session id.
*/
private void init(final String sessionId) {
final TLHttpRequestInterceptor tlHttpRequestInterceptor =
new TLHttpRequestInterceptor(sessionId);
this.addRequestInterceptor(tlHttpRequestInterceptor);
this.addResponseInterceptor(new TLHttpResponseInterceptor
(tlHttpRequestInterceptor));
}
}
Extend org.apache.http.HttpRequestInterceptor:
This class is used to inject session id as a cookie and additional headers that the
IBM Tealeaf system uses.
import java.io.IOException;
import java.util.Map.Entry;
import
import
import
import
org.apache.http.HttpException;
org.apache.http.HttpRequest;
org.apache.http.HttpRequestInterceptor;
org.apache.http.protocol.HttpContext;
import android.webkit.CookieManager;
import com.tl.uic.Tealeaf;
import com.tl.uic.util.LogInternal;
/**
* @author ohernandez
*/
public class TLHttpRequestInterceptor implements HttpRequestInterceptor {
private String url;
private final String sessionId;
/**
* Constructor.
*/
public TLHttpRequestInterceptor() {
super();
this.sessionId = null;
}
/**
* Constructor.
* @param sessionId Tealeaf session id.
*/
public TLHttpRequestInterceptor(final String sessionId) {
this.sessionId = sessionId;
}
/**
* Get url of the request.
* @return Url of the request.
*/
public final String getUrl() {
return url;
}
/**
80
IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide
* Url of the request.
* @param url Url of the request.
*/
public final void setUrl(final String url) {
this.url = url;
}
/**
* {@inheritDoc}
*/
public final void process(final HttpRequest request, final
HttpContext context) throws HttpException, IOException {
try {
this.url = request.getRequestLine().getUri();
if (!request.containsHeader(Tealeaf.TLF_HEADER)) {
request.addHeader(Tealeaf.TLF_HEADER, "device (Android) Lib/"
+ Tealeaf.getLibraryVersion());
}
if (!request.containsHeader(Tealeaf.TLF_PROPERTY_HEADER)) {
request.addHeader(Tealeaf.TLF_PROPERTY_HEADER,
Tealeaf.getHttpXTealeafProperty());
}
if (Tealeaf.getAdditionalHeaders() != null) {
for (final EntryString,<String> entry :
Tealeaf.getAdditionalHeaders().entrySet()) {
request.addHeader(entry.getKey(), entry.getValue());
}
}
final StringBuffer cookies = new StringBuffer(Tealeaf.
getTLCookie(this.sessionId));
if (this.getUrl() != null) {
final String extistingCookies = CookieManager.getInstance().
getCookie(this.getUrl());
if (extistingCookies != null) {
cookies.append(’;’);
cookies.append(extistingCookies);
}
}
request.addHeader("Cookie", cookies.toString());
LogInternal.log("Session cookie:" + cookies.toString());
}catch (final Exception e) {
Tealeaf.logException(e);
}
}
}
Extend org.apache.http.HttpResponseInterceptor:
This class is used to get information to fill out a IBM Tealeaf connection object.
import java.io.IOException;
import java.util.Date;
import
import
import
import
org.apache.http.HttpException;
org.apache.http.HttpResponse;
org.apache.http.HttpResponseInterceptor;
org.apache.http.protocol.HttpContext;
import com.tl.uic.TLFCache;
import com.tl.uic.Tealeaf;
import com.tl.uic.util.LogInternal;
Chapter 1. Tealeaf installation and implementation in an Android application
81
/**
* @author ohernandez
*
*/
public class TLHttpResponseInterceptor implements HttpResponseInterceptor {
private final TLHttpRequestInterceptor tlHttpRequestInterceptor;
private final Date startTime;
private final long initTime;
/**
* Constructor.
*
* @param tlHttpRequestInterceptor TLHttpRequestInterceptor used.
*/
public TLHttpResponseInterceptor(final TLHttpRequestInterceptor
tlHttpRequestInterceptor) {
this.tlHttpRequestInterceptor = tlHttpRequestInterceptor;
this.startTime = new Date();
this.initTime = TLFCache.timestampFromSession();
}
/**
* {@inheritDoc}
*/
public final void process(final HttpResponse response,
final HttpContext context) throws HttpException, IOException {
try {
final Date endTime = new Date();
final Date startLoad = new Date();
final long loadTime = (new Date()).getTime() - startLoad.getTime();
final long responseTime = endTime.getTime() - this.startTime.getTime();
Tealeaf.logConnection(this.tlHttpRequestInterceptor.getUrl(), response,
this.initTime, loadTime, responseTime);
} catch (final Exception e) {
LogInternal.logException(e);
}
}
}
Uses non IBM Tealeaf session ID
You must get your generated session ID and use it when you enable or start a new
session in Android SDK.
// If enabling of Android Logging Framework use
Tealeaf.enable();
Tealeaf.enable("your session id");
// If Android Logging Framework is enabled and a new session is to be created use
Tealeaf.startSession();
Tealeaf.startSession("your session id");
Android application gestures
You can capture gestures that the users make on your Android application. Several
types of gestures are captured.
Configuration
For any Activity class that you want Gesture logging, you edit
TealeafBasicConfig.properties file and set the SetGestureDetector property to
true.
Touch event methods
You add your variables to one of these methods:
82
IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide
v onTouchEvent - use this method if your activity is not using a customized gesture
view.
v dispatchTouchEvent - use this method if your activity is using a customized
gesture view.
If your application uses a customized gesture view, onTouchEvent does not detect
the gestures because they are already captured by the customized gesture view. If
you are using a customized gesture view, you must use dispatchTouchEvent.
You can use either the onTouchEvent or the dispatchTouchEvent. If you use both,
the gestures are captured twice.
Gesture events captured:
Gestures that are used to select items in an application or to adjust views in the
application are captured by Tealeaf.
Tap gestures
This table lists and describes the tap gestures that are captured from web and
mobile apps.
Note: The arrows that illustrate the direction of a swipe or pinch gesture are not
supported by the Internet Explorer browser.
Table 11. Tap gestures.
Gesture name
Description
Image displayed in Replay
Tap
This gesture is a one-finger gesture.
For a tap gesture, one-finger taps and lifts
from the screen in 1 location.
Tap and Hold
This gesture is a one-finger gesture.
For a Tap and Hold gesture, one-finger
presses and stays on the screen until
information is displayed or an action
occurs.
Note: The response to a Tap and Hold
gesture can vary from one application to
another. For example, a Tap and Hold
gesture might display an information
bubble, magnify content under the finger,
or present the user with a context menu.
Double tap
This gesture is a one-finger gesture.
For a double tap gesture, one-finger taps
twice in close succession in 1 location of the
screen.
Chapter 1. Tealeaf installation and implementation in an Android application
83
Swipe gestures
This table lists and describes the swipe gestures that are captured from web and
mobile apps:
Table 12. Swipe gestures
Gesture name Description
Swipe
vertically
Image displayed in Replay
This gesture is a one-finger gesture.
For a swipe vertically gesture, one-finger:
1. taps and holds in 1 location of screen,
2. continues to engage screen while it moves
up or down
3. lifts from the screen in different location.
Note: The initial tap becomes lighter in color,
while the destination is highlighted by a
darker color
Swipe
horizontally
This gesture is a one-finger gesture.
For a swipe horizontally gesture, one-finger:
1. taps and holds in 1 location of screen,
2. continues to engage screen while it moves
left or right
3. lifts from the screen in different location.
Note: The initial tap becomes lighter in color,
while the destination is highlighted by a
darker color
Resize gestures
This table lists and describes the resize gestures that are captured from web and
mobile apps:
Note: See the IBM Tealeaf Customer Experience 9.0.1 Release Notes for information
about a known limitation for handling some iOS pinch gestures.
Table 13. Resize gestures
Gesture name
Description
Pinch open
Sometimes referred to as a spread gesture,
this is a two-finger gesture.
Image displayed in Replay
For a pinch open gesture, 2 fingers:
1. tap and hold in 1 location of the screen,
2. maintain contact with the screen while
the fingers move apart from each other
in any direction,
3. lift from the screen at a new location.
84
IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide
Note: Accompanying arrows indicate the direction
(open or close) of the pinch
Table 13. Resize gestures (continued)
Gesture name
Description
Image displayed in Replay
Pinch close
This gesture is a two-finger gesture.
For a pinch close resize gesture, 2 fingers:
1. tap and hold in 1 location on the screen,
2. maintain contact with the screen while
the fingers move toward each other,
3. lift from the screen at a new location.
Note: Accompanying arrows indicate the direction
(open or close) of the pinch
Unresponsive gesture events captured
Unresponsive gestures are gestures that do not respond when a user tries to select
items in an application or tries to adjust views in the application. Like other
gesture events, unresponsive gestures are captured by Tealeaf.
Unresponsive gestures are displayed graphically in BBR as orange outlined icons
accompanied by a circled "X" . The circled "X" denotes that the gesture was
unresponsive. For example, if a double tap gesture did not yield a response in the
mobile application, then at replay time that gesture is displayed with the following
icon in BBR:
The following table lists the unresponsive gestures that are captured from web and
mobile apps and shows the images that are displayed in BBR:
Table 14. Unresponsive gestures and icons
Unresponsive Gesture
Image displayed in Replay
Tap gestures
Unresponsive tap
Unresponsive double tap
Unresponsive tap and hold
Swipe gestures
Chapter 1. Tealeaf installation and implementation in an Android application
85
Table 14. Unresponsive gestures and icons (continued)
Unresponsive Gesture
Image displayed in Replay
Tap gestures
Swipe vertically
Note: Accompanying arrows indicate the direction of the swipe.
Swipe horizontally
Note: Accompanying arrows indicate the direction of the swipe.
Resize gestures
Pinch open
Note: Accompanying arrows indicate the direction of the pinch.
Pinch close
Note: Accompanying arrows indicate the direction of the pinch.
Instrumenting your application for Android gestures:
You can enable your application to capture gestures that the user makes on your
application. To enable gestures for an Activity class, you modify the Activity class.
86
IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide
For example, you modify the MainActivity.java file and call the
Tealeaf.dispatchTouchEvent method inside dispatchTouchEvent or onTouchEvent
method.
To use the Android gestures module, you must the Android Support Library
android-support-v4.jar together with Tealeaf SDK uicandroid.jar. The
android-support-v4.jar is distributed within Android SDK. Download and install
the Android Support Library from the Android Support Library site. The
installation installs the android-support-v4.jar at ${your Android SDK
location}/extras/android/support/v4/android-support-v4.jar
1. Open the MainActivity.java file for your application.
2. Override either the dispatchTouchEvent or the onTouchEvent method,
depending on how you are using gestures in your application:
IF your application is...
THEN...
using a customized gesture view
Override the dispatchTouchEvent
publc boolean dispatchTouchEvent
( MotionEvent e) {
Tealeaf.dispatchTouchEvent(this, e);
return super.dispatchTouchEvent(e);
}
not using a customized gesture view
Override the onTouchEvent
publc boolean onTouchEvent
( MotionEvent e) {
Tealeaf.dispatchTouchEvent(this, e);
return super.onTouchEvent(e);
}
This example shows the code snippets that are added in this task for an
application that does not use a customized gesture view:
mport com.tl.uic.Tealeaf;
import com.tl.uic.app.UICActivity;
import android.os.Bundle;
import android.view.MotionEvent;
public class MainActivity extends UICActivity{
@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_main);
Tealeaf.logScreenLayout(this, this.getLogicalPageName(), 1000);
}
public boolean dispatchTouchEvent( MotionEvent e) {
Tealeaf.dispatchTouchEvent(this,e);
return super.dispatchTouchEvent(e);
}
}
Modifying the TealeafBasicConfig.properties file for gestures:
After you define the variables for gestures in your Activity class, you enable
gesture capture by modifying the TLFConfiguratableItems.properties file.
1. Edit the TealeafBasicConfig.properties file.
Chapter 1. Tealeaf installation and implementation in an Android application
87
2. Set SetGestureDetector to true.
3. Save and exit the TealeafBasicConfig.properties file.
Log exceptions
Exceptions are the way that a system or framework communicates to the
application that something is wrong. Tealeaf provides two mechanisms to log
exceptions. You can manually log exceptions by using the logException API, or
Tealeaf SDK will automatically log uncaught exceptions. The exception information
can be used for analytics.
Automatically log exceptions
When your application throws an uncaught exception, Tealeaf Android SDK
records the stack trace and state of the device at the time the exception was
thrown. Tealeaf Android SDK sends the crash information to your target servers
for processing.
Manually log exceptions
In the Android SDK, you modify your catch block to report caught exceptions to
the target server for processing. When you modify your catch block, you get the
full stack trace and same device information that Tealeaf collects for fatal crashes.
This table shows the method that is used to log exceptions and describes the
parameters that are used in the method:
Method
Parameters
public static Boolean
logException(final
Throwable exception, final
HashMap<String, String> data,
final Boolean unhandled)
Where:
v @param exception - the exception to be
logged.
v @param data - the value to be given to
event.
v @param unhandled - whether the
exception is unhandled.
v @return - whether exception was logged.
Example
In this example, you have a method that causes an exception:
public void clientMethod1( ) {
}
You add an @try , @catch, and the Tealeaf.logException(e, data, false) method
to handle the exception:
public void clientMethod1( ) {
try {
int[] array = new int[1];
int i = array[2]; // Index out of bound exception
} Catch (Exception e) {
HashMap<String, String> data = new HashMap<String, String>();
data.put("extraMessage", "custom value1");
Tealeaf.logException(e, data, false);
}
}
88
IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide
Logging exceptions:
Use the examples in this task as a guide to adding exception logging to your
application.
1. Determine the method for which you want to log exceptions. For example, you
have a method:
public void clientMethod1( ) {
}
2. Optional: Add the exception method to the method for which you want to log
the exceptions.
Add @try , @catch, and the Tealeaf.logException(e, data, false) method to
handle the exception:
public void clientMethod1( ) {
try {
int[] array = new int[1];
int i = array[2]; // Index out of bound exception
} Catch (Exception e) {
HashMap<String, String> data = new HashMap<String, String>();
data.put("extraMessage", "custom value1");
Tealeaf.logException(e, data, false);
}
}
Quick start for server configuration
This section describes the basic steps to configure the IBM Tealeaf CX Passive
Capture Application and Windows based servers to capture and process data that
is submitted from the Android SDK.
To enable processing of submitted data, you complete the steps in the following
sections.
Target page for traffic capture
IBM Tealeaf is designed to capture traffic between a client and a web server. To
facilitate capture, you must add a target page to your web server environment to
which the Android SDK can submit posts.
You can use the same target page that is available for IBM Tealeaf CX UI Capture
for AJAX.
See "UI Capture for Ajax Installation and Implementation" in the IBM Tealeaf CX UI
Capture for AJAX Guide.
After you add the target page to your web environment and enable the
appropriate access permissions, you must configure the URL for the target page in
the TLFConfigurableItems.properties page.
Note: If needed, you can configure the client framework to submit by HTTPS by
adding the protocol identifier to the post URL. See Chapter 2, “Configuration file,”
on page 97.
Traffic volume management
You can add a sampling function to work with the Android SDK KillSwitch. You
can use this sampling function to throttle the sampling rate and thus the volume of
traffic that is forwarded for capture.
Chapter 1. Tealeaf installation and implementation in an Android application
89
For more information about sampling functions for various server environments,
see "Sample Code" in the IBM Tealeaf Android SDK Guide.
CX Passive Capture Application traffic capture verification
You verify that the IBM Tealeaf CX Passive Capture Application in your IBM
Tealeaf environment is configured to capture and process the data that is submitted
from the Logging Frameworks.
The data is submitted using specific content types, which the CX Passive Capture
Application is typically configured to capture by default. You must verify that
these content types were enabled for capture through the CX Passive Capture
Application Web Console.
Note: After the completion of the steps in this section, data is processed by IBM
Tealeaf.
Verifying CX Passive Capture Application capture type
configuration
You use this procedure to verify that the CX Passive Capture Application is
configured to capture the content types submitted by the Android SDK.
Note: Depending on the version of the CX Passive Capture Application you
installed, the required content types may already be configured for capture.
The Android SDK submits messages using the text/json content type.
Note: Each IBM Tealeaf Logging Framework can use a different content type for
submitting events for capture to IBM Tealeaf. Be sure to review and verify the
content type for each deployed client framework.
1. Log in to the CX Passive Capture Application web console:
<PCAServer>:8080
where
<PCAServer> is the host name of the CX Passive Capture Application server.
2. Click the Pipeline tab.
3. Click Edit Type Lists.
4. In the Capture All POST Types box, verify that the following values ae
included:
text/json
text/x-json
application/json
application/x-json
5. Click Add.
6. The CX Passive Capture Application is now configured to capture the required
content types. All subsequent hits of this type are captured.
7. Save changes.
See "PCA Web Console - Pipeline Tab" in the IBM TealeafCX Passive Capture
Application Manual.
90
IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide
Configuring CX Passive Capture Application for Logging
Framework screen captures
Optionally, you can enable the Android SDK to capture screen captures during the
initial load of each view or screen of your web application. These screen captures
are forwarded to the IBM Tealeaf Target Page in .PNG format for capture and use
during session display.
See “UICActivity class” on page 113.
When this option is enabled, you must configure the CX Passive Capture
Application to capture these screen captures. By default, the CX Passive Capture
Application drops capture of binary or static content, so you must configure it to
capture these images that are submitted as binary POSTs to the target page.
1. Log in to the CX Passive Capture Application web console:
<PCAServer>:8080
Where
<PCAServer> is the host name of the CX Passive Capture Application server.
2. Click the Pipeline tab.
3. Click Edit Type Lists.
4. In the Excluded File Extensions list, verify that png is listed.
5. In the Included File Extensions list, verify that png is not listed.
Note: If a file extension is included in this list, then all instances that are sent
as responses are captured, which greatly expands the volume of data that is
captured by the CX Passive Capture Application. Capture in this manner is not
required.
6. In the Binary POST Types box, enter the following value:
image/png
7. Click Add.
8. The image/png POST type is added and enabled for capture. This setting allows
the PNG posts to be captured by the CX Passive Capture Application.
9. Save changes.
See "PCA Web Console - Pipeline Tab" in the IBM Tealeaf CX Passive Capture
Application Manual.
Enabling automated extraction of compressed POSTs
The Android SDK automatically compresses POST data. You must configure the
CX Passive Capture Application to extract them.
Note: For CX Passive Capture Application Build 3502 or later, this decompression
is done automatically. If you are using one of these CX Passive Capture
Application builds, this configuration step is not necessary.
1. In the CX Passive Capture Application Web Console, click the Pipeline tab.
2. Select Inflate compressed requests and responses.
3. Save changes.
The compress POSTs are now automatically extracted by the CX Passive Capture
Application and processed normally.
Options for monitoring captures and processing
You use different tools for testing your configuration and monitoring captures on
an ongoing basis.
Chapter 1. Tealeaf installation and implementation in an Android application
91
At target page
You can test the basic functionality of the target page by triggering GET and POST
actions on the URL where the target page was installed.
See "UI Capture for Ajax Installation and Implementation" in the IBM Tealeaf CX UI
Capture for AJAX Guide.
In Windows pipeline
You can monitor the capture and processing of hits in the Windows pipeline in real
time through the IBM Tealeaf Management System. See "TMS Pipeline Status Tab"
in the IBM Tealeaf cxImpact Administration Manual.
Configuring sessionization for Android applications in IBM
Tealeaf
IBM Tealeaf provides multiple mechanisms for identifying and tracking individual
visitor sessions. For the Android SDK, more configuration can be required.
Review the following steps and complete any necessary ones to sessionize your
mobile application.
To enable sessionization of hits that are captured through the Android SDK, you
must deploy the Sessioning session agent. See "Sessioning Session Agent" in the
IBM Tealeaf CX Configuration Manual
1. Log in to the Portal as an administrator.
2. From the Portal menu, select Tealeaf > TMS. The IBM Tealeaf Management
System opens.
See "Tealeaf Management System" in the IBM Tealeaf cxImpact Administration
Manual.
3. Click the WorldView tab.
4. For the View, select Servers.
See "TMS WorldView Tab" in the IBM Tealeaf cxImpact Administration Manual.
5. Click the Transport Service node.
6. Select Transport Service configuration. Then, click View/Edit.
7. The Pipeline Editor opens.
Note: Verify that the Sessioning session agent was installed.
v If it was not installed, drag it from the Available SessionAgents window to
the pipeline.
v For more information about deploying it, see "TMS Pipeline Editor" in the
IBM Tealeaf cxImpact Administration Manual.
8. Select the Sessioning session agent. Click Edit.
9. In the Sessioning session agent configuration, modify the PrimarySessField
value as follows:
PrimarySessField=AppEnv:SessionID,env:HTTP_X_TEALEAF
10. Save the configuration file.
11. Push the change to all servers. A restart is needed for the new sessionization
keys to take effect.
92
IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide
Android view name as URL during replay
Errors that can occur during session replay can be resolved by using the Android
view name as the URL during replay.
When you attempt to replay a session captured by the Android SDK, an error
message can indicate that there are no viewable pages in the session. This error is
related to the manner in which pages on Android devices are mapped.
Instead of displaying the URL during replay, you can configure IBM Tealeaf replay
clients to show the Android view name instead, which eliminates this cosmetic
error message.
To use the Android view name as the URL when you replay the session, complete
the following steps to configure the appropriate replay profile rule.
Note: Currently, configuration of this rule must be applied through the replay
profile that is stored on the Replay Server. Instructions follow.
When this change is applied, the Navigable Pages list in Replay view in Browser
Based Replay and CX RealiTea Viewer is populated with the Android view name
as the URL, instead of the generic IBM Tealeaf Target page URL.
v Browser Based Replay, or BBR
This web-based replay client is accessible through the IBM Tealeaf Portal and
retrieves its sessions through the Replay Server in your IBM Tealeaf
environment.
– See "CX Browser Based Replay" in the IBM Tealeaf cxImpact User Manual.
– See "Configuring the Replay Server" in the IBM Tealeaf CX Configuration
Manual.
v IBM Tealeaf CX RealiTea Viewer, or RTV
This replay client is a stand-alone Windows application that must be installed
separately on your desktop. Through CX RealiTea Viewer, you can search for
and replay sessions that are stored in your IBM Tealeaf environment.
See the IBM Tealeaf CX RealiTea Viewer User Manual.
To change the replay profile, you can use these options.
v “Applying the view name change locally”
You can apply the change locally through the IBM Tealeaf CX RealiTea Viewer, a
desktop application for viewing and replaying events. You can use this option to
test the change before you reconfigure the Replay Server.
v “Applying the view name change to the Replay Server” on page 94
If you do not have access to CX RealiTea Viewer, you can change server settings.
Note: CX RealiTea Viewer users must synchronize their local replay profiles to
the server profile to acquire the change.
Applying the view name change locally:
Complete the following steps in CX RealiTea Viewer to make changes locally and
test use of the Android view name during replay.
1. Start the CX RealiTea Viewer application on your local desktop.
Chapter 1. Tealeaf installation and implementation in an Android application
93
Note: CX RealiTea Viewer must be installed locally on your Windows
desktop. See "RealiTea Viewer (RTV) User Manual" in the IBM Tealeaf CX
RealiTea Viewer User Manual.
2. Load a session that is captured from the Android SDK.
3. From the CX RealiTea Viewer menu, select Tools > Options....
4. Click the Profiles tab.
See "RealiTea Viewer - Profile Options" in the IBM Tealeaf CX RealiTea Viewer
User Manual.
5. If you did not do so already, enter the name of the Replay Server that controls
the replay profile in the Server check box. Click Check for Updates Now.
If a server version of the profile is available, your local version is
synchronized to it.
6. Click Edit Raw Profile.
7. Complete the editing steps that are listed in the section that follows. You are
editing the raw XML file that is stored on your local desktop. See “Applying
the view name change to the Replay Server.”
8. After editing the profile as required, click Save Changes & Exit.
9. Click OK.
10. Replay the session. Click Replay in the toolbar.
11. In the Navigable Pages list, the listed URLs reflect the Android view name for
the screen.
12. If the Navigable Pages list is being populated accurately, you can send your
changes back to the Replay Server for deployment to other replay users.
a. From the RTV menu, select Tools > Options.
b. Click the Profiles tab.
c. Click Upload Settings to Server.
Applying the view name change to the Replay Server:
Complete the following steps on the Replay Server so that all Browser Based
Replay users see the Android view name during replay.
In the following steps, you apply the change to the Replay Server by accessing the
server and editing the appropriate file. This change is then available to all users of
the Replay Server's profile, which includes all Browser Based Replay users.
94
IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide
1. Log in to the server hosting the Replay Server as an administrator.
2. Edit the following file:
<Tealeaf_install_directory>\system\ReplayServerProfile.xml
3. Locate the RequestMapping section, which should be near the top of the file.
4. Add a Request Mapping, URL element entry. Locate the following header:
<RequestEntry name="URL">
5. Add the following key name as a new entry to the list of entries:
<Key name="HTTP_X_TEALEAF_VIEW_CLASS" enabled="1"/>
6. Save the file.
Runtime configuration
As needed, you can change server-side settings from the client application. All
configuration items can be configured dynamically from the client.
You can plan to manage server configuration during initialization of the
application, then update it selectively and as needed during run time.
See "TeaLeaf Class" in the IBM Tealeaf Android SDK Guide.
IBM Tealeaf events for Android SDK
The JSON format is used to track data that is captured by the Android SDK.
Data type
Description
Client Framework data (JSON)
If you are using step-based eventing, data from the client framework is
submitted in JSON format and is available through Browser Based Replay
for review and eventing. See "Step-Based Eventing" in the IBM Tealeaf Event
Manager Manual.
For a walk-through of how to capture this data into IBM Tealeaf events,
see "Integrating Client Framework Data into Tealeaf" in the IBM Tealeaf
Client Framework Data Integration Guide.
Client Framework data (hit-splitting)
See “Client Framework versions supported in this documentation” on page
2.
Upgrading the Android SDK
When you upgrade the IBM Tealeaf Android SDK, you complete the following
general tasks.
Note: Some steps can vary depending on your development and application
environments. The following example uses Eclipse as the development
environment.
1. Review current requirements. See Minimum requirements.
2. Review the package contents. See “Tealeaf package contents” on page 2.
3. If you are using a version of the IBM Tealeaf Android SDK that is earlier than
10.1.0, remove uicandroid.jar and TLFConfigurableItems.properties from the
project lib and assets folders.
Chapter 1. Tealeaf installation and implementation in an Android application
95
4. Add encore.jar and tealeafMod.jar to your project libraries. From your
Eclipse project, select Build Path > Configure Build Path > Android, add
encore.jar and tealeafMod.jar as libraries to your project.
5. Add TealeafBasicConfig.properties, TealeafAdvancedConfig.json,
EOCoreBasicConfig.properties, and EOCoreAdvancedConfig.json as assets in
your project. From your Eclipse project select Assets > General > Choose file
system > Next, then add TealeafBasicConfig.properties,
TealeafAdvancedConfig.json, EOCoreBasicConfig.properties, and
EOCoreAdvancedConfig.json.
6. Edit PostMessageUrl in TealeafBasicConfig.properties to point your target
server.
After completing the upgrade procedure, use the following steps to verify the
installation.
1. Verify that the appropriate content types are being captured and forwarded by
the IBM Tealeaf CX Passive Capture Application. See “CX Passive Capture
Application traffic capture verification” on page 90.
Note: This step turns on the switch to begin capturing and processing data
from the mobile application into Tealeaf. Depending on the volume of data,
you can use the kill switch. See “Traffic volume management” on page 89.
2. Verify that your application environment is configured to meet the project
requirements.
3. Verify that the requirement code changes were applied. See Android project
changes.
4. Apply the basic configuration.
Note: The latest version of the Android SDK includes new configuration
requirements. See “Basic configuration” on page 33.
5. Test your upgraded solution.
96
IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide
Chapter 2. Configuration file
The configuration files for the Android SDK library are placed into the asset folder
of an Android application. The configuration files are saved Java properties files
and are named TealeafBasicConfig.properties and
EOCoreBasicConfig.properties.
Application key
An application key (AppKey) setting is used to identify and sessionize the mobile
application with Tealeaf Customer Experience on Cloud.
For SaaS applications, you need to know if SaaS is using Tealeaf cookies for
sessionization. If the Tealeaf cookies are used, you need to provide a cookie name
and application key. You can use TLTSID as the cookie name. Contact your Tealeaf
SaaS administrator for the value of the application key.
Note: It is recommended that each mobile application is assigned a unique
application key. However, application keys can be used with more than one
application if the same data is being captured from each application and you want
captured data from multiple applications to be grouped as a single entity.
Log level settings
The log level settings configure base logging settings.
Table 15. Log level settings
Item ID
Description
Values
LoggingLevel
The current logging level, applies only when
log level is not indicated in log statement.
Integer, 0-3
v 0 does not send log data.
v 1 has the highest priority.
v 3 has the lowest priority.
To disable logging, start Tealeaf.Disable().
See Chapter 6, “Reference,” on page 113.
DisplayLogging
When set to true, debug log statements are
displayed in LogCat. Filter for the
UICAndroid tag.
Boolean
LogViewLayout
OnScreenTransition
When set to true, UICAndroid logs the screen
layout. When set to False, the screen layout
is not logged.
Boolean
© Copyright IBM Corp. 1999, 2016
97
Kill switch settings
These settings control the kill switch and whether to use a white list of phone
whose events can be captured.
Table 16. Kill switch settings
Item ID
Description
Values
KillSwitchEnabled
If true, the framework checks the
kill switch target page before
starting. You must specify the
following properties.
true/false
If KillSwitchEnabled=false, the
framework always starts.
KillSwitchUrl
Defines the URL to check for the kill URL
switch. The framework requires a
successful response to initialize
when KillSwitchEnabled is set to
true.
KillSwitchMaxNumberOfTries
The number of times the framework Integer
checks for the kill switch URL before
giving up. This value should be set
to at least 1.
KillSwitchTimeInterval
The time to wait before rechecking
the kill switch URL if it is not
responding
UseWhiteList
If true and KillSwitchEnabled, the
true/false
framework requires a phone id to
assign before calling Enable to check
the white list of phone ids.
Seconds
If false and KillSwitchEnabled, the
framework defaults to use random
sampling.
WhiteListParam
Parameter that is used to send the
white list ID corresponding to the
phone ID.
Current white list
server uses id
Local cache file settings
You use these settings to configure use of the device's local cache.
Table 17. Local cache file settings
Item ID
Description
Values
HasToPersistLocalCache
If true, data is stored in local storage
on the device, instead of in memory.
The following settings must also be
configured.
true/false
CachingLevel
The current caching level. Applies only Integer, 0-3
when HasToPersistLocalCache is true.
v 0 does not send data.
v 1 has the highest priority.
v 3 has the lowest priority.
0 has the highest priority.
98
IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide
Table 17. Local cache file settings (continued)
Item ID
Description
Values
CachedFileMaxBytesSize
Maximum number of bytes to be
stored on device.
Bytes
Post settings
These settings control the logging level, URL, volume, and frequency of posts to
the target page.
Table 18. Post settings
Item ID
Description
Values
PostMessageUrl
The URL for posting data to your server.
Note: To enable secure transport between
the logging framework and the target
page, configure this URL to begin with
https://. For more information about the
target page, see Chapter 1, “Tealeaf
installation and implementation in an
Android application,” on page 1.
URL
PostMessageLevelWiFi
The logging level of events to be sent to
the server over Wi-Fi when network
performance is good. 0 has the highest
priority.
0-3
PostMessageLevelCellular
The logging level of events to be sent to
the server over the cellular (3G) network.
0 has the highest priority.
0-3
MaxStringsLength
Maximum string length to be sent to
target page per value in log statements.
Prevents long strings from taking up
storage and bandwidth.
Note: This value must be set to at least 1.
Integer
ManualPostEnabled
If true, the framework sends data to the
server only when your application calls
requestManualServerPost.
true/false
If set to false, you must configure the
following settings.
Note: You cannot enable this setting and
DoPostOnIntervals together.
DoPostOnIntervals
If true, the framework sends data to the
server at regular time intervals that are
specified by PostMessageTimeIntervals
when the application is in the foreground.
This value must be set to true if
ManualPostEnabled=false.
Note: You cannot enable this setting and
ManualPostEnabled together.
PostMessageTimeIntervals
How often the framework sends data to
Seconds
the server when DoPostOnIntervals is set
to true.
Note: This value must be set to be greater
than PostMessageTimeout plus
PostMessageDelayTimeToSendData.
true/false
Chapter 2. Configuration file
99
Table 18. Post settings (continued)
Item ID
Description
Values
PostMessageTimeout
The timeout for the framework's posts to
the server. While the framework does not
receive a server response within this
timeframe, the framework keeps trying to
send data.
Seconds
Masking settings
These settings control privacy masking.
Table 19. Masking settings
Item ID
Description
Values
HasMasking
It can be true or false to mask
values of controls. If
HasMasking=true, then complete
next value.
Boolean
MaskIdList
Comma delimited ids or regular
expressions to find ids.
String
HasCustomMask
It can be true or false to use next
values below if true.
Boolean
SensitiveSmallCaseAlphabet
Character to be used by small case
letter.
String
SensitiveCapitalCaseAlphabet
Character to be used by capital case
letter.
String
SensitiveSymbol
Character to be used by symbol.
String
SensitiveNumber
Character to be used by number.
String
Filter message type setting
This setting controls the message types that are sent back to the server.
Table 20. Filter message type setting
Item ID
Description
Values
FilterMessageTypes
If set to TRUE, only the MessageTypes
included in the comma-separated list
are sent back to the server. If set to
FALSE, all message types are sent back
to the server.
TRUE/ FALSE
Cookie settings
These settings control cookies.
Table 21. Cookie settings
100
Item ID
Description
Values
CookieSecure
If set to TRUE, a secure parameter is
added to the cookie. This can only be
used in https post urls.
TRUE/ FALSE
IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide
Table 21. Cookie settings (continued)
Item ID
Description
Values
CookieExpiresFormat
This setting is used to indicate the
cookie expiration format.
Valid date formats:
ASCTIME, RFC1036,
or RFC1123
Session timeout setting
This setting controls session timeouts.
Table 22. Session timeout setting
Item ID
Description
Values
SessionTimeout
When SessionTimeout is set, the
expiration of cookie is the current
time plus the session timeout value.
Minutes
Screen shot settings
These settings control screen shots.
Note: You can store screen shots in memory instead of in local memory on the
device. To enable screen shots to save in memory, you must set
HasToPersistLocalCache to false in the local cache file settings.
Table 23. Screenshot settings
Item ID
Description
Values
ScreenshotFormat
The format of the screen shot.
PNG/ JPG
PercentOfScreenshotsSize
The percentage of screen capture's
original pixel dimensions at which
posted screen captures are
submitted, 1-100.
Integer 1-100
PercentToCompressImage
Percentage to compress image. This
setting can only be used for JPG
images. PNG images ignore this
setting and default to 100.
Integer 1-100
Internal settings: do not change
Do not change these settings unless directed to do so by IBM Tealeaf.
Table 24. Internal settings: do not change
Item ID
Description
Values
PostMessageSocketTimeout
The socket timeout for the framework's Seconds
posts to the server. While the
framework does not receive a server
response within this timeframe, the
framework keeps trying to send data.
Chapter 2. Configuration file
101
Table 24. Internal settings: do not change (continued)
102
Item ID
Description
Values
CompressPostMessage
When set to true, HTTP POSTs
submitted from the framework are
compressed in compress format.
Note: To extract the compressed
POSTs, some additional server-side
configuration can be required. See
Chapter 1, “Tealeaf installation and
implementation in an Android
application,” on page 1.
true/ false
BufferLimit
The number of messages to store in
memory to be sent to server.
Integer
BufferPercent
Percentage to remove from BufferLimit Percentage
before it gets saved to cache if enabled.
TimeIntervalBetweenSnapshots
The time interval for taking snapshots
of environmental data
IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide
Seconds
Chapter 3. Application images and replay
For application replay, the images that you added to your application should be
copied to the replay server. When the images are on the replay server, the images
do not need to be sent in the payload which could cause performance issues.
Instead, replay uses a unique identifier for each image to retrieve the needed
images from the replay server. Part of developing your application includes
collecting the images that you use in your application so that they can be copied to
the replay server. There are two tools that you run on your local machine that
assign the unique identifiers to the images and collect the images.
Available tools
There are two tools that you can use to collect the images that you inserted in your
application:
Tool
Description
Platforms
Target Simulator
A command line program
v For use with the Android
that runs on your local
SDK and iOS SDK.
machine and acts as a Tealeaf
v Runs in Windows and iOS
target page to collect the
environments.
images in your application.
Images are collected into a
folder. Using the tool
involves:
1. Installing the Target
Simulator from the
Android package.
2. Configuring
TLFConfigurableItems
configuration file to
non-standard run-time
settings.
3. Exercise all of the pages
in your application.
4. Reset your
TLFConfigurableItems
configuration file to
standard run-time
settings.
5. Transfer the images to the
replay server images
folder.
© Copyright IBM Corp. 1999, 2016
103
Tool
Description
Platforms
Android Image Capture Tool A command line program
v For use with the Android
that collects all of the images
SDK.
in your android application
v Runs in Android
to an archive. Using the tool
environments only.
involves:
1. Downloading and
installing Ruby.
2. Downloading and
installing Rake.
3. Installing the Android
Image Capture Tool in
your development
environment.
4. Running the tool from a
command line.
5. Transferring the archive
to the replay server
images folder.
Target Simulator
You use the Target Simulator Tool to capture the static images that you inserted in
your mobile application, such as backgrounds for buttons or controls. The tool
collects all images that it finds, including dynamic images that are part of the
application database. When you start the tool, you must exercise every page in
your application for the tool to capture the images. The Target Simulator uses the
IBM SDK for Node.js. You can obtain an installer from the Tealeaf Android or iOS
SDK package or from http://www.ibm.com/developerworks/web/nodesdk/. While
there are other versions of Node.js, only the IBM SDK for Node.js is supported.
Target Simulator details
The Target Simulator acts as a target page on your local machine. After you start
the simulator, you exercise every page in your application. The simulator takes the
images that are embedded in the application, uses the image check sum to create
unique file name for each image, and saves the images in the same location where
the Target Simulator tool is located. After you have the images, the images must be
transferred to the replay server images folder.
Target Simulator SDK settings
Because images are not sent in the payload in production, you modify the SDK
properties to send the images in payloads and to use a target page on the machine
running the Target Simulator and not the production Tealeaf Target page. When
you start the Target Simulator, the program gives you the URL where the Target
Simulator is listening SDK for payloads that contain images..
The Target Simulator provides you a URL with an IP address.
The PostMessageUrl location is http://<IP addres>:<portnumber>. By default, the
<portnumber> is 9000. If you change the port number on the command line, that is
the port number that is used.
104
IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide
You modify the TealeafBasicConfig.properties file for Android applications, and
the TLFConfigurableItems.plist file for iOS applications. You modify the settings
to point to the target page on the machine running the Target Simulator, to get
image data, and to increase the payload size to allow images. You modify:
v Android and iOS - PostMessageURL - http://localhost:<port number>
v Android and iOS - GetImageDataOnScreenLayout - Yes
v Android - MaxNumberOfBytesPerActivation - 2,000,000,000
After you exercise your application you modify the properties file and change the
properties back to the production settings for normal operation. You reset the
settings to:
v Android and iOS - PostMessageURL - the URL for the production Tealeaf Target
page
v Android and iOS - GetImageDataOnScreenLayout - No
v Android - MaxNumberOfBytesPerActivation - <the number used in production>
Target Simulator command
If you already have the IBM SDK for Node.js in your path, you can start the target
simulator by entering node target_sim.js.
If Node.js is not in your path,the Target Simulator full path command for Mac is
/Applications/IBM/node/bin/node target_sim.js.
If Node.js is not in your path, the Target Simulator full path command for
Windows is "C:\Program Files\IBM\Node\node.exe" target_sim.js.
By default the Target Simulator listens for SDK posts on port 9000. If you already
have something running on port 9000 and want the Target Simulator to use a
different port, specify a port number at the end of the command. For example, to
change the port to 8080, enter:
/Applications/IBM/node/bin/node target_sim.js 8080
Transfer the images to the replay server images folder
Once the folder with the images is created, with either tool, the archive must be
transferred to the replay server images folder. This folder is typically
C:\Tealeaf\Replay Server\Images.
Whoever has access to the replay server can transfer the archive. It may be you,
the portal administrator, or someone else, depending on your local practices.
Collecting images from your application with the Target
Simulator
Use this task to capture the images in your application so that they can be
transferred to the replay server for replay. The Target Simulator tool runs in Mac
OS and Windows environments to capture Android and Mac OS application
images. You use this tool after you have developed your application and have all
of your images imbedded and any time that you embed new images in your
application.
If you do not already have the IBM SDK for Node.js installed on your local
machine, download and install the SDK.
Chapter 3. Application images and replay
105
1. Extract the Target Simulator archive on the device that you used to create your
application.
2. Start the simulator with the default settings by entering node target_sim.js.
3. Modify the configuration properties for your platform:
IF you created your application for an...
Android device
THEN...
1. Edit the TealeafBasicConfig.properties
file.
2. Set PostMessageUrl: to the URL that
application reports is listening on.
3. Set GetImageDataOnScreenLayout: to YES
4. Set MaxNumberOfBytesPerActivation: to
2,000,000,000
5. Save and exit the file.
iOS device
1. Edit the TLFConfigurableItems.plist file.
2. Set PostMessageUrl: to the URL that
application reports it is listening on.
3. Set GetImageDataOnScreenLayout: to YES
4. Save and exit the file.
4. Exercise every page in your application to capture all of the images that you
added. In the target_sim.js console window, you see a running log of what
POSTs were received and what images (if any) were found and saved to the file
system.
5. In the target_sim.js console window, press Control-C to exit the simulator.
6. Reset the TealeafBasic configuration file to standard run-time settings.
IF you created your application for an...
Android device
THEN...
1. Edit the TealeafBasicConfig.properties
file.
2. Set PostMessageUrl: to the URL for the
application Target page.
3. Set GetImageDataOnScreenLayout: to NO
4. Set MaxNumberOfBytesPerActivation: to
your production environment setting.
5. Save and exit the file.
iOS device
1. Edit the TLFConfigurableItems.plist file.
2. Set GetImageDataOnScreenLayout: to NO
3. Save and exit the file.
7. Transfer the images to the replay server.
Android Image Capture Tool
You use the Android Image Capture Tool to capture the static images that you
inserted in your android application, such as PNG or JPG images used by
IOmageView. The tool collects all images that it finds under the "res" folder. When
you start the tool, it automatically captures the images from the application.
Android Image Capture Tool details
The Android Image Capture Tool automatically collects the images in an android
application into a folder called images. You do not need to exercise or run the
106
IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide
application. The Android Image Capture tool extracts and creates proper file path
mapping from your APK file, so that the metadata collected from the Tealeaf
Android client library for images can be displayed properly.
Android Image Capture Tool software
The Android Image Capture Tool requires Ruby and Rake software. The tool uses
the apk for your application to locate the application images.
Android Image Capture Tool files
The Android Image Capture Tool uniquely names the image files and places them
in an images folder in the AndroidImageCaptureTool root folder. In the Images
folder, the tool creates a res folder that contains sub-folders for the different image
resolutions. Images are grouped by resolution.
Transfer the images to the replay server images folder
Once the archive is created, with either tool, the archive must be transferred to the
replay server images folder. This folder is typically C:\Tealeaf\Replay
Server\Images.
Whoever has access to the replay server can transfer the archive. It may be you,
the portal administrator, or someone else, depending on your local practices.
Collecting images from your application with the Android
Image Capture Tool
Use this task to capture the images in your application so that they can be
transferred to the replay server for replay. The Android Image Capture Tool
captures images from android applications only.
Before you begin this task you must download and install:
1. Ruby version 2.1.2.
2. Rake version 10.3.2.
After Ruby and Rake are installed, install the zip and nokogiri gem modules.
To install the zip and nokogiri gem modules in a Mac OS environment:
1. Open a terminal window.
2. Enter xcode-select --install to install the Xcode Command Line tools.
3. Enter gem install rubyzip '1.1.7' to install the rubyzip module.
4. Enter gem install nokogiri '1.6.7.2' to install the nokogiri module.
To install the zip and nokogiri gem modules in a Windows environment:
1. Open a command prompt.
2. Enter gem install zip '1.1.7' to install the zip module.
3. Enter gem install nokogiri '1.6.7.2' to install the nokogiri module.
You must run this tool in your development environment where you developed
your application.
1. Extract the AndroidImageCaptureTool file from the Android SDK package to
your local path.
Chapter 3. Application images and replay
107
2. Open a terminal or command line prompt.
3. Go to the Android Image Capture Tool root folder AndroidImageCaptureTool/.
4. Enter the rake command to run the rake task on the .apk file for your
application: rake apk_path={YOUR/APK/PATH}
5. After the tool is finished, transfer the images to the replay server.
108
IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide
Chapter 4. Sample applications
The sample code that is provided with the software distribution contains an
Android application that can be used to test the IBM Tealeaf system.
There is one version of code provided.
Version
Description
UICAndroidControlsAppDarkHolo
An Android application, which has the current supported controls that you
can replay in BBR with examples of how to use event listeners with Tealeaf
api.
© Copyright IBM Corp. 1999, 2016
109
110
IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide
Chapter 5. Guidelines
Apply the following tips to your application development and integration of the
IBM Tealeaf Android SDK.
v Use the kill switch to control logging of the Android application. See Chapter 7,
“Sample Code,” on page 131.
v Add IDs for all UI controls that you want to capture.
v Apply privacy masking or blocking of all sensitive customer data through the
Android SDK.
Note: In Release 8.5, IBM Tealeaf introduced step-based eventing, which
simplifies and unifies event capture from all client frameworks, while it
enhances performance. Due to changes in how the data is bundled, you now
apply data privacy through the individual client frameworks, instead of using
the IBM Tealeaf server methods for data privacy.
– See Chapter 1, “Tealeaf installation and implementation in an Android
application,” on page 1.
– For more information about managing privacy in general, see "Managing
Data Privacy in Tealeaf CX" in the IBM Tealeaf CX Installation Manual.
v Follow guidelines for the file that extends Application. See Chapter 1, “Tealeaf
installation and implementation in an Android application,” on page 1.
v Follow guidelines for the file that extends Activity. See Chapter 1, “Tealeaf
installation and implementation in an Android application,” on page 1.
v Debug locally in Eclipse by using LogCat.
To see debug messages in the LogCat tab of Eclipse, enter the following string:
tag:UICAndroid.
v Follow guidelines for using text fields to get more metrics. See “Tealeaf class” on
page 116.
v Due to the way JSON messages are captured and transmitted, force a
submission of all queued messages before you allow users of your mobile native
application to open a web view. If this step is not done, hits can appear to be
out of order during replay in IBM Tealeaf.
See "Search and Replay for Mobile App" in the IBM Tealeaf CX Mobile User
Manual.
© Copyright IBM Corp. 1999, 2016
111
112
IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide
Chapter 6. Reference
This section contains class reference information about the IBM Tealeaf Android
SDK library.
UICActivity class
The com.tl.uic.app.UICActivity class extends com.tl.uic.app.Activity.
UICActivity helps capture user actions in an Android application and enables
screen capture after the Activity is created.
Note: To enable capture of screens into IBM Tealeaf, you must configure the PCA
to capture binary POSTs of png images. See Chapter 1, “Tealeaf installation and
implementation in an Android application,” on page 1.
Method detail
getTakeSnapshotAfterCreate
public Boolean getTakeSnapshotAfterCreate()
Whether to take the snapshot after create.
Returns whether to take the snapshot after create.
setTakeSnapshotAfterCreate
public void setTakeSnapshotAfterCreate(final
Boolean takeSnapshotAfterCreate)
Whether to take the snapshot after create.
takeSnapshotAfterCreate - Whether to take the snapshot after create.
getTookImage
public Boolean getTookImage()
Whether screen capture was taken.
setTookImage
public void setTookImage(final Boolean tookImage)
Whether screen capture was taken.
tookImage - Whether screen capture was taken.
getLogicalPageName
public String getLogicalPageName()
Logical page name of the Activity.
Returns the logical page name of the Activity. If none was assigned, it
receives a name from the class of Activity, and an underscore (_) with
current time in milliseconds is added.
setLogicalPageName
public void setLogicalPageName(final String logicalPageName)
Logical page name of the Activity.
logicalPageName - Logical page name of the Activity.
© Copyright IBM Corp. 1999, 2016
113
getImageBackground
public int getImageBackground()
Background color of the image of the screen capture.
Returns the background color of the image of the screen capture.
setImageBackground
public void setImageBackground(final int imageBackground)
Background color of the image of the screen capture.
imageBackground - Background color of the image of the screen capture.
getView
public View getView()
View to use for screen capture.
Returns the view to use for screen capture.
setView
public void setView(final View view)
View to use for screen capture.
view - View to use for screen capture.
getNumOnGlobalLayoutListener
public int getNumOnGlobalLayoutListener()
Number of OnGlobalLayoutListener set on views.
Returns the number of milliseconds to delay before snapshot is taken
because more time is needed to render properly.
setNumOnGlobalLayoutListener
public void setNumOnGlobalLayoutListener(final
int numOnGlobalLayoutListener)
Number of OnGlobalLayoutListener set on views.
millisecondSnapshotDelay - Milliseconds to delay before snapshot is taken
because more time is needed to render properly.
getMillisecondSnapshotDelay
public long getMillisecondSnapshotDelay()
Milliseconds to delay before snap shot is taken because more time is
needed to render properly.
Returns the number of milliseconds to delay before snapshot is taken
because more time is needed to render properly.
setMillisecondSnapshotDelay
public void setMillisecondSnapshotDelay(final
long millisecondSnapshotDelay)
Milliseconds to delay before snap shot is taken because more time is
needed to render properly.
millisecondSnapshotDelay - Milliseconds to delay before snap shot is taken
because more time is needed to render properly.
114
IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide
Reference
Table 25. UICActivity class
Package
Class
Description
com.tl.uic.app
UICActivity
UICActivity used to
help control IBM Tealeaf
Android SDK library.
“UICApplication class”
Application that is used
to help control IBM
Tealeaf Android SDK
library.
com.tl.uic
“Tealeaf class” on page 116
IBM Tealeaf Android
SDK library that is used
to capture user actions.
com.tl.uic.http
TLDefaultHttpClient class
Extends
DefaultHttpClient to
monitor when a URL
was requested.
TLHttpRequestInterceptor class
Extends
HttpRequestInterceptor
to add IBM Tealeaf
headers for
sessionization.
TLHttpResponseInterceptor class
Extends
HttpResponseInterceptor
to acquire details for the
Tealeaf connection
object.
“UICWebView class” on page 126
WebView used to add
session ID to header
requests.
com.tl.uic.webkit
“UICWebChromeClient Class” on page 128 Extends
WebChromeClient to
monitor when browser
finished render after
which screen capture is
enabled.
“UICWebViewClient Class” on page 129
Extends WebViewClient
to monitor when the
URL loaded to add IBM
Tealeaf headers for
sessionization.
UICApplication class
The com.tl.uic.app.UICApplication class extends android.app.Application.
UICApplication helps capture user actions in an Android application.
Method detail
getTealeaf
public Tealeaf getTealeaf()
Get current instance of IBM Tealeaf.
Returns the current instance of IBM Tealeaf.
Chapter 6. Reference
115
Reference
Table 26. UICApplication class
Package
Class
Description
com.tl.uic.app
“UICActivity class” on page 113
UICActivity used to help
control IBM Tealeaf
Android SDK library.
UICApplication
Application that is used to
help control IBM Tealeaf
Android SDK library.
com.tl.uic
“Tealeaf class”
IBM Tealeaf Android SDK
library that is used to
capture user actions.
com.tl.uic.http
TLDefaultHttpClient class
Extends DefaultHttpClient
to monitor when a URL
was requested.
TLHttpRequestInterceptor class
Extends
HttpRequestInterceptor to
add IBM Tealeaf headers
for sessionization.
TLHttpResponseInterceptor class
Extends
HttpResponseInterceptor to
acquire details for the IBM
Tealeaf connection object.
“UICWebView class” on page 126
WebView used to add
session ID to header
requests.
“UICWebChromeClient Class” on
page 128
Extends WebChromeClient
to monitor when browser
finished render after which
screen capture is enabled.
“UICWebViewClient Class” on page
129
Extends WebViewClient to
monitor when the URL
loaded to add IBM Tealeaf
headers for sessionization.
com.tl.uic.webkit
Tealeaf class
The com.tl.uic.TeaLeaf class extends java.lang.Object. The Tealeaf library helps
capture user actions in an Android application.
Fields
Table 27. Tealeaf class
116
Field
Summary
Description
static
java.lang.String
TLF_SESSION_HEADER
Header key that is used to
sessionize on
X-Tealeaf-Session.
static
java.lang.String
TAG
UICAndroid used in
LogCat.
IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide
Fields used in event handlers to get display user actions
correctly
Table 28. Tealeaf class
Field
Summary
Description
static
java.lang.String
TLF_ON_FOCUS_CHANGE_IN
Used in TextView based
controls to indicate focus
in.
static
java.lang.String
TLF_ON_FOCUS_CHANGE_OUT
Used in TextView based
controls to indicate focus
out.
static
java.lang.String
TLF_ON_GROUP_COLLAPSE
Used in
ExpandableListView based
controls to indicate group
is collapsed.
static
java.lang.String
TLF_ON_GROUP_EXPAND
Used in
ExpandableListView based
controls to indicate group
is expanded.
static
java.lang.String
TLF_ON_DRAWER_OPENED
Used in SlidingDrawer
based controls to indicate
drawer is opened.
static
java.lang.String
TLF_ON_DRAWER_CLOSED
Used in SlidingDrawer
based controls to indicate
drawer is closed.
Fields used to access configuration file values
Table 29. Tealeaf class
Field
Summary
Description
static
java.lang.String
TLF_LOGGING_LEVEL
Default log level.
static
java.lang.String
DISPLAY_LOGGING
Whether to
display debug
statements in
LogCat
static
java.lang.String
TLF_KILL_SWITCH_ENABLED
Whether kill
switch is enabled.
static
java.lang.String
TLF_KILL_SWITCH_URL
Url for kill switch.
static
java.lang.String
TLF_KILL_SWITCH_MAX_NUMBER_OF_TRIES
Maximum number
of tries
static
java.lang.String
TLF_KILL_SWITCH_TIME_INTERVAL
Kill switch time
interval to retry to
access kill switch.
static
java.lang.String
TLF_USE_WHITE_LIST
Whether to use
white list.
static
java.lang.String
TLF_WHITE_LIST_PARAM
Parameter that
white list uses.
static
java.lang.String
TLF_USE_RANDOM_SAMPLE
Whether to use
random sample.
Chapter 6. Reference
117
Table 29. Tealeaf class (continued)
118
Field
Summary
Description
static
java.lang.String
TLF_RANDOM_SAMPLE_PARAM
Parameter that
random sample
uses.
static
java.lang.String
TLF_HAS_TO_PERSIST_LOCAL_CACHE
Whether it is able
to save cache to
device.
static
java.lang.String
TLF_CACHED_LEVEL
Cache level to be
saved to device.
static
java.lang.String
TLF_CACHED_FILE_MAX_BYTES_SIZE
Maximum cache
byte size to be
saved to device.
static
java.lang.String
TLF_POST_MESSAGE_URL
Url of the target
page.
static
java.lang.String
TLF_POST_MESSAGE_LEVEL_WIFI
Log level if
current connection
level is WiFi.
static
java.lang.String
TLF_POST_MESSAGE_LEVEL_CELLULAR
Log level if
current connection
level is cellular.
static
java.lang.String
TLF_MAX_STRINGS_LENGTH
Maximum string
length.
static
java.lang.String
TLF_MANUAL_POST_ENABLED
Whether to enable
control of posting
to target page.
Developer is
responsible for
posting to target
page.
static
java.lang.String
TLF_DO_POSTS_ON_INTERVALS
Whether to have
framework post at
a set interval.
static
java.lang.String
TLF_POST_MESSAGE_TIME_INTERVALS
Time interval
between posts.
static
java.lang.String
TLF_POST_MESSAGE_MAX_BYTES_SIZE
Maximum byte
size for posting a
message.
static
java.lang.String
TLF_HAS_MASKING
Whether to mask
values of controls.
static
java.lang.String
TLF_MASK_ID_LIST
Comma-delimited
string that can
have IDs of
controls or regular
expression to find
IDs of controls.
IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide
Table 29. Tealeaf class (continued)
Field
Summary
Description
static
java.lang.String
TLF_HAS_CUSTOM_MASK
Whether to use
custom mask
values to replace.
If set to false,
Logging
Framework
returns an empty
string.
static
java.lang.String
TLF_SENSITIVE_SMALL_CASE_ALPHABET
Small letter to
replace during
custom mask.
static
java.lang.String
TLF_SENSITIVE_CAPITAL_CASE_ALPHABET
Capital letter to
replace during
custom mask.
static
java.lang.String
TLF_SENSITIVE_SYMBOL
Symbol to replace
during custom
mask.
static
java.lang.String
TLF_SENSITIVE_NUMBER
Number to replace
during custom
mask.
Constructor
Public Tealeaf (Application app)
Tealeaf is a library to help capture user actions in an Android application.
Parameters:
v application - Reference to current Android application.
Method detail
getCurrentSessionId
public static java.lang.String getCurrentSessionId()
Get current session ID.
getDeviceId
public static java.lang.String getDeviceId()
Get device ID used with the whitelist on the kill switch server.
getPhoneId This method has been deprecated. Use getDeviceId instead.
public static java.lang.String getPhoneId()
Get phone ID used with the whitelist on the kill switch server.
setDeviceId
public static void setDeviceId(java.lang.String deviceId)
Set device ID that is used with the whitelist on the kill switch server.
setPhoneId - This method has been deprecated. Use setDeviceId instead.
public static void setPhoneId(java.lang.String phoneId)
Set phone ID that is used with the whitelist on the kill switch server.
Chapter 6. Reference
119
isEnabled
public static java.lang.Boolean isEnabled()
To enable library.
Returns whether Tealeaf library was enabled.
getApplication()
public static android.app.Application getApplication()
Reference to current Android Application.
Returns reference to current Android Application.
getMessageVersion()
public static String getMessageVersion()
Get current JSON message version.
Returns current JSON message version.
getLibraryVersion()
public static java.lang.String getLibraryVersion()
Reference to current library version.
Returns reference to current library version.
enable
public static java.ladng.Boolean enable()
public static java.lang.Boolean enable(sessionId)
To enable library with a given session ID or a generated one.
v sessionId - Given session ID to use.
Returns if Tealeaf library was enabled.
disable
public static java.lang.Boolean disable()
To disable library.
Returns if library was disabled.
onPause
public static Boolean onPause(final Activity activity,
final String logicalPageName)
If not using UICActivity, add this call on your Activity file onPause method
before calling super.
v activity - Activity that calls onPause.
v logicalPageName - Descriptive name of the activity that calls onPause.
Returns True/False whether it was able to pause properly.
onResume
public static Boolean onResume(final Activity activity,
final String logicalPageName)
If not using UICActivity, add this call on your Activity file onResume
method before calling super.
v activity - Activity that calls onResume.
v logicalPageName - Descriptive name of the activity that calls onResume.
120
IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide
Returns True/False whether it was able to resume properly.
onDestroy
public static Boolean onDestroy(final Activity activity,
final String logicalPageName)
If not using UICActivity, add this call on your Activity file onDestroy
method before calling super.
v activity - Activity that calls onResume.
v logicalPageName - Descriptive name of the activity that calls onResume.
Returns True/False whether it was able to destroy properly.
OnLowMemory
public static java.lang.Boolean OnLowMemory()
If not using UICApplication, add this call on your Application file
OnLowMemory method before calling super.
Returns:
True/False whether it was able to properly clean up.
terminate
public static java.lang.Boolean terminate()
If not using UICApplicaion, add this call on your Application file on
terminate method before calling super.
Returns True/False whether it was able to terminate properly.
flush
public static java.lang.Boolean flush()
To be used to flush data.
Returns:
True/False whether it was able to flush data back to server.
logEvent
public static java.lang.Boolean
logEvent(final View view)public static java.lang.
Boolean logEvent(final View view,
final java.lang.String eventType)public
static java.lang.Boolean logEvent(final View view,
final java.lang.String eventType, final
int logLevel)
Log an event from an event handler.
v view - Control from event handler.
v eventType - Event type of event handler.
v logLevel - Log level for TeaLeaf library.
Returns True/False whether it was able to log event.
logCustomEvent
public static java.lang.Boolean
logCustomEvent(final java.lang.String eventName)
public static java.lang.Boolean
logCustomEvent(final java.lang.String eventName,
final int logLevel)public
static java.lang.Boolean
logCustomEvent(final java.lang.String eventName,
final
Chapter 6. Reference
121
java.util.HashMap<java.lang.String, final java.lang.
String> data)public static java.lang.
Boolean
logCustomEvent(final java.lang.String eventName,
final
java.util.HashMap<java.lang.String, java.lang.
String> data,
final int logLevel)
Log a custom event.
v eventName - Event name to be logged.
v data - Key and value pair to be logged.
v logLevel - Log level for TeaLeaf library.
Returns True/False whether it was able to log event.
logException
public static java.lang.Boolean
logException(final java.lang.Throwable exception)
public static java.lang.Boolean
logException(final java.lang.Throwable exception,
final HashMap<String, String> data)
public static java.lang.Boolean logException(final java.lang.
Throwable exception,
final HashMap<String, String> data, final boolean unhandled)
Log an exception.
v exception - Exception to be logged.
v data - The HashMap data to be logged. Values for this parameter are
key-value pairs.
v unhandled - Whether the exception is handled. Values are True or False.
Returns True or Falsewhether exception was logged.
logScreenview
public static Boolean logScreenview(final Activity activity,
final String logicalPageName, final ApplicationContextType
applicationContextType)
public static Boolean logScreenview(final Activity activity,
final String logicalPageName,
final ApplicationContextType applicationContextType,
final String referrer)
Log an application context (screenView).
v activity - Activity with an application context (screenView) change.
v logicalPageName - Activity's name or descriptive name that was created
on device.
v applicationContextType - ApplicationContextType of the application
context.
v referrer - Referrer page that logical page uses.
Returns True/False whether exception was logged.
logSpinnerEvent
public static Boolean logSpinnerEvent(final View view,
final String eventType, final Spinner spinner)
Logs an event from an event handler that has TextView data that needs to
be extracted from a spinner object and nested layouts. The following
parameters are used with the API.
122
IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide
v view - View control from the event handler.
v eventType - The event type of the event handler.
v spinner -: Spinner control type.
The API returns as true when it has successfully logged an event.
logScreenLayout
public static Boolean logScreenLayout(final Activity activity)
Log the layout of activity immediately without a layout name.
public static Boolean logScreenLayout(final Activity activity,final
String name)
Log the layout of activity immediately with a layout name.
public static Boolean logScreenLayout(final Activity activity,final
String name, final int delayMS)
Log the layout of an activity with a time delay on run.
v activity - Activity to be logged.
v name - Name of the layout.
v delayMS - Number, in milliseconds, to delay the call.
Returns: Whether the layout was logged.
public static Boolean logScreenLayout(final Activity activity,
final AlertDialog alertDialog, final String title, final String message)
public static Boolean logScreenLayout(final Activity activity,
final AlertDialog alertDialog, final String name, final String title,
final String message)
Log the layout of the alert dialog.
v activity - Activity where AlertDialog is to be logged.
v alertDialog - AlertDialog to be logged.
v name - Screenview name of where alert appears.
v title - Title displayed on the alert dialog.
v message - Message displayed on alert dialog.
Returns: Whether it was able to log the layout.
logScreenLayoutSetOnShowListener
public static Boolean logScreenLayoutSetOnShowListener
(final Activity activity, final AlertDialog alertDialog,
final String title, final String message)
public static Boolean logScreenLayoutSetOnShowListener
(final Activity activity, final AlertDialog alertDialog,
final String name, final String title, final String message)
Log the layout of the alert dialog.
v activity - Activity where AlertDialog is to be logged.
v alertDialog - AlertDialog to be logged.
v name - Screenview name of where the alert appears.
v title - Title displayed on alert dialog.
v message - Message displayed on alert dialog.
Returns: Whether the layout was logged.
Chapter 6. Reference
123
logScreenLayoutOnCreate
public static Boolean logScreenLayoutOnCreate(final Activity activity,
final String name)
Log the layout of the activity with OnGlobalLayoutListener to know when
the view is complete.
v activity - Activity to be logged.
v name - Name of the layout.
Returns: Whether the layout was logged.
logConnection
public static java.lang.Boolean
logConnection(final java.lang.String url,
final org.apache.http.HttpResponse
httpResponse, final java.util.Date initTime,
final long loadTime, final
long responseTime)
Log a connection.
v url - Url of the connection.
v httpResponse - HttpResponse of the connection.
v initTime - Initial time of the response.
v loadTime - Load time of the response.
v responseTime - Response time.
Returns True/False whether connection was logged.
takeScreenShot
public static java.lang.Boolean
takeScreenShot(final View view,final java.lang.
String imageFileName)
Take screen capture of given view.
Note: This method requires to be able to save to device to take screen
capture.
v view - View to take screen capture.
v imageFileName - Name of the image.
Returns True/False whether screen capture was taken.
startSession
public static void startSession()
public static void startSession(final sessionId)
Indicate to start with a given session ID or a generated one.
v sessionId - session ID to use.
requestManualServerPost
public static java.lang.Boolean requestManualServerPost()
Post current logged data.
Returns True/False whether data was posted.
getApplicationContextOffset
public static long getApplicationContextOffset()
The current application context offset.
124
IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide
Returns long: The current application context offset.
registerFormField
public static Boolean
registerFormField(final View formField, final Activity activity)
public static Boolean
registerFormField(final View formField, final Activity activity,
final int logLevel)
Register form field that helps get statistics.
v formField - Form field to register.
v activity - Activity that has form field.
v logLevel - Log level for library.
Returns True/False whether form field was registered.
isApplicationInBackground
public static Boolean isApplicationInBackground()
Returns whether application was moved to background by not having any
activity that is displayed in the foreground.
Returns True/False whether application was moved to background.
Reference
Table 30. Tealeaf class
Package
Class
Description
com.tl.uic.app
“UICActivity class” on page 113
UICActivity used to help
control library.
“UICApplication class” on page 115
Application that is used
to help control library.
com.tl.uic
TeaLeaf
library that is used to
capture user actions.
com.tl.uic.http
TLDefaultHttpClient class
Extends
DefaultHttpClient to
monitor when a URL was
requested
TLHttpRequestInterceptor class
Extends
HttpRequestInterceptor to
add headers for
sessionization
TLHttpResponseInterceptor class
Extends
HttpResponseInterceptor
to acquire details for the
connection object
“UICWebView class” on page 126
WebView used to add
session ID to header
requests.
“UICWebChromeClient Class” on page
128
Extends
WebChromeClient to
monitor when browser
has finished render, after
which screen capture is
enabled
com.tl.uic.webkit
Chapter 6. Reference
125
Table 30. Tealeaf class (continued)
Package
Class
Description
“UICWebViewClient Class” on page 129
Extends WebViewClient
to monitor when the URL
was loaded to add
headers for sessionization
UICWebView class
The com.tl.uic.webkit.UICWebView class extends android.webkit.WebView. You use
UICWebView to add a session ID to header requests for purposes of sessionization.
This class also adds a connection object to provide information of WebView.
Method detail
getEndLoad
public Date getEndLoad()
When page finished loading.
Returns Date: When page finished loading.
setEndLoad
public void setEndLoad(final Date endLoad)
When page finished loading.
endLoad - When page finished loading.
getStartLoad
public Date getStartLoad()
When page starts loading.
Returns Date: When page starts loading.
setStartLoad
public void setStartLoad(final Date startLoad)
When page starts loading.
StartLoad - When page starts loading.
getHttpResponse
public HttpResponse getHttpResponse()
HttpResponse from the connection.
Returns HttpResponse: HttpResponse from the connection.
setHttpResponse
public void setHttpResponse
(final HttpResponse httpResponse)
HttpResponse from the connection.
httpResponse - HttpResponse from the connection.
getInitTime
public Date getInitTime()
126
IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide
Initial time from the connection.
Returns Date: Initial time from the connection.
setInitTime
public void setInitTime
(final Date initTime)
Initial time from the connection.
InitTime - Initial time from the connection.
getResponseTime
public long getResponseTime()
Response time from the connection.
long: Response time from the connection.
setResponseTime
public void setResponseTime
(final long responseTime)
Response time from the connection.
ResponseTime - Response time from the connection.
logConnection
public void logConnection()
Logs the current connection time of the webview.
Reference
Table 31. UICWebView Class
Package
Class
Description
com.tl.uic.app
“UICActivity class” on page 113
UICActivity used to help
control IBM Tealeaf
Android SDK library.
“UICApplication class” on page 115
Application that is used
to help control IBM
Tealeaf Android SDK
library.
com.tl.uic
“Tealeaf class” on page 116
IBM Tealeaf Android SDK
library that is used to
capture user actions.
com.tl.uic.http
TLDefaultHttpClient class
Extends DefaultHttpClient
to monitor when a URL
was requested.
TLHttpRequestInterceptor class
Extends
HttpRequestInterceptor to
add Android SDK
headers for sessionization.
TLHttpResponseInterceptor class
Extends
HttpResponseInterceptor
to acquire details for the
Android SDK connection
object.
Chapter 6. Reference
127
Table 31. UICWebView Class (continued)
Package
Class
Description
com.tl.uic.webkit
UICWebView
WebView used to add
session ID to header
requests.
“UICWebChromeClient Class”
Extends
WebChromeClient to
monitor when browser
finished render after
which screen capture is
enabled.
“UICWebViewClient Class” on page 129
Extends WebViewClient
to monitor when the URL
loaded to add Android
SDK headers for
sessionization.
UICWebChromeClient Class
The com.tl.uic.webkit.UICWebChromeClient class extends
android.webkit.WebChromeClient. You use UICWebChromeClient to monitor when
progress of the browser finished in order to capture a screen capture of the device
screen.
Methods overridden
v onProgressChanged
Reference
Table 32. UICWebChromeClient class
128
Package
Class
Description
com.tl.uic.app
“UICActivity class” on page 113
UICActivity used to help
control IBM Tealeaf
Android SDK library.
“UICApplication class” on page 115
Application that is used
to help control IBM
Tealeaf Android SDK
library.
com.tl.uic
“Tealeaf class” on page 116
IBM Tealeaf Android SDK
library that is used to
capture user actions.
com.tl.uic.http
TLDefaultHttpClient class
Extends
DefaultHttpClient to
monitor when a URL was
requested.
TLHttpRequestInterceptor class
Extends
HttpRequestInterceptor to
add IBM Tealeaf headers
for sessionization.
IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide
Table 32. UICWebChromeClient class (continued)
Package
com.tl.uic.webkit
Class
Description
TLHttpResponseInterceptor class
Extends
HttpResponseInterceptor
to acquire details for the
IBM Tealeaf connection
object.
“UICWebView class” on page 126
WebView used to add
session ID to header
requests.
UICWebChromeClient
Extends
WebChromeClient to
monitor when browser
finished render after
which screen capture is
enabled.
“UICWebViewClient Class”
Extends WebViewClient
to monitor when the URL
loaded to add IBM
Tealeaf headers for
sessionization.
UICWebViewClient Class
The com.tl.uic.webkit.UICWebViewClient class extends
android.webkit.WebViewClient. You use UICWebViewClient to monitor when a URL
is loading in order to add IBM Tealeaf headers for sessionizing.
Methods overridden
v shouldOverrideUrlLoading
Reference
Table 33. UICWebViewClient class
Package
Class
Description
com.tl.uic.app
“UICActivity class” on page 113
UICActivity used to help control
IBM Tealeaf Android SDK library.
“UICApplication class” on page 115 Application that is used to help
control IBM Tealeaf Android SDK
library.
com.tl.uic
“Tealeaf class” on page 116
IBM Tealeaf Android SDK library
that is used to capture user actions.
com.tl.uic.http
TLDefaultHttpClient class
Extends DefaultHttpClient to
monitor when a URL was
requested.
TLHttpRequestInterceptor class
Extends HttpRequestInterceptor to
add IBM Tealeaf headers for
sessionization.
TLHttpResponseInterceptor class
Extends HttpResponseInterceptor
to acquire details for the IBM
Tealeaf connection object.
com.tl.uic.webkit “UICWebView class” on page 126
WebView used to add session ID to
header requests.
Chapter 6. Reference
129
Table 33. UICWebViewClient class (continued)
Package
130
Class
Description
“UICWebChromeClient Class” on
page 128
Extends WebChromeClient to
monitor when browser finished
render after which screen capture is
enabled.
UICWebViewClient
Extends WebViewClient to monitor
when the URL loaded in to add
IBM Tealeaf headers for
sessionization.
IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide
Chapter 7. Sample Code
This chapter contains sample code for IBM Tealeaf Android SDK.
How to instrument TextView based controls
Because TextView based controls are used for text fields, to get dwell time and
other data you instrument the OnFocusChangeListener to know when a user starts
and completes typing.
// Get TextView based control
final EditText nameEditText = (EditText) findViewById(R.id.nameEditText);
// Create a OnFocusChangeListener
OnFocusChangeListener focusListen = new OnFocusChangeListener () {
public void onFocusChange(View view, boolean hasFocus){
if(hasFocus == false){
Tealeaf.logEvent(view, Tealeaf.TLF_ON_FOCUS_CHANGE_OUT);
}
else{
Tealeaf.logEvent(view, Tealeaf.TLF_ON_FOCUS_CHANGE_IN);
}
}
});
// Set OnFocusChangeListener on TextView based control
nameEditText.setOnFocusChangeListener(focusListen);
// Register TextView based control
Tealeaf.registerFormField(nameEditText, this);
How to instrument ExpandableListView based controls
For ExpandableListView controls, in order to know when a user expands or
collapses a control you instrument the OnGroupCollapseListener and
OnGroupExpandListener.
// Get ExpandableListView based control
final ExpandableListView elv = (ExpandableListView) findViewById(R.id.elv);
elv.setOnChildClickListener(new OnChildClickListener() {
public boolean onChildClick(ExpandableListView parent, View view,
int groupPosition, int childPosition, long id) {
Tealeaf.logEvent(view);
return true;
}
});
elv.setOnGroupCollapseListener(new OnGroupCollapseListener() {
public void onGroupCollapse(int groupPosition) {
Tealeaf.logEvent(elv, Tealeaf.TLF_ON_GROUP_COLLAPSE);
}
});
elv.setOnGroupExpandListener(new OnGroupExpandListener(){
public void onGroupExpand(int groupPosition) {
Tealeaf.logEvent(elv, Tealeaf.TLF_ON_GROUP_EXPAND);
}
});
© Copyright IBM Corp. 1999, 2016
131
How to instrument SlidingDrawer based controls
For SlidingDrawer controls, to know when a user opens or closes a control you
instrument the OnDrawerOpenListener and OnDrawerCloseListener.
// Get SlidingDrawer based control
final SlidingDrawer sd = (SlidingDrawer) findViewById(R.id.sd);
sd.setOnDrawerOpenListener(new OnDrawerOpenListener() {
public void onDrawerOpened(){
Tealeaf.logEvent(slidingDrawer_c5, Tealeaf.TLF_ON_DRAWER_OPENED);
}
});
sd.setOnDrawerCloseListener(new OnDrawerCloseListener(){
public void onDrawerClosed(){
Tealeaf.logEvent(slidingDrawer_c5, Tealeaf.TLF_ON_DRAWER_CLOSED);
}
});
How to mask controls
Custom masking is a feature that matches specified IDs and regular expressions
and then does character substitutions. In the example that follows, custom masking
converts actual values to the letters that are supplied as replacements. If custom
masking is set to false, it returns an empty string. You specify masking in the
TLFConfigurableItem.properties file that is in the assets folder of the Android
application.
#Masking settings
HasMasking=true
#It can be a series of ids and regular expressions comma delimited
MaskIdList=com.tealeaf.sp:id\/EditText*,com.tealeaf.sp:id\/login.password
#If set to false it will return an empty string
HasCustomMask=true
#It will turn small letters to value given
SensitiveSmallCaseAlphabet=x
#It will turn capital letters to value given
SensitiveCapitalCaseAlphabet=X
#It will turn symbols to value given
SensitiveSymbol=#
#It will turn digits to value given
SensitiveNumber=9
How to implement AdvertisingId in your application to capture Google
Advertising ID (GAID) data
Tealeaf can capture Google Advertising ID (GAID) data using AdvertisingId. The
Google Play services advertising ID is a unique, user-resettable ID for advertising.
The advertising ID gives users better controls and provides developers with a
standard system to continue to monetize their apps. The advertising ID also gives
users the ability to reset their identifier or opt out of personalized ads within
Google Play applications.
Complete the following steps to enable the ability to capture GAID data in your
application:
1. Open AndroidManifest.xml, add the following snippet to the application
section.
<meta-data
android:name="com.google.android.gms.version"
android:value="@integer/google_play_services_version" />
132
IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide
2. Open the app.gradle file for your application and add the following snippet to
add the Google Play Service ads library.
dependencies {
// Requires for Google Play ads library compile
’com.google.android.gms:play-services-ads:9.4.0’
...
}
The following example shows the JSON data with the implemented advertisingId.
"clientEnvironment": {
"osVersion": "5.0",
"height": 1920,
"width": 1080,
"deviceWidth": 360,
"deviceHeight": 640,
"pixelDensity": 3,
"mobileEnvironment": {
"totalStorage": 6619593,
"totalMemory": 369287168,
"locale": "English (United States)",
"language": "English",
"manufacturer": "samsung",
"deviceModel": "SM-N900V",
"appName": "AuroraAuto",
"appVersion": "1.0",
"deviceId": "",
"orientationType": "PORTRAIT",
"android": {},
"advertisingId": "567eca34-2ea3-4f80-9436-ea63a7abc5b0"
"osType": "Android",
"orientation": 0
}
},
If the end user has chosen to opt out of ads, advertisingId returns the following
value:
“advertisingId”: “N/A”
Server-Side KillSwitch Sampling Function
When the KillSwitch feature is enabled in the client configuration, the Framework
queries the KillSwitch URL to determine whether to enable or disable the
framework for that session. The KillSwitch URL can be .aspx, .jsp or .php.
If the Android logging framework is disabled, then the session is not captured and
is excluded from the sampled data.
The KillSwitch URL returns 1 to enable the Framework and 0 to disable the
Framework. Each KillSwitch URL has a corresponding web.config configuration
file.
Sampling function examples for ASPX
These examples show the killswitch.aspx and web.config configuration file for
ASPX
Example killswitch.aspx
This example shows the killswitch.aspx:
Chapter 7. Sample Code
133
<%@ Page Language="C#" AutoEventWireup="true"%>
<script runat="server">
public int Sampler()
{
Random rand = new Random();
int nextRandom = rand.Next(1,100);
int samplepercent = Convert.ToInt32(ConfigurationManager.AppSettings
["rate"]);
if(nextRandom &lt;= samplepercent){
return 1;
}
else{
return0;
}
}
</script>
<%
if (ConfigurationManager.AppSettings["killswitchtype"].Equals
("percentagesample")) {
%>
<%= Sampler() %>
<% } else { } %>
Example web.config configuration file for ASPX
This example shows the web.config configuration file for the killswitch.aspx:
<?xml version="1.0"?>
<!-For more information on how to configure your ASP.NET application,
please visit http://go.microsoft.com/fwlink/?LinkId=169433
-->
<configuration>
<appSettings>
<add key="killswitchtype" value="percentagesample"/>
<add key="rate" value="50"/>
</appSettings>
</configuration>
Sampling Function for JSP
These examples show the killswitch.jsp and web.config configuration file for JSP.
For the JSP, if the:
v request does not have parameters, then the client framework is always disabled.
v id request parameter exists, it is used to check the whitelist.
v
randomsample parameter exists, the percentage rate from the config.properties
file is used to determine how the server responds.
Example killswitch.jsp
This example shows the killswitch.jsp:
<%@ page language="java" contentType="text/html; charset=ISO-8859-1"
pageEncoding="ISO-8859-1"%>
<%@page import="java.util.Properties"%>
<%@page import="java.util.Date" %>
<%@ page import="java.net.*"%>
<%@ page import="java.io.*" errorPage=""%>
<%
InputStream stream = application
.getResourceAsStream("/config.properties");
134
IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide
Properties props = new Properties();
props.load(stream);
Boolean DEBUG = false;
DEBUG = ("true").equals(props.getProperty("debug"));
String id = request.getParameter("id");
String randomsample = request.getParameter("randomsample");
String killSwitchResponse = "";
String debugstr = "";
// white list
if (id != null && !id.isEmpty()) {
InputStream whitestream = application.getResourceAsStream(props
.getProperty("WhiteListFile"));
BufferedReader input = new BufferedReader(
new InputStreamReader(whitestream));
String line = "";
Boolean match = false;
while ((line = input.readLine()) != null) {
line = line.trim();
if (line.equals(id)) {
killSwitchResponse = "1";
match = true;
break;
}
}
input.close();
if (!match) {
killSwitchResponse = "0";
}
}
// If kill switch is by sample rate
else if (randomsample != null) {
int rand = (int) (Math.random() * 100);
int sampleRate = Integer.parseInt(props
.getProperty("samplerate"));
if (rand <= sampleRate) {
killSwitchResponse = "1";
} else {
killSwitchResponse = "0";
}
} else {
killSwitchResponse = "0";
}
out.print(killSwitchResponse);
//always give the path from root. This way it almost always works.
String nameOfTextFile = props.getProperty("logfile");
PrintWriter pw;
if (DEBUG) {
try {
pw = new PrintWriter(new FileOutputStream(nameOfTextFile,
true));
Date date = new java.util.Date();
debugstr = date.toString() + "\t";
if (request.getQueryString() != null) {
debugstr += request.getQueryString();
}
if("0".equals(killSwitchResponse))
pw.println(debugstr + "\tDisable");
else
pw.println(debugstr + "\tEnable");
//clean up
pw.close();
Chapter 7. Sample Code
135
} catch (IOException e) {
out.println(e.getMessage());
}
}
%>
Example web.config configuration file
This example shows the web.config configuration file for the killswitch.jsp:
WhiteListFile=whitelist.txt
samplerate =50
debug=true
logfile=/killswitchlog.txt
Sampling Function for PHP
These examples show the killswitch.php and web.config configuration file for
PHP.
Example killswitch.php
This example shows the killswitch.php:
<?php
$ini_array = parse_ini_file("config.ini", true);
//print_r($ini_array);
// if sample by percent
if($ini_array[’configtype’][’killswitchtype’] === ’percentagesample’){
$sampleRate = intval($ini_array[’percentagesample’][’rate’]);
killbysamplerate($sampleRate);
}
// if sample by whitelist
else {
}
function killbysamplerate($sampleRate){
$randomnumber = rand(1,100);
if($randomnumber <= $sampleRate){
echo ’1’;
}
else {
echo ’0’;
}
}
function killbywhitelist($whitelistpath){
}
?>
Example web.config configuration file
This example shows the web.config configuration file for the killswitch.php:
; This is a sample configuration file
; Comments start with ’;’, as in php.ini
[configtype]
killswitchtype=percentagesample
[percentagesample]
rate = 50
136
IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide
[whitelist]
x
y
z
JSON message type schemas and examples
JSON messages are categorized by type for processing. Tealeaf supports the
following JSON message types.
Message header properties
All messages contain message header properties consisting of two properties that
contain the message type and the time that is offset from the start of the session in
milliseconds. All time measurements in the JSON object schema are in
milliseconds.
Message list
This table lists and describes the supported JSON message types:
Table 34. Schema by Message Type
Type
Message Type
Description
1
“Client state (Type 1) messages” on
page 139
Any object that shows the current
state of client.
2
“ScreenView (Type 2) messages” on
page 141
Any message that indicates changes
in view on the "screen". The "screen"
is the page, view, or activity where
the visitor is in the application.
3
“Connections (Type 3) messages” on Any request or response that the
page 143
application performs during capture.
4
“Control (Type 4) messages” on page User interface control that fires an
144
event to which Tealeaf listens for
capture.
5
“Custom Event (Type 5) messages”
on page 147
Any custom log event from any
location in application.
6
“Exception (Type 6) messages” on
page 148
Any exception that the application
can throw.
7
“Performance (Type 7) messages” on Performance data from a browser.
page 149
8
“Web Storage (Type 8) messages” on Any object that contains information
page 150
about local storage information on
the browser.
9
“Overstat Hover Event (Type 9)
messages” on page 151
Any object that contains information
about mouse hover and hover-to-click
activity.
10
“Layout (Type 10) messages” on
page 151
Any message that shows the current
display layout of a native page.
11
“Gesture (Type 11) messages” on
page 154
Any message that shows a gesture
that fires a higher touch event that
Tealeaf listens to for capture.
Chapter 7. Sample Code
137
Table 34. Schema by Message Type (continued)
Type
Message Type
Description
12
“DOM Capture (Type 12) message
example” on page 166
Any object that contains serialized
HTML data (DOM snapshot) of the
page.
13
“GeoLocation (Type 13) messages”
on page 168
Messages that contain the geolocation
information about the device.
14
“Cookie (Type 14) message schema”
on page 168
Messages that contain the cookie data
for the application.
Message header properties
All messages contain message header properties consisting of two properties that
contain the message type and the time that is offset from the start of the session in
milliseconds.
All time measurements in the JSON object schema are in milliseconds.
Message header properties schema
This example shows the schema for the JSON message headers.
"offset": {
"title": "Milliseconds offset from start of stream",
"type": "integer",
"required": true
},"screenViewOffset": {
"title": "Milliseconds offset from start of ScreenView",
"type": "integer",
"required": true
},"count": {
"title": "The number of the message being sent",
"type": "integer",
"required": only used for UIC
},"fromWeb": {
"title": "Used to identify if it came from Web or Native application",
"type": "boolean",
"required": true
},"webviewId": {
"title": "Used to identify which webview it came from. This is only used
when fromWeb is true and it is a hybrid application ",
"type":"string",
"required": true only when fromWeb is true and it is a hybrid application
},"type": {
"title": "Message header type",
"type": [ {
"enum": [1],
description: "CLIENT_STATE"
},
"enum": [2],
description: "APPLICATION_CONTEXT"
}],
"enum": [3],
description: "CONNECTION"
},
"enum": [4],
description: "CONTROL"
},
"enum": [5],
description: "CUSTOM_EVENT"
}],
"enum": [6],
138
IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide
description: "EXCEPTION"
}],
"required": true
},
Client state (Type 1) messages
Client state messages are delivered on a schedule basis or on changes to the
environment state on the client. These are Type 1 JSON messages.
Note: Replay of client state messages is not supported, except for scroll events.
Replay of scroll events that are captured from the client is supported for mobile
sessions only in BBR only. See Search and Replay for Mobile Web.
Client State (Type 1) message schema
This is the schema for the Client State (Type 1) messages.
{
"$ref" : "MessageHeader",
"mobileState": {
"description": "Logical page being loaded for iOS and Android",
"type": "object",
"properties": {
"orientation": {
"title": "Current orientation of the device",
"type": "integer",
"required": true
},
"freeStorage": {
"title": "Amount of available storage in Mbytes",
"type": "number",
"required": true
},
"androidState": {
"description": "Current state in an Android device",
"type": "object",
"properties": {
"keyboardState": {
"title": "Current keyboard state",
"type": [ {
"enum": [0],
description: "Keyboard not hidden"
},
"enum": [1],
description: "Keyboard hidden"
},
"enum": [2],
description: "Undefined"
}],
"required": true
},
}
},
"battery": {
"title": "Battery level from 0 to 100",
"type": "number",
"required": true
},
"freeMemory": {
"title": "Amount of available memory in Mbytes",
"type": "number",
"required": true
},
"connectionType": {
"title": "Current connection type",
"type": "string",
Chapter 7. Sample Code
139
"required": true
},
"carrier": {
"title": "Carrier of device",
"type": "string",
"required": true
},
"networkReachability": {
"title": "Current network reachability",
"type": [ {
"enum": [0],
description: "Unknown"
},
"enum": [1],
description: "NotReachable"
},
"enum": [2],
description: "ReachableViaWIFI"
},
"enum": [3],
description: "ReachableViaWWAN"
}],
"required": true
},
"ip": {
"title": "Ip address of device",
"type": "string",
"required": true
}
},
"additionalProperties" : false
"clientState": {
"description": "Logical web page being loaded for UIC",
"type": "object",
"properties": {
"pageWidth": {
"title": "Width of the document of the web page",
"type": "integer",
"required": true
},
"pageHeight": {
"title": "Height of the document of the web page",
"type": "integer",
"required": true
},
"viewPortWidth": {
"title": "Width of viewport",
"type": "integer",
"required": true
},
"viewPortHeight": {
"title": "Height of viewport",
"type": "integer",
"required": true
},
"viewPortX": {
"title": "x position of scrollbar on viewport",
"type": "integer",
"required": true
},
"viewPortY": {
"title": "y position of scrollbar on viewport",
"type": "integer",
"required": true
},
"event": {
"title": "event that triggered the client state",
140
IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide
"type": "string",
"required": true
},
"deviceScale": {
"title": "scaling factor for fitting
page into window for replay",
"type": "integer",
"required": true
},
"viewTime": {
"title": "time in milliseconds user was on the event triggered",
"type": "integer",
"required": true
},
"viewPortXStart": {
"title": "initial start x position of scrollbar on viewport",
"type": "integer",
"required": only used in scroll events
},
"viewPortYStart": {
"title": "initial start y position of scrollbar on viewport",
"type": "integer",
"required": only used in scroll events
},
},
"additionalProperties" : false
}
}
Client State (Type 1) message example
This is an example of a Client State (Type 1) message. This example comes from an
Android native application.
{
"offset": 667,
"screenViewOffset": 4556,
"type": 1,
"mobileState": {
"orientation": 0,
"freeStorage": 33972224,
"androidState": {
"keyboardState": 0
},
"battery": 50,
"freeMemory": 64630784,
"connectionType": "UMTS",
"carrier": "Android",
"networkReachability": "ReachableViaWWAN",
"ip": "0.0.0.0"
}
}
ScreenView (Type 2) messages
ScreenView messages indicate steps in a visitor's experience with your application.
These steps can be logical page views in a web application, screen changes in a
mobile application, or steps in a business process. ScreenView messages are Type 2
JSON messages.
In Release 8.5 and earlier, these messages were called Application Context
messages.
ScreenView (Type 2) message schema
This is the schema for the ScreenView (Type 2) JSON messages.
Chapter 7. Sample Code
141
{
"$ref" : "MessageHeader",
"dcid": {
"title": "Unique identifier that is used to match the corresponding
DOM Capture message associated with this
message.",
"type": "string",
"required": false
},
"screenview/context": {
"description": "Logical page being loaded or unloaded",
"type": "object",
"properties": {
"type": {
"title": "Type of application context - LOAD or UNLOAD",
"type": "string",
"required": true
},
"name": {
"title": "Name of the logical page. This is given by customer
or it uses name of the class used
by the page.",
"type": "string",
"required": true
},
"url": {
"title": "URL path of the logical page",
"type": "string",
"required": false only used in UIC
},
"host": {
"title": "URL Host of the logical page",
"type": "string",
"required": false only used in UIC
},
"referrer": {
"title": "Previous logical page loaded, only used in LOAD",
"type": "string",
"required": false
},
"referrerUrl": {
"title": "Url of the previous logical page loaded",
"type": "string",
"required": false, not used in UIC
}
},
"additionalProperties" : false,
"required": false
}
}
ScreenView (Type 2) message example
This is an example of a ScreenView (Type 2) message. This example contains three
ScreenView messages, indicating page load and page unload events.
{
"offset": 124,
"contextOffset": 4556,
"type": 2,
"context": {
"type": "LOAD",
"name": "PAGE 2",
"referrer": "PAGE 1"
}
}
{
142
IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide
"type": 2,
"offset": 19216
"context": {
"type": "UNLOAD",
"name": "PAGE 2"
}
}
{
"type": 2,
"offset": 2144,
"contextOffset": 0,
"count": 9,
"fromWeb": true,
"webviewId": "webview1",
"screenview": {
"type": "LOAD",
"name": "Ford",
"url": "/dynamic/ford.aspx",
"host": "http://www.cartest.com",
"referrer": "BMW",
"referrerUrl": "/dynamic/bmw.aspx"
}
}
Connections (Type 3) messages
Connection messages provide information about how requests or responses are
managed by the client application. Connections messages are Type 3 JSON
messages.
Connections (Type 3) messages schema
This is the schema for Connections (Type 3) JSON messages.
{
"$ref" : "MessageHeader",
"connection": {
"description": "Connection in application",
"type": "object",
"properties": {
"statusCode": {
"title": "Status code of connection",
"type": "integer",
"required": true
},
"responseDataSize": {
"title": "Response data size",
"type": "number",
"required": true
},
"initTime": {
"title": "Initial time of connection",
"type": "number",
"required": true
},
"responseTime": {
"title": "Response time of connection",
"type": "number",
"required": true
},
"url": {
"title": "Url of connection",
"type": "string",
"required": true
Chapter 7. Sample Code
143
},
"loadTime": {
"title": "Load time from connection",
"type": "number",
"required": true
}
},
"additionalProperties" : false
}
}
Connections (Type 3) message example
This example shows the Connections (Type 3) JSON message.
{
"offset": 03829,
"type": 3,
"screenViewOffset": 45560,
"type": 3,
"connection": {
"statusCode": 200,
"responseDataSize": 0272,
"initTime": 01333669478556,
"responseTime": 02237,
"url": "http://google.com",
"url": "/store/js/tealeaf/
TeaLeafTarget.php??width=540&height=960&orientation=0",
"loadTime": 0
}
}
Control (Type 4) messages
Control messages are used to log user action and behavior. These messages consist
of a control identifier and a value that is returned by the identified control. Control
messages are Type 4 JSON messages.
The control identifiers are mapped to specific controls for the submitting client
framework. The value can be a number, a text string, or structured data.
Control (Type 4) message schema
This is the schema for Control (Type 4) messages.
The X and Y properties are not present in the UI Capture frameworks.
{
"$ref" : "MessageHeader",
"offset": {
"title": "Milliseconds offset from offset
for when focusIn of text fields occur",
"type": "integer",
"required": true
},
"target": {
"description": "Control being logged",
"type": "object",
"properties": {
"position": {
"description": "Position of control being logged",
"type": "object",
"properties": {
"x": {
"title": "X of the control",
"type": "integer",
"required": true
},
144
IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide
"y": {
"title": "Y of the control",
"type": "integer",
"required": true
},
"height": {
"title": "height of control",
"type": "integer",
"required": true
},
"width": {
"title": "width of control",
"type": "integer",
"required": true
},
"relXY": {
"title": "relative X & Y ratio that
can be from 0 to 1 with a
default value of 0.5",
"type": "string",
"required": true for click events
},
},
"additionalProperties" : false
}
"id": {
"title": "Id/Name/Tag of control",
"type": "string",
"required": true
},
idType": {
"title": "Indicates what id is based on: Native id (e.g. HTML ’id’
attribute): -1,
xPath: -2, or Custom attribute for UIC and
Hashcode value for Native: -3, or xPath for Native iOS/Android: -4",
"type": "integer",
"required": true
},
"dwell": {
"title": "Dwell time of control",
"type": "integer value that is in milliseconds",
"required": false
},
"visitedCount": {
"title": "Number of times a form control has
been visited to be filled by user.",
"type": "integer",
"required": false
},
"isParentLink": {
"title": "To indicate if control a A type tag",
"type": "boolean",
"required": false only in UIC for usability
},
"name": {
"title": "Name of control",
"type": "string",
"required": true in UIC
},
"type": {
"title": "Type of control",
"type": "string",
"required": true
},
"subType": {
"title": "SubType of control",
"type": "string",
Chapter 7. Sample Code
145
"required": true
},
"tlType": {
"title": "tlType of control that normalizes
the control type for eventing",
"type": "string",
"required": true
},
"prevState": {
"title": "Previous state of control",
"type": "object",
"required": true,
"properties": {
"?": { // Could be any variable name given by developer
"title": "Additional data in string format",
"type": "string",
"required": false
}
},
"currState": {
"title": "Current state of control",
"type": "object",
"required": true,
"properties": {
"?": { // Could be any variable name given by developer
"title": "Additional data in string format",
"type": "string",
"required": false
}
}
},
"additionalProperties" : false
}
"event": {
"description": "Event from control",
"type": "object",
"properties": {
"tlEvent": {
"title": "Tealeaf type of event",
"type": "string",
"required": true
},
"type": {
"title": "Type of event",
"type": "string",
"required": true
},
"subType": {
"title": "Subtype of event",
"type": "string",
"required": true
}
},
"additionalProperties" : false
}
}
Control (Type 4) message example
This is an example of a Control (Type 4) message.
This example shows a control with an idType of XPATH, which means no id was
assigned to the control in the application so Tealeaf traversed the layout and
created an XPATH id for the control:,
146
IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide
{
"screenviewOffset":380,
"target":{
"id":"[KV,0]",
"position":{
"y":331,
"x":0,
"width":320,
"height":202
},
"idType":"-4",
"currState":{
"y":"0",
"x":"0"
},
"style":{
"paddingTop":2,
"textBGAlphaColor":255,
"bgAlphaColor":255,
"paddingBottom":0,
"paddingLeft":0,
"hidden":false,
"paddingRight":0
},
"subType":"View",
"type":"KeyboardView",
"tlType":"keyboard"
},
"type":4,
"offset":728,
"count":3,
"fromWeb":false,
"event":{
"type":"UIKeyboardDidShowNotification",
"tlEvent": "kbDisplayed"
}
},
Custom Event (Type 5) messages
The Custom Event messages are used to custom log any event from any place in
the application. Custom Event messages are Type 5 JSON messages.
Custom Event (Type 5) message schema
This is the schema for the Custom Event (Type 5) messages.
The only required field is the name of the custom event (name value).
Application-specific code must be created to process this logged message type.
{
"$ref" : "MessageHeader",
"customEvent": {
"description": "Custom event message",
"type": "object",
"properties": {
"name": {
"title": "Exception name/type",
"type": "string",
"required": true
},
"data": "Additional properties given by developer",
"type": "object",
"required": truefalse,
"properties": {
"?": { // Could be any variable name given by developer
"title": "Additional data in string format",
Chapter 7. Sample Code
147
"type": "string",
"required": false
}
},
},
"additionalProperties" : false
}
}
Custom Event (Type 5) message example
This is an example of a Custom Event (Type 5) message. This custom event
message provides the name of the custom event (MyEvent_1) and several custom
properties in the data section.
{
"type": 5,
"offset": 17981,
"screenViewOffset": 4556,
"customEvent": {
"name": "MyEvent_1",
"data": {
"Foo": "Bar",
"validationError": "Invalid zipcode.",
"ajaxPerformance": 56734
}
}
}
Exception (Type 6) messages
The exceptions messages type records the name and description of an exception
occurring on the client application. Exception messages are Type 6 JSON messages.
Exception (Type 6) message schema
This is the schema for the Exception (Type 6) messages.
{
"$ref" : "MessageHeader",
"exception": {
"description": "Exception description message",
"type": "object",
"properties": {
"description": {
"title": "Exception message from api call",
"type": "string",
"required": true
},
"name": {
"title": "Exception name/type",
"type": "string",
"required": true, not for UIC
},
"stackTrace": {
"title": "Exception stacktrace given by framework",
"type": "string",
"required": true, not for UIC
},
"url": {
"title": "Url where exception ocurred",
"type": "string",
"required": true for UIC
},
"fileName": {
"title": "File name where exception ocurred",
"type": "string",
"required": true for iOS, not for UIC
},
148
IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide
"line": {
"title": "Line number where eception occurred.",
"type": "string",
"required": true for UIC and iOS
},
"unhandled": {
"title": "Whether exception had a try catch around it.",
"type": "boolean",
"required": true, not for UIC
},
"data": {
"title": "User defined data being passed with
user info from system",
"type": "object",
"required": true for iOS, not for UIC
"properties": {
"userInfo": {
"type": "object",
"title": "OS information from error or exception",
"required": iOS optional (data is JSON
serializable or not)
},
"message": {
"type": "string",
"title":"User supplied message on error event",
"required":iOS optional (not on exceptions
required on error)
}
},
},
},
"additionalProperties" : false
}
}
Exception (Type 6) message example
This is an example of an Exception (Type 6) message. This example exception
indicates an attempt to read a property named 'type' of a variable or value which
is undefined.
{
"type" : 6,
"offset" : 4606,
"screenviewOffset" : 4603,
"count" : 3,
"fromWeb" : true,
"exception" : {
"description" : "Uncaught TypeError: Cannot read
property ’type’ of undefined",
"url" : "http://www.xyz.com/js/badscript.js",
"line" : 258
}
}
Performance (Type 7) messages
Performance messages show performance data from a browser. Performance
messages are Type 7 JSON messages.
Performance (Type 7) message schema
This is the schema for Performance (Type 7) messages.
Chapter 7. Sample Code
149
{
"$ref" : "MessageHeader",
"performance": {
"description": "Performance message",
"type": "object",
"properties": {
},
"additionalProperties" : false
}
}
Performance (Type 7) message example
This is an example of a Performance (Type 7) message.
{
"type": 7,
"offset": 9182,
"screenviewOffset": 9181,
"count": 3,
"fromWeb": true,
"performance": {
"timing": {
"redirectEnd": 0,
"secureConnectionStart": 0,
"domainLookupStart": 159,
"domContentLoadedEventStart": 2531,
"domainLookupEnd": 159,
"domContentLoadedEventEnd": 2551,
"fetchStart": 159,
"connectEnd": 166,
"responseEnd": 1774,
"domComplete": 2760,
"responseStart": 728,
"requestStart": 166,
"redirectStart": 0,
"unloadEventEnd": 0,
"domInteractive": 2531,
"connectStart": 165,
"unloadEventStart": 0,
"domLoading": 1769,
"loadEventStart": 2760,
"navigationStart": 0,
"loadEventEnd": 2780,
"renderTime": 986
},
"navigation": {
"type": "NAVIGATE",
"redirectCount": 0
}
}
}
Web Storage (Type 8) messages
Web Storage messages are any objects that contain information about local storage
information on the browser. Web Storage messages are Type 8 JSON messages.
Web Storage (Type 8) message schema
This is the schema for the Web Storage (Type 8) messages.
"$ref" : "MessageHeader",
webStorage: {
key : &ldquo;string&rdquo;,
value: &ldquo;string&rdquo;,
}
150
IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide
Web Storage (Type 8) message example
This is an example of a Web Storage (Type 8) message.
{
type: 8,
offset: 25,
screenviewOffset: 23,
count: 2,
fromWeb: true,
webStorage: {
key: "vistCount"
value: "5"
}
}
Overstat Hover Event (Type 9) messages
Overstat® Hover Event messages are any object containing information about
mouse hover and hover-to-click activity. Overstat Hover Event messages are Type 9
JSON messages.
Overstat Hover Event (Type 9) message schema
This is the schema for Overstat Hover Event (Type 9) messages
"$ref" : "MessageHeader",
event: {
xPath: "string",
hoverDuration: int,
hoverToClick: boolean,
gridPosition: {
x: int,
y: int
}
}
Overstat Hover Event (Type 9) message example
This is an example of a Overstat Hover Event (Type 9) message.
{
type: 9,
offset: 25,
screenviewOffset: 23,
count: 2,
fromWeb: true,
event: {
xPath: "[\"ii\"]",
hoverDuration: 5457,
hoverToClick: false,
gridPosition: {
x: 3,
y: 2
}
}
Layout (Type 10) messages
Layout messages show the current display layout of a native page. Layout
messages are Type 10 JSON messages.
Layout (Type 10) message schema
This is the schema for Layout (Type 10) messages.
"$ref" : "MessageHeader",
"version": {
"description": "Message Version, must be in x.x format",
"type": "string",
"required": true
Chapter 7. Sample Code
151
},
"layoutControl": {
"description": "Control on application page",
"type": "object",
"properties": {
"position": {
"description": "Position of control",
"type": "object",
"properties": {
"x": {
"title": "X of the control",
"type": "integer",
"required": true
},
"y": {
"title": "Y of the control",
"type": "integer",
"required": true
},
"height": {
"title": "height of control",
"type": "integer",
"required": true
},
"width": {
"title": "width of control",
"type": "integer",
"required": true
}
},
"additionalProperties" : false
}
"id": {
"title": "Id/Name/Tag of control",
"type": "string",
"required": true
},
"type": {
"title": "Type of control",
"type": "string",
"required": true
},
"subType": {
"title": "SubType of control",
"type": "string",
"required": true
},
"tlType": {
"title": "tlType of control that normalizes the control type for eventing",
"type": "string",
"required": true
},
"currState": {
"title": "Current state of control",
"type": "object",
"required": true,
"properties": {
"?": { // Could be any variable name given by developer
"title": "Additional data in string format",
"type": "string",
"required": false
}
}
},
"style" : {
"title": "Style of the control",
"type": "object",
152
IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide
"required": true,
"properties": {
"textColor": {
"title": "Text color",
"type": "string",
"required": true
},
"textAlphaColor": {
"title": "Text alpha color",
"type": "string",
"required": true
},
"textBGColor": {
"title": "Text background color",
"type": "string",
"required": true
},
"textBGAlphaColor": {
"title": "Text background alpha color",
"type": "string",
"required": true
},
"bgColor": {
"title": "Background color",
"type": "string",
"required": true
},
"bgAlphaColor": {
"title": "Background alpha color",
"type": "string",
"required": true
}
}
}
},
"additionalProperties" : false
}
Layout (Type 10) message example
This is an example of a Layout (Type 10 ) message.
{
"offset": 27004,
"screenviewOffset": 4706,
"count": 16,
"fromWeb": false,
"type": 10,
"version" : "1.0",
"orientation" : 0,
"deviceHeight": 592,
"deviceWidth": 360,
"layout": {
"name": "loginPage",
"class": "loginPageActivty",
"controls": [
{
"position": {
"y": 38,
"height": 96,
"width": 720,
"x": 0
},
"id": "com.tl.uiwidget:id\/userNameLabel",
"idType": -1,
"type": "UILabel",
"subType": "UIView",
Chapter 7. Sample Code
153
"tlType": "label",
"currState": {
"text": "User name*"
},
"style": {
"textColor": 16777215,
"textAlphaColor": 1,
"textBGColor": 0,
"textBGAlphaColor": 0,
"bgColor": 0,
"bgAlphaColor": 0
}
},
{...},
{...}
]
}
}
Gesture (Type 11) messages
Gesture messages are used to log user action and behavior. A Gesture message
consists of a control identifier and a the value returned by that control. The control
identifiers are mapped to specific controls on the client logging platform. The value
can be a number, a text string or structured data. Gesture messages are Type 12
JSON messages.
Gesture (Type 11) message schema
This is the schema for Gesture (Type 11) messages.
Touch events
This is a JSON object that represents a gesture finger that is linked to control
underneath the finger. It is reused in targets property of gesture type 11.This is the
schema for touch events:
{
"$ref" : "MessageHeader",
"focusInOffset": {
"title": "Milliseconds offset from offset for when focusIn of text
fields occur",
"type": "integer",
"required": false
},
"target": {
"description": "Control being logged",
"type": "object",
"properties": {
"position": {
"description": "Position of control being logged",
"type": "object",
"properties": {
"x": {
"title": "X of the control",
"type": "integer",
"required": true
},
"y": {
"title": "Y of the control",
"type": "integer",
"required": true
},
"height": {
"title": "height of control",
"type": "integer",
154
IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide
"required": true
},
"width": {
"title": "width of control",
"type": "integer",
"required": true
},
"relXY": {
"title": "relative X & Y ratio that can be
from 0
to 1 with a default value of 0.5",
"type": "string",
"required": true for click events
},
"scrollX": {
"title": "scroll X of the page",
"type": "integer",
"required": true
},
"scrollY": {
"title": "scroll Y of the page",
"type": "integer",
"required": true
},
},
"additionalProperties" : false
}
"id": {
"title": "Id/Name/Tag of control",
"type": "string",
"required": true
},
"idType":{
"title": "Indicates what id is based on: Native id (e.g. HTML
’id’ attribute): -1,
xPath: -2, or Custom attribute for
UIC and Hashcode value for Native: -3, or xPath for Native iOS/Android: -4",
"type": "integer",
"required": true
},
"dwell": {
"title": "Dwell time of control",
"type": "integer value that is in milliseconds",
"required": false
},
"focusInOffset": {
"title": "Offset when control got focus",
"type": "integer value that is in milliseconds",
"required": true in UIC
},
"visitedCount": {
"title": "Number of times a form control has been visited to be
filled by
user.",
"type": "integer",
"required": false
},
"isParentLink": {
"title": "To indicate if control a A type tag",
"type": "boolean",
"required": false only in UIC for usability
},
"name": {
"title": "Name of control",
"type": "string",
"required": true in UIC
},
Chapter 7. Sample Code
155
"type": {
"title": "Type of control",
"type": "string",
"required": true
},
"subType": {
"title": "SubType of control",
"type": "string",
"required": true
},
"tlType": {
"title": "tlType of control that normalizes the control type for
eventing",
"type": "string",
"required": true
},
"prevState": {
"title": "Previous state of control",
"type": "object",
"required": false,
"properties": {
"?": { // Could be any variable name given by developer
"title": "Additional data in string format",
"type": "string",
"required": false
}
}
},
"currState": {
"title": "Current state of control",
"type": "object",
"required": true,
"properties": {
"?": { // Could be any variable name given by developer
"title": "Additional data in string format",
"type": "string",
"required": false
}
}
}
},
"additionalProperties" : false
}
"event": {
"description": "Event from control",
"type": "object",
"properties": {
"tlEvent": {
"title": "Tealeaf type of event",
"type": "string",
"required": true
},
"type": {
"title": "Type of event",
"type": "string",
"required": false
},
"subType": {
"title": "Subtype of event",
"type": "string",
"required": false
}
},
"additionalProperties" : false
}}
156
IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide
Tap event schema
This contains only one touch object. This is the schema for tap events:
{
"$ref" : "MessageHeader",
"event": {
"description": "Event from control",
"type": "object",
"properties": {
"tlEvent": {
"title": "Tealeaf type of event",
"type": "string",
"required": true
},
"type": {
"title": "Type of event framework reports",
"type": "string",
"required": false
}
}
},
"touches": {
"description": "Gestures touch objects per finger.",
"type": "array",
"required": true
"items": {
"description": "Touch objects per finger starting with intial
and ends with last object when finger is lifted from device.",
"type": "array",
"required": true,
"$ref": "Touch"
}
}
}
}
Swipe event schema
The swipe event contains only one touch object which will be the initial location
with its corresponding direction and velocity. This is the schema for swipe events:
{
"$ref" : "MessageHeader",
"event": {
"description": "Event from control",
"type": "object",
"properties": {
"tlEvent": {
"title": "Tealeaf type of event",
"type": "string",
"required": true
},
"type": {
"title": "Type of event framework reports",
"type": "string",
"required": false
}
}
},
"touches": {
"description": "Gestures touch objects per finger.",
"type": "array",
"required": true
"items": {
"description": "Touch objects per finger starting with intial
and ends with last object when finger is lifted from device.",
Chapter 7. Sample Code
157
"type": "array",
"required": true,
"$ref": "Touch"
}
}
},
"direction": {
"title": "The direction of the swipe which can be up, down. left or
right.",
"type": "string",
"required": true
},
"velocityX": {
"title": "The velocity of this measured in pixels per second along the
x axis",
"type": "float",
"required": true
},
"velocityY": {
"title": "The velocity of this measured in pixels per second along the
y axis",
"type": "float",
"required": false
}
}
Pinch events
The pinch event contains only an initial touch object per finger and the last touch
object per finger, with the corresponding direction. This is the schema for pinch
events:
{
"$ref" : "MessageHeader",
"event": {
"description": "Event from control",
"type": "object",
"properties": {
"tlEvent": {
"title": "Tealeaf type of event",
"type": "string",
"required": true
},
"type": {
"title": "Type of event framework reports",
"type": "string",
"required": false
}
}
},
"touches": {
"description": "Gestures touch objects per finger.",
"type": "array",
"required": true
"items": {
"description": "Touch objects per finger starting with intial and
ends with last object when finger is lifted from device.",
"type": "array",
"required": true,
"$ref": "Touch"
}
}
},
"direction": {
"title": "Direction of pinch which can be open or close",
158
IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide
"type": "string",
"required": true
}
}
Gesture (Type 11) message example
These are examples of UIC SDK Gesture (Type 11) messages.
Tap events
This example is a gesture message for a tap event:
{
"fromWeb": false,
"type": 11,
"offset": 46788,
"screenviewOffset": 42208,
"count": 14,
"event": {
"type": "ACTION_DOWN",
"tlEvent": "tap"
},
"touches": [
[
{
"position": {
"x": 179,
"y": 543
},
"control": {
"position": {
"height": 184,
"width": 1080,
"relXY": "0.17,0.93"
"scrollX": 10
"scrollY": 15
},
"id": "[RL,0]",
"idType": -4,
"type": "RelativeLayout",
"subType": "ViewGroup",
"tlType": "canvas"
}
}
]
]
}
Double tap events
This example is a gesture message for a double tap event:
{
"fromWeb": false,
"type": 11,
"offset": 49585,
"screenviewOffset": 45005,
"count": 15,
"event": {
"type": "ACTION_DOWN",
"tlEvent": "doubleTap"
},
"touches": [
[
{
"position": {
Chapter 7. Sample Code
159
"x": 182,
"y": 520
},
"control": {
"position": {
"height": 184,
"width": 1080,
"relXY": "0.17,0.8"
"scrollX": 10
"scrollY": 15
},
"id": "[RL,0]",
"idType": -4,
"type": "RelativeLayout",
"subType": "ViewGroup",
"tlType": "canvas"
}
}
]
]
}
Tap hold events
This example is a gesture message for a tap hold event:
{
"fromWeb": false,
"type": 11,
"offset": 52389,
"screenviewOffset": 47809,
"count": 16,
"event": {
"type": "ACTION_DOWN",
"tlEvent": "tapHold"
},
"touches": [
[
{
"position": {
"x": 182,
"y": 536
},
"control": {
"position": {
"height": 184,
"width": 1080,
"relXY": "0.17,0.89"
"scrollX": 10
"scrollY": 15
},
"id": "[RL,0]",
"idType": -4,
"type": "RelativeLayout",
"subType": "ViewGroup",
"tlType": "canvas"
}
}
]
]
}
160
IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide
Swipe event example
The swipe event contains only one touch object which will be the initial location
with its corresponding direction and velocity. This example is a message for a
swipe event:
{
"fromWeb": false,
"type": 11,
"offset": 54409,
"screenviewOffset": 49829,
"count": 17,
"event": {
"type": "ACTION_DOWN",
"tlEvent": "swipe"
},
"direction": "right",
"velocityX": 7762.8466796875,
"velocityY": 127.47991943359375,
"touches": [
[
{
"position": {
"x": 75,
"y": 538
},
"control": {
"position": {
"height": 184,
"width": 1080,
"relXY": "0.07,0.9"
"scrollX": 10
"scrollY": 15
},
"id": "[RL,0]",
"type": "RelativeLayout",
"subType": "ViewGroup",
"tlType": "canvas"
}
},
{
"position": {
"x": 212,
"y": 526
},
"control": {
"position": {
"height": 184,
"width": 1080,
"relXY": "0.2,0.84"
"scrollX": 10
"scrollY": 15
},
"id": "[RL,0]",
"idType": -4,
"type": "RelativeLayout",
"subType": "ViewGroup",
"tlType": "canvas"
}
}
]
]
}
Chapter 7. Sample Code
161
Pinch events
The pinch event contains only an initial touch object per finger and the last touch
object per finger, with the corresponding direction. This example is a message for a
pinch event:
{
"type": 11,
"offset": 2220,
"screenviewOffset": 2022,
"count": 6,
"fromWeb": false,
"event": {
"tlEvent": "pinch",
"type": "onScale"
},
"touches": [
[
{
"position": {
"y": 388,
"x": 0
},
"control": {
"position": {
"height": 100,
"width": 100,
"relXY": "0.6,0.8"
"scrollX": 10
"scrollY": 15
},
"id": "com.tl.uic.appDarkHolo:id/imageView1",
"idType": -1,
"type": "ImageView",
"subType": "View",
"tlType": "image"
}
},
{
"position": {
"y": 388,
"x": 400
},
"control": {
"position": {
"height": 100,
"width": 100,
"relXY": "0.4,0.7"
"scrollX": 10
"scrollY": 15
},
"id": "com.tl.uic.appDarkHolo:id/imageView1",
"idType": -1,
"type": "ImageView",
"subType": "View",
"tlType": "image"
}
}
],
[
{
"position": {
"y": 388,
"x": 800
},
"control": {
"position": {
162
IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide
"height": 100,
"width": 100,
"relXY": "0.6,0.8"
"scrollX": 10
"scrollY": 15
},
"id": "com.tl.uic.appDarkHolo:id/imageView1",
"idType": -1,
"type": "ImageView",
"subType": "View",
"tlType": "image"
}
},
{
"position": {
"y": 388,
"x": 500
},
"control": {
"position": {
"height": 100,
"width": 100,
"relXY": "0.4,0.7"
"scrollX": 10
"scrollY": 15
},
"id": "com.tl.uic.appDarkHolo:id/imageView1",
"idType": -1,
"type": "ImageView",
"subType": "View",
"tlType": "image"
}
}
]
],
"direction": "close"
}
DOM Capture (Type 12) messages
DOM Capture messages are objects that contain serialized HTML data (DOM
snapshot) of the page. DOM Capture Messages are Type 12 JSON messages.
DOM Capture (Type 12) message schema
This is the schema for the DOM Capture (Type 12) messages.
"$ref" : "MessageHeader",
"domCapture": {
"description": "Serialized HTML snapshot of the document.",
"type": "object",
"properties": {
"dcid": {
"title": "Unique identifier of this DOM snapshot.",
"type": "string",
"required": true
}
"fullDOM": {
"title": "Flag indicating if the contents of this message contain
a full DOM or a DOM diff.",
"type": "boolean",
"required": false
},
"charset": {
"title": "Browser reported charset of the document.",
"type": "string",
"required": false
},
Chapter 7. Sample Code
163
"root": {
"title": "Serialized HTML of the document.",
"type": "string",
"required": false
},
"diffs": {
"title": "List of DOM diff entries. Each entry can contain
a HTML Diff or an attribute diff.",
"type": "array",
"required": false,
"Item": {
"title": "An object containing the DOM diff. The diff can
be a HTML diff or an attribute diff.",
"type": "object",
"required": false,
"properties": {
"xpath": {
"title": "The xpath of the node.",
"type": "string",
"required": true
},
"root": {
"title": "Serialized HTML of the node referred
by the xpath. Presence of this property constitutes a HTML diff.",
"type": "string",
"required": false
},
"attributes": {
"title": "List of attribute diff entries. Each entry
contains a single attribute diff corresponding to the node
referred by the xpath. Presence of this property constitutes
an attribute diff.",
"type": "array",
"required": false,
"Item": {
"title": "An object containing the attribute
diff.",
"type": "object",
"required": true,
"properties": {
"name": {
"title": "The attribute name.",
"type": "string",
"required": true
},
"value": {
"title": "The attribute value.",
"type": "string",
"required": true
}
}
}
}
}
}
},
"eventOn": {
"title": "Flag indicating if Tealeaf eventing should be enabled
for this DOM Capture snapshot.",
"type": "boolean",
"required": false
},
"url": {
"title": "URL path of the snapshot document",
"type": "string",
"required": false
},
164
IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide
"host": {
"title": "URL Host of the snapshot document",
"type": "string",
"required": false
},
"error": {
"title": "Error message",
"type": "string",
"required": false
},
"errorCode": {
"title": "Error code corresponding to the error message.",
"type": "integer",
"required": false
},
"frames": {
"title": "Serialized HTML of any child frames of the document",
"type": "array",
"required": false,
"Item": {
"title": "An object containing serialized HTML of the frame",
"type": "object",
"required": false,
"properties": {
"tltid": {
"title": "Unique identifier for this frame. Same tltid is
added to the serialized HTML source of the parent."
"type": "string",
"required": true
},
"charset": {
"title": "Browser reported charset of the document.",
"type": "string",
"required": true
},
"url": {
"title": "URL path of the snapshot document",
"type": "string",
"required": true
},
"host": {
"title": "URL Host of the snapshot document",
"type": "string",
"required": true
},
"root": {
"title": "Serialized HTML of the document.",
"type": "string",
"required": true
}
}
}
},
"canvas" : {
"title": "Serialized data of the canvas snapshot.",
"type": "array",
"required": false,
}
},
"additionalProperties" : false
}
Chapter 7. Sample Code
165
DOM Capture (Type 12) message example
This is an example of a DOM Capture (Type 12) message.
This example shows a DOM message with full DOM capture enabled:
{
// DOM Capture messages use type 12
"type": 12,
// The standard UIC message properties
"offset": 16821,
"screenviewOffset": 16817,
"count": 5,
"fromWeb": true,
"domCapture": {
"dcid": "dcid-3"
"fullDOM":true
"charset": "ISO-8859-1",
"root": "<html><body><iframe id="greeting.html" tltid="tlt-4"/>
</body></html>",
"host": "http://www.uictest.com",
"url": "/h4/dcTest.html",
"eventOn": true,
"frames": [
{
"tltid": "tlt-4",
"root": "<html><body>Hello, World!</body></html>",
"charset": "ISO-8859-1",
"host": "http://www.uictest.com",
"url": "/h4/greeting.html"
}
],
"canvas": []
}
}
This example shows a DOM capture message with DOM diff enabled:
{
"type": 12,
"offset": 13874,
"screenviewOffset": 13861,
"count": 6,
"fromWeb": true,
"domCapture": {
"fullDOM": false,
"diffs": [
{
"xpath": "[[\"html\",0],[\"body\",0],[\"div\",1]]",
"root": "<div class=\"bluebg\"><div><div>Input 1<input
type=\"text\" name=\"ip-x-1\" value=\"\"></div></div></div>"
}
],
"dcid": "dcid-3.1437256358764",
"eventOn": false
}
}
DOM Diff (with HTML and attribute diff):
{
"type": 12,
"offset": 5794,
"screenviewOffset": 5777,
166
IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide
"count": 8,
"fromWeb": true,
"domCapture": {
"fullDOM": false,
"diffs": [
{
"xpath": "[[\"html\",0],[\"body\",0],[\"div\",2],[\"div\",1]]",
"root": "<div>Select List:<select name=\"select.pvt\"><option
value=\"O1\" selected=\"selected\">1</option><option value=\"O2\">2</option>
<option value=\"O3\">3</option></select></div>"
},
{
"xpath": "[[\"cb1\"]]",
"attributes": [
{
"name": "style",
"value": "height: 13px; width: 13px; visibility: hidden;"
}
]
},
{
"xpath": "[[\"container_1\"],[\"table\",0],[\"tbody\",0],
[\"tr\",2],[\"td\",1],[\"select\",0]]",
"attributes": [
{
"name": "style",
"value": "visibility: hidden;"
}
]
}
],
"dcid": "dcid-3.1437256879815",
"eventOn": false
}
}
This example shows the error message when the captured DOM message length
exceeds the configured threshold:
{
// DOM Capture messages use type 12
"type": 12,
// The standard UIC message properties
"offset": 16821,
"screenviewOffset": 16817,
"count": 5,
"fromWeb": true,
// The DOM Capture data is namespaced in the domCapture object
"domCapture": {
// The "error" contains the verbose error message explaining why the
DOM Capture couldn’t be performed.
"error": "Captured length (18045) exceeded limit (10000).",
// The "errorCode" contains the numeric code for this error message.
Currently, there is only 1 error message.
"errorCode": 101,
// The "dcid" property contains the unique string identifying this
DOM Capture within the page instance.
"dcid": "dcid-1.1414088027401"
}
}
Chapter 7. Sample Code
167
GeoLocation (Type 13) messages
A GeoLocation message logs a user's location information. The message consists of
a control identifier and a GeoLocation value. If the user has given the permission
to use location data, GeoLocation returns latitude, longitude, accuracy values. If
the user has not given permission to use location data, GeoLocation returns an
error code and error string.
GeoLocation (Type 13) message schemas
This is the schema for the GeoLocation (Type 13) JSON messages:
This is the schema for messages from a device that the user has given permission
to use location data:
"$ref" : "MessageHeader",
"geolocation": {
"lat": double,
"long": double,
"accuracy": float
}
This is the schema for messages from a device that the user has not given
permission to use location data:
"$ref" : "MessageHeader",
"geolocation": {
"errorCode": int,
"error": "string",
}
GeoLocation (Type 13) message examples
This is an example of the GeoLocation (Type 13) JSON message.
This is an example of a message from a device that the user has given permission
to use location data:
{
"type": 13,
"geolocation": {
"lat": 37.5680,
"long": -122.3292,
"accuracy": 65
}
}
This is an example of a message from a device that the user has not given
permission to use location data:
{
"type": 13,
"geolocation": {
"errorCode": 201,
"error": "permission denied",
}
}
Cookie (Type 14) message schema
This is the schema that is used to capture cookie information from an application
as name-value pairs.
"$ref" : "MessageHeader",
cookies: {
cookieName: cookieValue}
The following example records the cookie values after each screenview load.
168
IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide
{
"type" : 14,
"offset" : 5796,
"screenviewOffset" : 10,
"count" : 4,
"fromWeb" : true,
"cookies" :{
"cookieName1" : "valueA",
"cookieName2": "valueB"
}
}
Chapter 7. Sample Code
169
170
IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide
Chapter 8. Troubleshooting
Troubleshooting and debugging - enabling raw request and response
headers
For debugging purposes, it may be useful to include the raw request and the
response headers in the data that is passed by the PCA to the Canister. This
method is useful if you are not seeing any JSON data that is parsed in Tealeaf.
Including these sections in your Tealeaf sessions can significantly increase the
storage requirements for mobile sessions. These options should be enabled only for
debugging purposes.
In the PCA Pipeline tab, set the following properties:
Setting Value
Include Raw Request
true
Include Response Headers
true
See "PCA Web Console - Pipeline Tab" in the IBM Tealeaf Passive Capture Application
Manual section.
Troubleshooting - managing client-side issues
The section that follows describes how the IBM Tealeaf Android SDK manages
application crashes, exceptions, or other issues that can occur on the mobile device
or the network.
Exceptions or crashes
Application exceptions are logged and reported to IBM Tealeaf in JSON format.
For devices that run iOS, a transmission of the current exception to the server is
attempted. A copy is added to the set of messages queued locally and is sent the
next time that the application is started.
For Android devices, all local data in the device is flushed. The exception object is
transmitted to the server.
Power failures
A TL Library Error: File Not Found exception might be caused by disruption to
the monitored application. If the user turned off the application or if it is closed,
the posting task is disabled. When the application restarts, the library begins
sending the queued JSON messages. However, if some of these reference images
that are no longer available, the File Not Found error is generated.
If power failures are a persistent problem, you can configure the client application
to save to local disk at smaller intervals, sending to server at more frequent
intervals. You can modify the local cache size and POSTs from the client. These
settingssettings are managed with the configuration file.
© Copyright IBM Corp. 1999, 2016
171
Kill switch
If the device is unable to connect to the target page, the device does not capture
data.
Network issues
If there are network connectivity issues, these events are logged as connection
objects with details on the issues.
v For GET issues as a result of application interruptions, an exception object is
generated.
v If the network connection is interrupted, user actions are saved and sent later.
Low memory or local storage
If low memory or low local storage conditions occur, a custom log message is
generated.
For devices that run iOS, user data is trimmed in memory until more memory
becomes available.
For Android devices, all collected data on the device is flushed, and the Android
SDK is disabled for the device.
172
IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide
Chapter 9. IBM Tealeaf documentation and help
IBM Tealeaf provides documentation and help for users, developers, and
administrators.
Viewing product documentation
All IBM Tealeaf product documentation is available at the following website:
https://tealeaf.support.ibmcloud.com/
Use the information in the following table to view the product documentation for
IBM Tealeaf:
Table 35. Getting help
To view...
Do this...
Product documentation
On the IBM Tealeaf portal, go to ? > Product
Documentation.
IBM Tealeaf Knowledge Center
On the IBM Tealeaf portal, go to ? > Product
Documentation and select IBM Tealeaf
Customer Experience in the ExperienceOne
Knowledge Center.
Help for a page on the IBM Tealeaf Portal
On the IBM Tealeaf portal, go to ? > Help
for This Page.
Help for IBM Tealeaf CX PCA
On the IBM Tealeaf CX PCA web interface,
select Guide to access the IBM Tealeaf CX
PCA Manual.
Available documents for IBM Tealeaf products
The following table is a list of available documents for all IBM Tealeaf products:
Table 36. Available documentation for IBM Tealeaf products.
IBM Tealeaf products
Available documents
IBM Tealeaf CX
v IBM Tealeaf Customer Experience Overview
Guide
v IBM Tealeaf CX Client Framework Data
Integration Guide
v IBM Tealeaf CX Configuration Manual
v IBM Tealeaf CX Cookie Injector Manual
v IBM Tealeaf CX Databases Guide
v IBM Tealeaf CX Event Manager Manual
v IBM Tealeaf CX Glossary
v IBM Tealeaf CX Installation Manual
v IBM Tealeaf CX PCA Manual
v IBM Tealeaf CX PCA Release Notes
© Copyright IBM Corp. 1999, 2016
173
Table 36. Available documentation for IBM Tealeaf products (continued).
IBM Tealeaf products
Available documents
IBM Tealeaf CX
v IBM Tealeaf CX RealiTea Viewer Client Side
Capture Manual
v IBM Tealeaf CX RealiTea Viewer User
Manual
v IBM Tealeaf CX Release Notes
v IBM Tealeaf CX Release Upgrade Manual
v IBM Tealeaf CX Support Troubleshooting
FAQ
v IBM Tealeaf CX Troubleshooting Guide
v IBM Tealeaf CX UI Capture j2 Guide
v IBM Tealeaf CX UI Capture j2 Release Notes
IBM Tealeaf cxImpact
v IBM Tealeaf cxImpact Administration Manual
v IBM Tealeaf cxImpact User Manual
v IBM Tealeaf cxImpact Reporting Guide
IBM Tealeaf cxConnect
v IBM Tealeaf cxConnect for Data Analysis
Administration Manual
v IBM Tealeaf cxConnect for Voice of Customer
Administration Manual
v IBM Tealeaf cxConnect for Web Analytics
Administration Manual
IBM Tealeaf cxOverstat
IBM Tealeaf cxOverstat User Manual
IBM Tealeaf cxReveal
v IBM Tealeaf cxReveal Administration Manual
v IBM Tealeaf cxReveal API Guide
v IBM Tealeaf cxReveal User Manual
IBM Tealeaf cxVerify
v IBM Tealeaf cxVerify Installation Guide
v IBM Tealeaf cxVerify User's Guide
IBM Tealeaf cxView
IBM Tealeaf cxView User's Guide
IBM Tealeaf CX Mobile
v IBM Tealeaf CX Mobile Android Logging
Framework Guide
v IBM Tealeaf Android Logging Framework
Release Notes
v IBM Tealeaf CX Mobile Administration
Manual
v IBM Tealeaf CX Mobile User Manual
v IBM Tealeaf CX Mobile iOS Logging
Framework Guide
v IBM Tealeaf iOS Logging Framework Release
Notes
174
IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide
Notices
This information was developed for products and services offered in the U.S.A.
IBM may not offer the products, services, or features discussed in this document in
other countries. Consult your local IBM representative for information on the
products and services currently available in your area. Any reference to an IBM
product, program, or service is not intended to state or imply that only that IBM
product, program, or service may be used. Any functionally equivalent product,
program, or service that does not infringe any IBM intellectual property right may
be used instead. However, it is the user's responsibility to evaluate and verify the
operation of any non-IBM product, program, or service.
IBM may have patents or pending patent applications covering subject matter
described in this document. The furnishing of this document does not grant you
any license to these patents. You can send license inquiries, in writing, to:
IBM Director of Licensing IBM Corporation North Castle Drive Armonk, NY
10504-1785 U.S.A.
For license inquiries regarding double-byte (DBCS) information, contact the IBM
Intellectual Property Department in your country or send inquiries, in writing, to:
Intellectual Property Licensing Legal and Intellectual Property Law IBM Japan, Ltd.
19-21, Nihonbashi-Hakozakicho, Chuo-ku Tokyo 103-8510, Japan
The following paragraph does not apply to the United Kingdom or any other
country where such provisions are inconsistent with local law: INTERNATIONAL
BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION "AS IS"
WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED,
INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR
PURPOSE. Some states do not allow disclaimer of express or implied warranties in
certain transactions, therefore, this statement may not apply to you.
This information could include technical inaccuracies or typographical errors.
Changes are periodically made to the information herein; these changes will be
incorporated in new editions of the publication. IBM may make improvements
and/or changes in the product(s) and/or the program(s) described in this
publication at any time without notice.
Any references in this information to non-IBM Web sites are provided for
convenience only and do not in any manner serve as an endorsement of those Web
sites. The materials at those Web sites are not part of the materials for this IBM
product and use of those Web sites is at your own risk.
IBM may use or distribute any of the information you supply in any way it
believes appropriate without incurring any obligation to you.
Licensees of this program who wish to have information about it for the purpose
of enabling: (i) the exchange of information between independently created
programs and other programs (including this one) and (ii) the mutual use of the
information which has been exchanged, should contact:
© Copyright IBM Corp. 1999, 2016
175
IBM Bay Area Lab 1001 E Hillsdale Boulevard Foster City, California 94404 U.S.A.
Such information may be available, subject to appropriate terms and conditions,
including in some cases, payment of a fee.
The licensed program described in this document and all licensed material
available for it are provided by IBM under terms of the IBM Customer Agreement,
IBM International Program License Agreement or any equivalent agreement
between us.
Any performance data contained herein was determined in a controlled
environment. Therefore, the results obtained in other operating environments may
vary significantly. Some measurements may have been made on development-level
systems and there is no guarantee that these measurements will be the same on
generally available systems. Furthermore, some measurements may have been
estimated through extrapolation. Actual results may vary. Users of this document
should verify the applicable data for their specific environment.
Information concerning non-IBM products was obtained from the suppliers of
those products, their published announcements or other publicly available sources.
IBM has not tested those products and cannot confirm the accuracy of
performance, compatibility or any other claims related to non-IBM products.
Questions on the capabilities of non-IBM products should be addressed to the
suppliers of those products.
All statements regarding IBM's future direction or intent are subject to change or
withdrawal without notice, and represent goals and objectives only.
This information contains examples of data and reports used in daily business
operations. To illustrate them as completely as possible, the examples include the
names of individuals, companies, brands, and products. All of these names are
fictitious and any similarity to the names and addresses used by an actual business
enterprise is entirely coincidental.
COPYRIGHT LICENSE:
This information contains sample application programs in source language, which
illustrate programming techniques on various operating platforms. You may copy,
modify, and distribute these sample programs in any form without payment to
IBM, for the purposes of developing, using, marketing or distributing application
programs conforming to the application programming interface for the operating
platform for which the sample programs are written. These examples have not
been thoroughly tested under all conditions. IBM, therefore, cannot guarantee or
imply reliability, serviceability, or function of these programs. The sample
programs are provided "AS IS", without warranty of any kind. IBM shall not be
liable for any damages arising out of your use of the sample programs.
Trademarks
IBM, the IBM logo, and ibm.com® are trademarks or registered trademarks of
International Business Machines Corp., registered in many jurisdictions worldwide.
Other product and service names might be trademarks of IBM or other companies.
A current list of IBM trademarks is available on the Web at “Copyright and
trademark information” at www.ibm.com/legal/copytrade.shtml.
176
IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide
Privacy Policy Considerations
IBM Software products, including software as a service solutions, ("Software
Offerings") may use cookies or other technologies to collect product usage
information, to help improve the end user experience, to tailor interactions with
the end user or for other purposes. A cookie is a piece of data that a web site can
send to your browser, which may then be stored on your computer as a tag that
identifies your computer. In many cases, no personal information is collected by
these cookies. If a Software Offering you are using enables you to collect personal
information through cookies and similar technologies, we inform you about the
specifics below.
Depending upon the configurations deployed, this Software Offering may use
session and persistent cookies that collect each user's user name, and other
personal information for purposes of session management, enhanced user usability,
or other usage tracking or functional purposes. These cookies can be disabled, but
disabling them will also eliminate the functionality they enable.
Various jurisdictions regulate the collection of personal information through
cookies and similar technologies. If the configurations deployed for this Software
Offering provide you as customer the ability to collect personal information from
end users via cookies and other technologies, you should seek your own legal
advice about any laws applicable to such data collection, including any
requirements for providing notice and consent where appropriate.
IBM requires that Clients (1) provide a clear and conspicuous link to Customer's
website terms of use (e.g. privacy policy) which includes a link to IBM's and
Client's data collection and use practices, (2) notify that cookies and clear gifs/web
beacons are being placed on the visitor's computer by IBM on the Client's behalf
along with an explanation of the purpose of such technology, and (3) to the extent
required by law, obtain consent from website visitors prior to the placement of
cookies and clear gifs/web beacons placed by Client or IBM on Client's behalf on
website visitor's devices
For more information about the use of various technologies, including cookies, for
these purposes, See IBM's Online Privacy Statement at: http://www.ibm.com/
privacy/details/us/en section entitled "Cookies, Web Beacons and Other
Technologies."
Notices
177
178
IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide
IBM®
Printed in USA