Skip to content

Android Application Integration

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

Reading Path

Prerequisites

Note

If the RUM Headless service is already enabled, the prerequisites are automatically configured and you can directly integrate the application.

Application Integration

  1. Go to Real User Monitoring > Create Application > Android;
  2. Enter the application name;
  3. Enter the application ID;

  4. Select the application integration method:

    • Public DataWay: Receives RUM data directly, no need to install the DataKit collector.
    • On-Premises Deployment: Receives RUM data after meeting the prerequisites.

Installation

Source Code: https://github.com/GuanceCloud/datakit-android

Demo: https://github.com/GuanceDemo/guance-app-demo

Gradle Configuration

Applying the Plugin

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

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

//build.gradle
plugins{
    //Add the Plugin dependency, requires AGP 7.4.2+ and Gradle 7.2.0+
    id 'com.cloudcare.ft.mobile.sdk.tracker.plugin' version '[latest_version]' apply false
    // For AGP versions below 7.4.2, use ft-plugin-legacy
    //id 'com.cloudcare.ft.mobile.sdk.tracker.plugin.legacy' version '[latest_version]' apply false
    }
  • Add the usage of app/build.gradle to the main module Plugin file
//Apply the plugin in app/build.gradle. Missing this configuration will affect the following auto-collection features.
// 
// 1.RUM: App startup, OkHttp requests, WebView activity Activity/Fragment transitions, click events
// 2.Log: Console Logcat 
apply plugin: 'ft-plugin'  //If using ft-plugin-legacy, use the 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; additional FTExt configuration is required only when debugging plugin behavior, controlling instrumentation scope, or manually supplementing WebView identification.

Parameter Type Default Description Use Case
showLog Boolean false Whether to output ft-plugin build logs. Enable when debugging the plugin execution process or verifying instrumentation effectiveness.
asmVersion String asm9 Specifies the ASM version used by the plugin. Options: asm7 ~ asm9. Adjust when there are compatibility requirements with other bytecode processing plugins in the project.
ignorePackages String[] Empty Configures package paths to exclude from ASM instrumentation. Package path separator 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 to be recognized as WebView. Use when the custom WebView inheritance hierarchy is complex and auto-recognition fails.

knownWebViewClasses is only needed when auto-recognition fails. For troubleshooting methods, refer to Custom WebView Auto-Collection Not Working.

Applying the SDK

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

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

For the latest version, see the version names of ft-sdk, ft-plugin, and ft-native above.

Application Configuration

The best place to initialize the SDK is in the Application method of onCreate. If your application does not have a custom Application, you need to create one and declare it in AndroidManifest.xml. See here for an example.

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

R8 / Proguard Obfuscation Configuration

If using a version prior to ft-sdk 1.6.15 and need to set android.buildTypes in minifyEnabled = true, 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 in action_name from being obfuscated during Action retrieval ###
-keepnames class * extends android.view.View
-keepnames class * extends android.view.MenuItem

```

Initialization Notes

For a minimal initialization example, please read Quick Start.

For the complete FTSDKConfig parameter description, please read SDK Initialization.

Detailed Configuration Entry Points

Advanced Scenarios

Plugin AOP Ignore

To ignore ASM insertion, add @IgnoreAOP to the method overridden by Plugin AOP. To ignore in bulk, use ignorePackages in the FTExt block of ft-plugin.

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

}

}); ```

```kotlin View.setOnClickListener @IgnoreAOP {

} ```

Frequently Asked Questions

Adding Global Variables to Avoid Conflicting Fields

To avoid conflicts between custom fields and SDK data, it is recommended to prefix tag names with a project abbreviation, for example custom_tag_name. For the key values used in the project, refer to source code. When a global variable in the SDK conflicts with the same variable in RUM or Log, the RUM or Log value will override the SDK global variable.

SDK Compatibility

Addressing Market Privacy Audits

See Privacy and Permissions.

Third-Party Frameworks

flutter, react-native, uni-app, unity can use a delayed initialization approach similar to native Android to address app store privacy audits.

Jetpack Compose Support

Currently, auto-collection of pages generated by Compose components is not supported. However, you can manually track click events and page transition events using the custom Action and View interfaces. Refer to here for details.

Feedback

Is this page helpful?