跳转至

Android 应用接入

通过收集 Android 应用的指标数据，以可视化方式分析应用性能。

阅读路径

前置条件

注意

若已开通 RUM Headless 服务，前置条件已自动配置，可直接接入应用。

应用接入

  1. 进入用户访问监测 > 新建应用 > Android；
  2. 输入应用名称；
  3. 输入应用 ID；

  4. 选择应用接入方式：

    • 公网 DataWay：直接接收 RUM 数据，无需安装 DataKit 采集器。
    • 本地环境部署：满足前置条件后接收 RUM 数据。

安装

源码地址：https://github.com/GuanceCloud/datakit-android

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

Gradle 配置

引入 Plugin

  • 在项目根目录的 build.gradle 文件中添加 SDK 的远程仓库地址
//build.gradle
buildscript {
    //...
    repositories {
        //...
        //添加  Plugin 的远程仓库地址
        maven {
            url 'https://mvnrepo.jiagouyun.com/repository/maven-releases'
        }
    }
    dependencies {
        //...
        //添加 Plugin 的插件，依赖 AGP 7.4.2 以上，Gradle 7.2.0 以上
        classpath 'com.cloudcare.ft.mobile.sdk.tracker.plugin:ft-plugin:[latest_version]'
        // AGP 7.4.2 以下版本，请使用 ft-plugin-legacy 
        //classpath 'com.cloudcare.ft.mobile.sdk.tracker.plugin:ft-plugin-legacy:[latest_version]'
    }
}

//setting.gradle
pluginManagement {
    repositories {
        google()
        mavenCentral()
        gradlePluginPortal()
        //添加 Plugin 的远程仓库地址
        maven {
            url('https://mvnrepo.jiagouyun.com/repository/maven-releases')
        }
    }
}

//build.gradle
plugins{
    //添加 Plugin 的插件，依赖 AGP 7.4.2 以上，Gradle 7.2.0 以上
    id 'com.cloudcare.ft.mobile.sdk.tracker.plugin' version '[latest_version]' apply false
    // AGP 7.4.2 以下版本，请使用 ft-plugin-legacy 
    //id 'com.cloudcare.ft.mobile.sdk.tracker.plugin.legacy' version '[latest_version]' apply false
}
  • 在项目主模块 app/build.gradle 文件中添加 Plugin 的使用
//在 app/build.gradle 中应用插件，缺失配置会影响下列自动采集功能。
// 
// 1.RUM：App 启动、OkHttp 请求、WebView 活动 Activity/Fragment 跳转、点击事件
// 2.Log：Console Logcat 
apply plugin: 'ft-plugin'  //如果使用的是 ft-plugin-legacy，同样也使用这个配置

//可选：按需配置插件参数
FTExt {
    //showLog = true
    //asmVersion='asm7'
    //ignorePackages=['com.ft','com/ft']
    //knownWebViewClasses = ['com.your.CustomWebView']
}

插件参数均为可选项。大多数场景下，仅需 apply plugin: 'ft-plugin' 即可；只有在调试插件行为、控制插桩范围，或手动补充 WebView 识别时，才需要增加 FTExt 配置。

参数名 类型 默认值 说明 适用场景
showLog Boolean false 是否输出 ft-plugin 的构建日志。 调试插件执行过程、排查插桩是否生效时开启。
asmVersion String asm9 指定插件使用的 ASM 版本，可选 asm7 ~ asm9。 与项目中其他字节码处理插件存在兼容性要求时调整。
ignorePackages String[] 空 配置不进行 ASM 插桩的包路径；路径分隔可使用 . 或 /。 需要跳过某些业务包、三方包或与其他插件冲突的代码时使用。
knownWebViewClasses String[] 空 手动声明需要识别为 WebView 的自定义类。 自定义 WebView 继承层级较复杂，自动识别未生效时使用。

knownWebViewClasses 仅在自动识别失败时才需要配置。相关排查方法可参考自定义 WebView 自动采集未生效。

引入 SDK

  • 在项目的根目录的 build.gradle 文件中添加 SDK 的远程仓库地址
//build.gradle
allprojects {
    repositories {
        //...
        //添加 SDK 的远程仓库地址
        maven {
            url 'https://mvnrepo.jiagouyun.com/repository/maven-releases'
        }
    }
}

//build.gradle
dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
        //添加 SDK 的远程仓库地址
        maven {
            url('https://mvnrepo.jiagouyun.com/repository/maven-releases')
        }
    }
}
  • 在项目主模块 app/build.gradle 文件中添加 SDK 的依赖
//app/build.gradle
dependencies {
    //添加 SDK 的依赖
    implementation 'com.cloudcare.ft.mobile.sdk.tracker.agent:ft-sdk:[latest_version]'
    //捕获 native 层崩溃信息的依赖，需要配合 ft-sdk 使用，不能单独使用
    implementation 'com.cloudcare.ft.mobile.sdk.tracker.agent:ft-native:[latest_version]'
    // json 序列化
    implementation 'com.google.code.gson:gson:2.8.+'
    //可选，如果需要自动采集网络请求和自动开启链路必须添加，最低兼容 3.12.+ 以上版本
    implementation 'com.squareup.okhttp3:okhttp:4.+'
}

最新的版本请看上方的 ft-sdk、ft-plugin、ft-native 的版本名。

Application 配置

最佳的 SDK 初始化位置是在 Application 的 onCreate 方法中，如果您的应用尚未创建 Application，您需要创建一个，并在 AndroidManifest.xml 中声明，示例请参考这里。

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

R8 / Proguard 混淆配置

如果使用的是 ft-sdk 1.6.15 之前的版本，并且需要在 android.buildTypes 中设置 minifyEnabled = true，需要开启如下配置：

-dontwarn com.ft.sdk.**

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

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

### 防止 Action 获取时 action_name 中类名被混淆###
-keepnames class * extends android.view.View
-keepnames class * extends android.view.MenuItem

```

初始化说明

最小初始化示例请阅读 快速开始。

完整 FTSDKConfig 参数说明请阅读 SDK 初始化。

详细配置入口

高级场景

Plugin AOP 忽略

通过 Plugin AOP 覆盖方法中添加 @IgnoreAOP 来忽略 ASM 插入。如果需要批量忽略，请通过使用 ft-plugin FTExt 中 ignorePackages 进行忽略。

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

    }
}

```

```kotlin View.setOnClickListener @IgnoreAOP{

}

```

常见问题

添加局变量避免冲突字段

为了避免自定义字段与 SDK 数据冲突，建议标签命名添加 项目缩写 的前缀，例如 df_tag_name，项目中使用 key 值可查询源码。SDK 全局变量中出现与 RUM、Log 相同变量时，RUM、Log 会覆盖 SDK 中的全局变量。

SDK 兼容性

应对市场隐私审核

详见 隐私与权限说明。

第三方框架

flutter、react-native、uni-app、unity 可以采用与以上原生 Android 相似延迟初始化方式，来应对应用市场隐私审核。

Jetpack Compose 支持

目前暂时不支持自动采集 compose 组件生成的页面，但是可以通过手动 Action 和 View 的自定义接口，点击事件和页面跳转事件进行追踪，可以参考这里

文档评价

文档内容是否对您有帮助？ ×