Skip to content

Android Application Integration

Collect metrics data from Android applications to analyze application performance visually.

Reading Path

Prerequisites

Note

If the RUM Headless service has been activated, the prerequisites are automatically configured, and you can directly integrate the application.

Application Integration

  1. Go to RUM > Create > Android.
  2. Enter the application name.
  3. Enter the application ID.

  4. Select the application integration method:

    • Public DataWay: Directly receives RUM data without installing the DataKit collector.
    • Local environment deployment: Receives RUM data after meeting the prerequisites.

Installation

Source Code Repository: https://github.com/TrueWatchTech/datakit-android

Demo: https://github.com/TrueWatchTech/truewatch-app-demo

Gradle Configuration

Introducing the Plugin

  • Add the remote repository address for the SDK in the root project's build.gradle file.
//build.gradle
buildscript {
    //...
    repositories {
        //...
        //Add the remote repository address for the Plugin
        maven {
            url 'https://mvnrepo.truewatch.com/repository/maven-releases'
            }
    }
    dependencies {
        //...
        //Add the Plugin dependency, requires AGP 7.4.2+ and Gradle 7.2.0+
        classpath 'com.truewatch.ft.mobile.sdk.tracker.plugin:ft-plugin:[latest_version]'
        // For AGP versions below 7.4.2, use ft-plugin-legacy
        //classpath 'com.truewatch.ft.mobile.sdk.tracker.plugin:ft-plugin-legacy:[latest_version]'
        }
}

//setting.gradle
pluginManagement {
    repositories {
        google()
        mavenCentral()
        gradlePluginPortal()
        //Add the remote repository address for the Plugin
        maven {
            url('https://mvnrepo.truewatch.com/repository/maven-releases')
            }
    }
}

//build.gradle
plugins{
    //Add the Plugin, requires AGP 7.4.2+ and Gradle 7.2.0+
    id 'com.truewatch.ft.mobile.sdk.tracker.plugin' version '[latest_version]' apply false
    // For AGP versions below 7.4.2, use ft-plugin-legacy
    //id 'com.truewatch.ft.mobile.sdk.tracker.plugin.legacy' version '[latest_version]' apply false
    }
  • Apply the Plugin in the main module's app/build.gradle file.
//Apply the plugin in app/build.gradle. Missing configuration will affect the following automatic collection features.
//
// 1.RUM: App startup, OkHttp requests, WebView activity Activity/Fragment navigation, click events
// 2.Log: Console Logcat
apply plugin: 'ft-plugin'  //If using ft-plugin-legacy, use this same configuration.

//Optional: Configure plugin parameters as needed.
FTExt {
    //showLog = true
    //asmVersion='asm7'
    //ignorePackages=['com.ft','com/ft']
    //knownWebViewClasses = ['com.your.CustomWebView']
}

All plugin parameters are optional. In most scenarios, only apply plugin: 'ft-plugin' is needed. FTExt configuration is only required when debugging plugin behavior, controlling instrumentation scope, or manually supplementing WebView identification.

Parameter Name Type Default Value Description Use Case
showLog Boolean false Whether to output ft-plugin build logs. Enable when debugging plugin execution or troubleshooting if instrumentation is effective.
asmVersion String asm9 Specifies the ASM version used by the plugin, options range from asm7 to asm9. Adjust when there are compatibility requirements with other bytecode processing plugins in the project.
ignorePackages String[] Empty Configures package paths not to be instrumented by ASM; path separators can be . or /. Use when needing to skip certain business packages, third-party packages, or code conflicting with other plugins.
knownWebViewClasses String[] Empty Manually declares custom classes that should be identified as WebViews. Use when automatic identification fails for custom WebViews with complex inheritance hierarchies.

knownWebViewClasses only needs to be configured when automatic identification fails. Related troubleshooting methods can be found in Custom WebView Automatic Collection Not Working.

Introducing the SDK

  • Add the remote repository address for the SDK in the root project's build.gradle file.
//build.gradle
allprojects {
    repositories {
        //...
        //Add the remote repository address for the SDK
        maven {
            url 'https://mvnrepo.truewatch.com/repository/maven-releases'
            }
    }
}

//build.gradle
dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
        //Add the remote repository address for the SDK
        maven {
            url('https://mvnrepo.truewatch.com/repository/maven-releases')
            }
    }
}
  • Add the SDK dependency in the main module's app/build.gradle file.
//app/build.gradle
dependencies {
    //Add the SDK dependency
    implementation 'com.truewatch.ft.mobile.sdk.tracker.agent:ft-sdk:[latest_version]'
    //Dependency for capturing native layer crash information, must be used with ft-sdk, cannot be used alone.
    implementation 'com.truewatch.ft.mobile.sdk.tracker.agent:ft-native:[latest_version]'
    // json serialization
    implementation 'com.google.code.gson:gson:2.8.+'
    //Optional, required for automatic network request collection and automatic trace enabling, minimum compatible version 3.12.+
    implementation 'com.squareup.okhttp3:okhttp:4.+'
}

For the latest versions, refer to the version names for ft-sdk, ft-plugin, and ft-native above.

Application Configuration

The optimal location for SDK initialization is within the onCreate method of the Application. If your application hasn't created an Application, you need to create one and declare it in AndroidManifest.xml. For an example, refer to here.

<application 
       android:name="YourApplication"> 
</application>

R8 / Proguard Obfuscation Configuration

If using a version of ft-sdk prior to 1.6.15 and you need to set minifyEnabled = true in android.buildTypes, enable the following configuration:

-dontwarn com.ft.sdk.**

### ft-sdk library
-keep class com.ft.sdk.**{*;}

### ft-native library
-keep class ftnative.*{*;}

### Prevent class names from being obfuscated in action_name when obtaining Actions ###
-keepnames class * extends android.view.View
-keepnames class * extends android.view.MenuItem

Initialization Instructions

For a minimal initialization example, read Quick Start.

For complete FTSDKConfig parameter details, read SDK Initialization.

Detailed Configuration Entries

Advanced Scenarios

Plugin AOP Ignore

Ignore ASM insertion by adding @IgnoreAOP to methods overridden by Plugin AOP. For batch ignoring, use ignorePackages in the ft-plugin FTExt configuration.

View.setOnClickListener(new View.OnClickListener() {
        @Override
        @IgnoreAOP
        public void onClick(View v) {

        }
    }

View.setOnClickListener @IgnoreAOP{

    }

Frequently Asked Questions

Adding Global Variables to Avoid Key Conflicts

To avoid conflicts between custom fields and SDK data, it is recommended to add a project abbreviation prefix to tag names, e.g., custom_tag_name. The key values used in the project can be queried in the source code. When the same variable appears in SDK global variables and RUM/Log, the RUM/Log variable will override the SDK global variable.

SDK Compatibility

Adapting to Market Privacy Audits

Refer to Privacy and Permissions Statement for details.

Third-party Frameworks

flutter, react-native, uni-app, unity can adopt a similar delayed initialization approach as native Android to adapt to application market privacy audits.

Jetpack Compose Support

Currently, automatic collection for pages generated by compose components is not supported. However, you can track click events and page navigation events through manual Action and View custom interfaces. Refer to here for an example.