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.
The Tealeaf Android SDK plugin helps you to simplify the Android SDK instrumentation. You can integrate the plugin with your projects in the Android studio. The plugin adds the Tealeaf SDK library to your application. The plugin also provides a user interface for selecting the SDK type and versions.

Install the Tealeaf Android SDK plugin

You must first install the Tealeaf Android SDK plugin in Android Studio to get started.

  1. Open the Android Studio application or an existing project in Android Studio.
  2. For Mac, from the menu bar, click Android Studio > Preferences. For Windows, click File > Settings.
  3. On the Preferences (Settings)window, clickPlugins. A list of available plugins is displayed.
  4. In the search bar, type Tealeaf. Click Install and then OK.
  5. Once the plugin is installed, you will be prompted to restart the application.
  6. Click Restart. You must restart the application to finish the installation.

πŸ“˜

Note:

You can also download the latest version of the plugin from Tealeaf Android SDK Dev Platform.

Start instrumentation

The Tealeaf Android SDK plugin is installed and added to the Android Studio sidebar menu.

πŸ“˜

Note:

You can move the sidebar menu items in Android Studio. Depending on how you have set up the sidebar menu view, the location of the plugin may differ.You can also access the plugin from View > Tool Windows.

You can now start instrumentation for the Android SDK.

  1. Open the Tealeaf Android SDK plugin from the sidebar menu. The plugin User Interface panel opens.
  2. On the Tealeaf Dev Platform panel, the Module, Library Type, and Versions are selected by default. You can change the default selections and make your own selections. Choose the module(app), library type (release or beta), and version for each library.
  3. πŸ“˜

    Tip:

    The refresh button will reset the selection.

  4. After selecting the default or your own selections, click Instrument to start instrumentation.
  5. After the instrumentation is complete, a success message appears. Click OK.

View replay

  1. Open the TealeafBasicConfig.properties file from the assets folder.
  2. Add the PostMessageUrl property and provide the URL.

πŸ“˜

Note:

For SaaS server configuration, provide a valid Appkey property for the Android SDK.
Contact your administrator for the application key value.

  1. Compile and run your project. A PostTask ID is generated when your data is posted successfully.

When you manually install the Tealeaf SDK, you must add the SDK files to the proper locations in your application.

  1. Add the EOCore.jar and TealeafMod.jar into the libs folder of your application to make the capture functions available. Add the files into the build path of the application you want to instrument.
  2. Integrate Tealeaf SDK files into your Android project by copying the following Tealeaf SDK files to the specified folder for your Android project.
    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
  3. In Android Studio, add the com.ea:eocore and com.ea:tealeaf files to the build.gradle file as follows:
    dependencies { implementation 'com.ea:eocore:x.x.x' implementation 'com.ea:tealeaf:x.x.x' }

    where xx.x.x is replaced with the version number of the Android library instance.

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

πŸ“˜

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.