Add the Android SDK to your project

Overview

Use the Android SDK to instrument your native Android applications for logging and analysis. The Android SDK implementation is simple. It uses standard Android classes and user interface controls to track user interface events.

Before you begin

• Install Android Studio. Studio Chipmunk is recommended.
• Use gradle version 7.2

Download and add the SDK to your project

1. Download the latest release of our Android SDK.
2. Add the Android SDK to your project.

Add permissions for Android

Add the following permissions in the AndroidManifest.xml file to register the Tealeaf SDK files.

📘

Note:

If you install the SDK using the CXA plugin these permissions are automatically added to your AndroidManifest.xml file.

<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"/>

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

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

Implement Android auto instrumentation

The Android SDK supports limited auto-instrumentation.

📘

Note:

Starting with Android SDK version 2.0, the AspectJ library is no longer supported. To remove the AspectJ configurations from the app, see the Migration guide.

The Tealeaf Android SDK uses the settings defined in the TealeafLayoutConfig.json to log layout messages [type 10] for screenviews of native mobile application sessions.

The AutoLayout controller enables the application to automatically continue logging type 10 screen layouts when it resumes to the foreground.

Open the TealeafLayoutConfig.json from the assets folder and edit the Autolayout configurations. For more information, see Autolayout configuration options.

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

{
  "AutoLayout": {
    "GlobalScreenSettings": {
      "ScreenChange": true,
      "DisplayName": "",
      "CaptureLayoutDelay": 500,
      "ScreenShot": false,
      "NumberOfWebViews": 0,
      "CaptureUserEvents": true,
      "CaptureScreenVisits": true,
      "CaptureLayoutOn": 2,
      "CaptureScreenshotOn": 0,
      "Masking": {
        "HasMasking": true,
        "HasCustomMask": true,
        "Sensitive": {
          "capitalCaseAlphabet": "X",
          "number": "9",
          "smallCaseAlphabet": "x",
          "symbol": "#"
        },
        "MaskIdList": [
          "textView1,login.password,editText*"
        ],
        "MaskValueList": [
          "test sensitive*",
          "^3[47][0-9]{13}$",
          "^4[0-9]{12}(?:[0-9]{3})?$"
        ]
      }
    },
    "AppendMapIds": {
      "com.any.package:id/givenIdOnXmlLayout1": {
        "mid": "giveAdditionalId1"
      },
      "com.any.package:id/givenIdOnXmlLayout2": {
        "mid": "giveAdditionalId2"
      }
    }
  }

📘

Tip:

You can also manually configure a screen to log a layout by adding the following code snippet.
Tealeaf.logScreenLayout(activity, "Name", delayInMS);

Pause and resume library to capture specific pages

You can also configure the SDK to pause and resume to capture only specific pages by following one of the following methods:

Edit TealeafLayoutConfig.json

The preferred method is to edit the TealeafLayoutConfig.json file.

By default, you have the following defaults, which capture all pages, events, and gestures, but no screenshots:

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

To pause the library, use the CaptureUserEvents setting and set it to false to indicate that you want to pause the library and no longer capture information on a page.

📘

Note:

When you pause the library, it only pauses the capture of user events.

• If you do not want to capture screens, set the ScreenChange setting to false.
• If you do not want to capture screen visits, set the CaptureScreenVisits setting to false.

To resume the library, set the CaptureUserEvents settings to true.

The following example code snippet shows how to capture all data except for user events on "FirstActivity" which is the first page, and then capture user events on "SecondActivity," which is the second page.

{
  "AutoLayout": {
    "GlobalScreenSettings": {
      "ScreenChange": true,
      "DisplayName": "",
      "CaptureLayoutDelay": 0,
      "ScreenShot": false,
      "NumberOfWebViews": 0,
      "CaptureUserEvents": true,
      "CaptureScreenVisits": true,
      "CaptureLayoutOn": 2,
      "CaptureScreenshotOn": 0
    },
    "FirstActivity": {
      "ScreenChange": false,
      "DisplayName": "First Screen",
      "CaptureLayoutDelay": 0,
      "ScreenShot": false,
      "NumberOfWebViews": 0,
      "CaptureUserEvents": false,
      "CaptureScreenVisits": false,
      "CaptureLayoutOn": 0,
      "CaptureScreenshotOn": 0
    },
    "SecondActivity": {
      "ScreenChange": true,
      "DisplayName": "Second Screen",
      "CaptureLayoutDelay": 0,
      "ScreenShot": false,
      "NumberOfWebViews": 0,
      "CaptureUserEvents": true,
      "CaptureScreenVisits": true,
      "CaptureLayoutOn": 2,
      "CaptureScreenshotOn": 0
    }
  },
  "AppendMapIds": {
    
  }
}

You can also disable capturing all data except for specific pages, as shown in the following example.

{
  "AutoLayout": {
    "GlobalScreenSettings": {
       "ScreenChange": false,
       "DisplayName": "",
       "CaptureLayoutDelay": 0,
       "ScreenShot": false,
       "NumberOfWebViews": 0,
       "CaptureUserEvents": false,
       "CaptureScreenVisits": false,
       "CaptureLayoutOn": 0,
       "CaptureScreenshotOn": 0
    },
    "FirstActivity": {
      "ScreenChange": true,
      "DisplayName": "First Screen",
      "CaptureLayoutDelay": 0,
      "ScreenShot": false,
      "NumberOfWebViews": 0,
      "CaptureUserEvents": true,
      "CaptureScreenVisits": true,
      "CaptureLayoutOn": 2,
      "CaptureScreenshotOn": 0
    },
    "SecondActivity": {
      "ScreenChange": true,
      "DisplayName": "Second Screen",
      "CaptureLayoutDelay": 0,
      "ScreenShot": false,
      "NumberOfWebViews": 0,
      "CaptureUserEvents": true,
      "CaptureScreenVisits": true,
      "CaptureLayoutOn": 2,
      "CaptureScreenshotOn": 0
    }
  },
  "AppendMapIds": {
    
  }
}

Call TealeafLayoutConfig.json programmatically

Use the GlobalScreenSettings configuration in the TealeafLayoutConfig.json file to set values for all view controllers. Then you call the TealeafLayoutConfig.json configurations programmatically from the page where you want to apply the settings.

To pause the Tealeaf SDK from capturing specific pages, go to the page where you want to start pausing the capture and call the TealeafLayoutConfig.json programmatically by implementing onStart and onResume methods, which are always called when an activity is displayed.

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

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

override fun onResume() {
        Tealeaf.pauseTealeaf()
        super.onResume()
    }

    override fun onStart() {
        Tealeaf.pauseTealeaf()
        super.onStart()
    }

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

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

override fun onPause() {
        Tealeaf.resumeTealeaf(true)
        super.onPause()
    }

Configure Tealeaf properties

You must configure the target-page location, kill-switch location, specific URLs for logging events, message flow, logging levels, and how to log screen layouts and gestures for your application to work with the Tealeaf SDK.
You must configure these Tealeaf properties in the EOCoreBasicConfig.properties and TealeafBasicConfig.properties files located in the assets folder of your project.
You can manually update configuration values by editing EOCoreBasicConfig.properties and TealeafBasicConfig.properties files, or you can dynamically update the configuration values through an API using the following API call structure:

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

Examples:
You can use the following API call 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
• value – is the value you want to assign to the configuration property.

You can use the following API call to update an application configuration value that is stored in TealeafBasicConfig.properties:

EOCore.updateConfig(configItem, value, TealeafEOLifecycleObject.getInstance())

Where

• key – is the configuration property that you want to update
• value – is the value you want to assign to the configuration property.

For a list of properties that you must configure, see

• Log level settings
• Kill switch
• Post settings

📘

Note:

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.