Android Application Integration¶

Collect metrics data from Android applications and analyze application performance through visualization.

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: Check the specialized pages under the "Advanced Scenarios" group
• Troubleshooting: Refer to Troubleshooting

Prerequisites¶

• Install DataKit.
• Configure the RUM Collector.
• Configure DataKit to be accessible via the public network and install the IP Geolocation database.

Application Integration¶

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

4. Choose the application integration method:

   • Public Network 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/GuanceCloud/datakit-android

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

Gradle Configuration¶

Applying the Plugin¶

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

//build.gradle
buildscript {
    //...
    repositories {
        //...
        //Add the remote repository address 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, please 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.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, please use ft-plugin-legacy
    //id 'com.cloudcare.ft.mobile.sdk.tracker.plugin.legacy' version '[latest_version]' apply false
    }

• Add the Plugin usage in the main module app/build.gradle file.

//Apply the plugin in app/build.gradle. Missing configuration will affect the following automatic collection features.
//
// 1.RUM: App launch, OkHttp requests, WebView activities, Activity/Fragment navigation, click events
// 2.Log: Console Logcat
apply plugin: 'ft-plugin'  //If using ft-plugin-legacy, also use this 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.

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

Applying the SDK¶

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

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

• Add the SDK dependency in the 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 opening are needed, minimum compatible version 3.12.+
    implementation 'com.squareup.okhttp3:okhttp:4.+'
}

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

Application Configuration¶

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

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

R8 / Proguard Obfuscation Configuration¶

If using ft-sdk versions before 1.6.15 and need to set minifyEnabled = true in android.buildTypes, the following configuration needs to be enabled:

-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 Action is obtained ###
-keepnames class * extends android.view.View
-keepnames class * extends android.view.MenuItem

```

Initialization Instructions¶

For the minimal initialization example, please read Quick Start.

For complete FTSDKConfig parameter explanations, please 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 Permission Instructions
• Content Provider Settings
• Manual Compatibility Integration

Plugin AOP Ignore¶

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

    }
}

}

Frequently Asked Questions¶

Adding Prefixes 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, such as custom_tag_name. The key values used in the project can be queried from the source code. When global variables in the SDK appear with the same variables as RUM or Log, RUM and Log will override the global variables in the SDK.

SDK Compatibility¶

• Runnable Environment
• Compatible Environment

Adapting to Market Privacy Audits¶

For details, see Privacy and Permission Instructions.

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 of pages generated by compose components is currently not supported. However, tracking can be performed through manual Action and View custom interfaces for click events and page navigation events. For reference, see here