Android Application Integration¶

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

Reading Path¶

• First-time integration: see Quick Start
• Full integration: continue reading this document
• Parameter details: see SDK Initialization, RUM Configuration, Log Configuration, Trace Configuration
• Advanced capabilities: see the dedicated pages under the Advanced Scenarios section
• Troubleshooting: see Troubleshooting

Prerequisites¶

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

Application Integration¶

1. Go to RUM > 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, with no need to install a DataKit collector.
   • Local environment deployment: receives RUM data after the prerequisites are met.

Installation¶

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

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

Gradle Configuration¶

Add the Plugin¶

• In the build.gradle file at the project root, add the remote repository for the SDK.

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

//build.gradle
plugins{
    //Add the Plugin; requires AGP 7.4.2 or above and Gradle 7.2.0 or above
    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
    }

• In the main module's app/build.gradle file, apply the Plugin.

//Apply the plugin in app/build.gradle. Missing this configuration will affect the following automatic collection features.
// 
// 1. RUM: App launch, OkHttp requests, opt-in HTTP/HTTPS URLConnection 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 cases, only apply plugin: 'ft-plugin' is needed. You only need to add FTExt configuration when debugging plugin behavior, controlling the instrumentation scope, or manually supplementing WebView detection.

knownWebViewClasses only needs to be configured when automatic detection fails. For related troubleshooting methods, see Custom WebView automatic collection not taking effect.

Add the SDK¶

• In the build.gradle file at the project root, add the remote repository for the SDK.

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

• In the main module's app/build.gradle file, add the SDK dependency.

//app/build.gradle
dependencies {
    //Add SDK dependencies
    implementation 'com.truewatch.ft.mobile.sdk.tracker.agent:ft-sdk:[latest_version]'
    //Dependency for capturing native crash information. Must be used with ft-sdk and 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: add this when using automatic OkHttp network request collection and automatic distributed tracing. Minimum compatibility is 3.12.+ or above.
    implementation 'com.squareup.okhttp3:okhttp:4.+'
}

For the latest versions, 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 onCreate method of your Application. If your application does not already have an 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 you are using a version prior to ft-sdk 1.6.15 and 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 in action_name from being obfuscated when Action is captured###
-keepnames class * extends android.view.View
-keepnames class * extends android.view.MenuItem

Initialization Notes¶

For a minimal initialization example, see Quick Start.

For complete FTSDKConfig parameter descriptions, see SDK Initialization.

Detailed Configuration Guides¶

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

Advanced Scenarios¶

• Custom Tags
• Custom Collection Rules
• Data Collection Masking
• WebView Monitoring
• Visitor ID
• 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 skip ASM instrumentation. If you need to ignore in batches, use ignorePackages in FTExt of ft-plugin.

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

    }
});

View.setOnClickListener @IgnoreAOP {

}

FAQ¶

Add Global Variables to Avoid Field Conflicts¶

To avoid conflicts between custom fields and SDK data, it is recommended to prefix tag names with the project abbreviation, for example custom_tag_name. For the key values used in your project, you can query the source code. When SDK global variables are the same as RUM or Log variables, RUM and Log override the SDK global variables.

SDK Compatibility¶

• Runnable Environments
• Compatible Environments

Handling App Store Privacy Audits¶

For details, see Privacy and Permissions.

Third-Party Frameworks¶

flutter, react-native, uni-app, and unity can use a delayed initialization approach similar to the native Android approach described above to handle app store privacy audits.

Jetpack Compose Support¶

Automatic collection of pages generated by Compose components is currently not supported. However, you can track click events and page navigation events through the custom interfaces for manual Action and View. See here.