Android Application Integration¶

Collect Metrics data from Android applications and analyze application performance visually.

Reading Path¶

• First-time integration: Start with Quick Start
• Complete integration: Continue reading this article
• Parameter details: Refer to SDK Initialization, RUM Configuration, Log Configuration, Trace Configuration
• Advanced capabilities: View specialized pages under the "Advanced Scenarios" group
• Troubleshooting: Refer to Troubleshooting

Prerequisites¶

• Install DataKit;
• Configure the RUM Collector;
• Configure DataKit to be publicly accessible and install the IP Geolocation database.

Application Integration¶

1. Navigate 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: https://github.com/GuanceCloud/datakit-android

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

Gradle Configuration¶

Apply Plugin¶

• Add the remote repository address for the SDK in the project root directory's build.gradle file.

//build.gradle
buildscript {
    //...
    repositories {
        //...
        //Add the remote repository address for the Plugin
        maven {
            url 'https://mvnrepo.jiagouyun.com/repository/maven-releases'
        }
    }
    dependencies {
        //...
        //Add the Plugin dependency, requires AGP 7.4.2 or above, Gradle 7.2.0 or above
        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 address for the Plugin
        maven {
            url('https://mvnrepo.jiagouyun.com/repository/maven-releases')
        }
    }
}

//build.gradle
plugins{
    //Add the Plugin dependency, requires AGP 7.4.2 or above, Gradle 7.2.0 or above
    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 the Plugin in the project's main module app/build.gradle file.

//Apply the plugin in app/build.gradle. Missing this 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 configuration as well.

//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; adding FTExt configuration is only necessary when debugging plugin behavior, controlling instrumentation scope, or manually supplementing WebView identification.

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

Apply SDK¶

• Add the remote repository address for the SDK in the project root directory's build.gradle file.

//build.gradle
allprojects {
    repositories {
        //...
        //Add the remote repository address for the SDK
        maven {
            url 'https://mvnrepo.jiagouyun.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.jiagouyun.com/repository/maven-releases')
        }
    }
}

• Add the SDK dependency in the project's main module app/build.gradle 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 layer 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 if automatic network request collection and automatic trace enabling are needed, 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, ft-native above.

Application Configuration¶

The optimal location for SDK initialization is in 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 ft-sdk 1.6.15 or earlier versions and need to set minifyEnabled = true in android.buildTypes, the following configuration is required:

-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 a complete explanation of FTSDKConfig parameters, read SDK Initialization.

Detailed Configuration Entries¶

• SDK Initialization
• RUM Configuration
• Log Configuration
• Trace Configuration

Advanced Scenarios¶

• Custom Tags
• Custom Collection Rules
• Data Collection Masking
• WebView Monitoring
• Dynamic Configuration and Dynamic Update Address
• Symbol File Upload
• Privacy and Permissions
• Content Provider Settings
• Manual Compatibility Integration

Plugin AOP Ignore¶

Add @IgnoreAOP to methods covered by Plugin AOP to ignore ASM insertion. For batch ignoring, use ignorePackages in FTExt of ft-plugin.

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

        }
    }

View.setOnClickListener @IgnoreAOP{

    }

Frequently Asked Questions¶

Add Project Prefix 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., df_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, RUM/Log will override the global variable in the SDK.

SDK Compatibility¶

• Runnable Environment
• Compatible Environment

Adapting to Market Privacy Audits¶

Refer to Privacy and Permissions 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¶

Automatic collection for pages generated by compose components is currently not supported. However, manual tracking of click events and page navigation events can be achieved through custom interfaces for Action and View. Refer to here for an example.