Implement Tealeaf in your application

Overview

After you install the Tealeaf SDK, you must implement Tealeaf functions in your application. Implementing the Tealeaf functions may require modifying your application to capture controls, events, and screen views.

Before you begin

Install the Android Tealeaf SDK. For more information, see Add the Android SDK to your project.

Capture screen layouts

Tealeaf has functions to log screen layouts for screenviews of native mobile app sessions. When you capture screen layouts, you can replay a mobile app session as you would an HTML web session instead of viewing the mobile app session as a series of screen captures.

The screen layouts of the native mobile app sessions are captured in Tealeaf JSON format. The screen layouts are then sent back to the 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. For more information, see Replay a visitor session

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

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

To activate native app session replay, you must set LogViewLayoutOnScreenTransition = true to true in the TealeafBasicConfig.properties file.

During predeployment, set the GetImageDataOnScreenLayout = true to collect all the images. This setting creates a large payload sent to the server that contains base64 images that are used for replay. When the application is ready to be deployed to the Play Store, change the GetImageDataOnScreenLayout setting to false.

Record an activity

In Android, an activity can be considered a page displayed on mobile devices. By default, you should record an activity that is displayed. For more information, see The Activity Lifecycle.

You can record an activity 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");

// 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 allows you to log a screen layout without making additional changes to your application code. For more information, see Auto-layout

You can also configure the SDK to pause and resume to capture only specific pages. For more information, see Pause and resume library.

Record a Fragment

In Android, a Fragment is UI component in an activity. The SDK has auto Fragment screen logging built in using default screen view name. However,

To customize Fragment screenview name or more control over how it is captured, update TealeafAdvancedConfig.json:

"EnableFragmentLifeCycleListener": false,

Record an Fragment displayed by placing the following information in the OnResume 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");

override fun onResume() {
        super.onResume()
        // Manual call will not be logged since logging is disabled for "NotLoggedFragment"
        Tealeaf.onResume(activity, "LoggedFragment")
    }

To log the Fragment layout, update TealeafLayoutConfig.json AutoLayout section with below.


    "LoggedFragment": {
      "ScreenChange": true,
      "DisplayName": "This fragment is logged"
    }

To disable the Fragment layout logging, update TealeafLayoutConfig.json AutoLayout section with below.


    "LoggedFragment": {
      "ScreenChange": false,
      "DisplayName": "This fragment is logged"
    }

Capture webview data

You can automatically capture and consume Google WebViews in your app.

📘
Note:
You must have Android SDK Tealeaf Module version 10.3.274 added to your application to enable automatic webview capture.

If your app needs to extend a customized version of the WebViewClient, then set the ExtendsGoogleWebViewClient value to true in the TealeafAdvancedConfig.json file.

"ExtendsGoogleWebViewClient": false,
"GoogleWebViewEnabled": true

Add the following code to the MainActivity file.

Does NOT extend a custom WebViewClient:

private void createWebView(final int id, final String url) {
        WebView webView = findViewById(id);
        webView.loadUrl("YOUR_WEB_PAGE_URL");
    }

private fun createWebView(id: Int, url: String) {
        val webView: WebView = findViewById(id)
        webView.loadUrl("YOUR_WEB_PAGE_URL")
    }

Extends a custom WebViewClient:

private void createWebView(final int id, final String url) {
        WebView webView = findViewById(id);
        webView.setWebViewClient(new "CALL_YOUR_CUSTOM_WEB_CLIENT");      
        webView.loadUrl("YOUR_WEB_PAGE_URL");
    }

private fun createWebView(id: Int, url: String) {
        val webView: WebView = findViewById(id)
        webView.setWebViewClient("CALL_YOUR"CUSTOM_WEB_CLIENT")        
        webView.loadUrl("YOUR_WEB_PAGE_URL")
    }

Capture gestures

You can capture gestures that the users make on your Android application. Several types of gestures are captured; for more information, see Capture gestures.

Touch event method

You must add your variables to one of these methods:

dispatchTouchEvent - use this method if your activity uses a customized gesture view.

To instrument your application for Android gestures, follow these steps:

To use the Android gestures module, compile the Android Support Library in the build.gradle file: implementation 'androidx.appcompat:appcompat:xx.x.x'
Update each Activity class, override the dispatchTouchEvent method:

// Override the dispatchTouchEvent
    public boolean dispatchTouchEvent(MotionEvent e)
    {
        //detector.onTouchEvent(e);
        Tealeaf.dispatchTouchEvent(this, e);
        return super.dispatchTouchEvent(e);
    }

override fun dispatchTouchEvent(e: MotionEvent?): Boolean {
        //detector.onTouchEvent(e);
        Tealeaf.dispatchTouchEvent(this, e)
        return super.dispatchTouchEvent(e)
    }

Edit the TealeafBasicConfig.properties file, and set SetGestureDetector to true.

For information about the types of Gesture events captured, see Capture gestures.

Add exception logging to your application

Exceptions are how a system or framework communicates to the application that something is wrong. You can use the exception information can be used for analytics. Tealeaf provides two mechanisms to log exceptions.

You can manually log exceptions by using the logException API. Or, the Tealeaf SDK automatically logs uncaught exceptions.

Automatically log exceptions

When your application throws an uncaught exception, Tealeaf Android SDK records the stack trace and state of the device when 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 the same device information that Tealeaf collects for fatal crashes.

public static Boolean logException(final Throwable exception, final HashMap < String, String > data, final
Boolean unhandled)

fun logException(exception: Throwable?, data: HashMap<String?, String?>?, unhandled: Boolean?): Boolean

where:
exception - is the exception to be logged.
data - is the value to be given to the event.
unhandled - whether the exception is unhandled.
return - whether the exception was logged.

To add exception logging to your application, follow these examples:

Determine the method for which you want to log exceptions. For example, you have the method:

public
void clientMethod1() {}

fun clientMethod1() {}

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);
  }
}

fun clientMethod1() {
        try {
            val array = IntArray(1)
            val i = array[2] // Index out of bound exception
        } catch (e: Exception) {
            val data = HashMap<String, String>()
            data["extraMessage"] = "custom value1"
            Tealeaf.logException(e, data, false)
        }
    }

Log geolocation information automatically

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 are not available currently.

Automatic logging

You can configure automatic logging with the TealeafBasicConfig.properties file and the manifest file.

To give permission to the device to log geolocation data, add the following to the Android manifest file.

<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION">

<uses-permission android:name=
"android.permission.ACCESS_COARSE_LOCATION"
/>

Configure the following geolocation properties in the TealeafBasicConfig.properties file. For more information see,Auto-layout.

LogLocationEnabled
LogLocationTries
LogLocationTimeout

Using APIs

There are three APIs you can use to enable geolocation information logging in your application manually:

public static Boolean logGeolocation() - Use this API at a specific point in your application to log geolocation only at that point.
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.
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 Web SDK 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 to capture the geolocation information.

To disable geolocation capture in the Web application:

Locate the Web SDK configuration. The configuration is typically at the end of the Web SDK file as part of the call to the TLT.init() API.
Locate the geolocation configuration section in the replay module configuration object (modules.replay.geolocation).
If the geolocation configuration section does not exist, the feature is disabled automatically. If the section exists, ensure that the enabled setting is set to false. The following example shows the geolocation section for the Web SDK with geolocation disabled.

geolocation: {
  enabled: false,
  triggers: [{
    event: "load"
  }]
},

Capture navigation drawers

When you have implemented navigation drawers in your application, you can capture data and log events for the open and close actions for the navigation drawers.

📘
Note:
You must have Android SDK Tealeaf Module version 10.3.274 added to your application to enable this functionality.

You can instrument your application to automatically capture the nav drawer data by extending the custom class or manually capturing the data.

Automatic capture

📘
Note:
You must enable the auto instrumentation property in the Tealeaf SDK's basic config properties file for auto instrumentation.

To instrument the automatic capture of the open and close events for the nav drawer, add the following code in the MainActivity.java file for your application.
You should already have most of the code if a navigation drawer exists. To implement automatic capture of the open and close events, use the custom class ActionBarDrawerToggleTealeaf that Tealeaf provides, as shown in the following example,:

private DrawerLayout drawerLayout;
private ActionBarDrawerToggleTealeaf actionBarDrawerToggle;

actionBarDrawerToggle = new ActionBarDrawerToggleTealeaf(this, drawerLayout, R.string.nav_drawer_menu_open, R.string.nav_drawer_menu_close);

drawerLayout.addDrawerListener(actionBarDrawerToggle);
actionBarDrawerToggle.syncState();

private lateinit var drawerLayout: DrawerLayout

drawerLayout = binding.drawerLayout

//Add this code block to automatically capture NavDrawer events
val toggle = object : ActionBarDrawerToggleTealeaf(this, drawerLayout, R.string.nav_drawer_menu_open, R.string.nav_drawer_menu_close) 

drawerLayout.addDrawerListener(toggle)
toggle.syncState()

where

R.string.nav_drawer_menu_open is defined in the strings file as <string name="nav_drawer_menu_open">Open</string>
R.string.nav_drawer_menu_close is defined in the strings file as <string name="nav_drawer_menu_close">Close</string>

Manual capture

Add the following code to manually capture the open and close events for the navigation drawer in the MainActivity.java file for your application. You should already have most of the code if a navigation drawer exists. Add the ActionBarDrawerToggle class, as shown in the following example, to implement manual capture of the open and close events.

private DrawerLayout drawerLayout;
private ActionBarDrawerToggle actionBarDrawerToggle;

actionBarDrawerToggle = new ActionBarDrawerToggle(this, drawerLayout, R.string.nav_drawer_menu_open, R.string.nav_drawer_menu_close) {
  public void onDrawerOpened(View drawerView) {
    Tealeaf.logEvent(drawerView, Tealeaf.TLF_ON_DRAWER_OPENED);
    super.onDrawerOpened(drawerView);
  }
  public void onDrawerClosed(View drawerView) {
    Tealeaf.logEvent(drawerView, Tealeaf.TLF_ON_DRAWER_CLOSED);
    super.onDrawerClosed(drawerView);
  }
};

drawerLayout.addDrawerListener(actionBarDrawerToggle);
actionBarDrawerToggle.syncState();

private lateinit var drawerLayout: DrawerLayout

drawerLayout = binding.drawerLayout

//Add this code block to manually capture NavDrawer events
val toggle = object : ActionBarDrawerToggle(this, drawerLayout, R.string.nav_drawer_menu_open, R.string.nav_drawer_menu_close) {
    override fun onDrawerOpened(drawerView: View) {
        Tealeaf.logEvent(drawerView, Tealeaf.TLF_ON_DRAWER_OPENED)
        super.onDrawerOpened(drawerView)
    }

    override fun onDrawerClosed(drawerView: View) {
        Tealeaf.logEvent(drawerView, Tealeaf.TLF_ON_DRAWER_CLOSED)
        super.onDrawerClosed(drawerView)
    }
}

drawerLayout.addDrawerListener(toggle)
toggle.syncState()

where

R.string.nav_drawer_menu_open is defined in the strings file as <string name="nav_drawer_menu_open">Open</string>
R.string.nav_drawer_menu_close is defined in the strings file as <string name="nav_drawer_menu_close">Close</string>

Capture dialog popups

You can automatically capture and ingest data for dialog popups.

📘
Note:
You must have Android SDK Tealeaf Module version 10.3.274 added to your application to enable this functionality.

You can implement auto-instrumentation or manually instrument your application to capture the dialog popup data.

Capture bottomsheet dialog data

If you have implemented the BottomSheetDialog - a dialog that slides up from the bottom of the screen - then you must create or update the BottomSheetDialog fragment to capture the data.

Automatic capture
To instrument the automatic capture of Bottomsheet dialog data, you must create or update a fragment class that inherits from Tealeaf’s custom TLFBottomSheetDialogFragment.

public class MyDialogFragment extends TLFBottomSheetDialogFragment

class MyDialogFragment : TLFBottomSheetDialogFragment

Manual capture
To manually capture the Bottomsheet dialog data, create or update a fragment class to inherit from BottomSheetDialogFragment.

public class MyDialogFragment extends BottomSheetDialogFragment

class MyDialogFragment : BottomSheetDialogFragment

Each view within your custom fragment class that requires instrumentation must have an attached listener.

TextView textView = rootView.findViewById(R.id.tvTitle);
textView.setOnClickListener(view -> Tealeaf.logEvent(view));

val textView = rootView.findViewById<TextView>(R.id.tvTitle)
textView.setOnClickListener { view -> Tealeaf.logEvent(view) }

Capture dialog window data

If you have implemented the DialogFragment - a dialog window that floats on top of its activity window - then you must create or update the Dialog fragment to capture the data.

Automatic capture
To instrument the automatic capture of dialog window data, you must create or update a fragment class that inherits from Tealeaf's custom TLFDialogFragment.

public class MyDialogFragment extends TLFDialogFragment

class MyDialogFragment : TLFDialogFragment

Manual capture
To manually capture the dialog window data, create or update a fragment class to inherit from DialogFragment.

public class MyDialogFragment extends DialogFragment

class MyDialogFragment : DialogFragment

Each view within your custom fragment class that requires instrumentation must have an attached listener.

TextView textView = rootView.findViewById(R.id.tvTitle);
textView.setOnClickListener(view -> Tealeaf.logEvent(view));

val textView = rootView.findViewById<TextView>(R.id.tvTitle)
textView.setOnClickListener { view -> Tealeaf.logEvent(view) }

Capture alert dialogs

Automatically capture alert dialogs with a defined builder
You can automatically capture alert dialogs in an existing application that already has a builder object by replacing the dialog.show() method with the following:

final AlertDialog dialog = builder.create();
DialogUtil.showDialog(getContext(), dialog);

val dialog: AlertDialog = builder.create()
DialogUtil.showDialog(context, dialog)

Automatically capture simple alert dialogs
The following code will create a simple alert dialog containing a Title, Message, and Negative button. To execute the method, include it in a click or touch event.

DialogUtil.showDialog(getContext(), "Title", "Message", "Button Text");

DialogUtil.showDialog(context, "Title", "Message", "Button Text")

Implement Tealeaf in your application

Overview

Before you begin

Capture screen layouts

Record an activity

Record a Fragment

Capture webview data

📘
Note:

Capture gestures

Touch event method

Add exception logging to your application

Automatically log exceptions

Manually log exceptions

Log geolocation information automatically

Automatic logging

Using APIs

Disable geolocation capture in the Web application

📘
Note:

Capture navigation drawers

📘
Note:

Automatic capture

📘
Note:

Manual capture

Capture dialog popups

📘
Note:

Capture bottomsheet dialog data

Capture dialog window data

Capture alert dialogs

Overview

Before you begin

Capture screen layouts

Record an activity

Record a Fragment

Capture webview data

📘Note:

Capture gestures

Touch event method

Add exception logging to your application

Automatically log exceptions

Manually log exceptions

Log geolocation information automatically

Automatic logging

Using APIs

Disable geolocation capture in the Web application

📘Note:

Capture navigation drawers

📘Note:

Automatic capture

📘Note:

Manual capture

Capture dialog popups

📘Note:

Capture bottomsheet dialog data

Capture dialog window data

Capture alert dialogs

📘
Note:

📘
Note:

📘
Note:

📘
Note:

📘
Note: