# Android SDK接入 APM Android SDK具备采集上报App启动性能、崩溃、卡顿、错误、网络请求、终端设备、自定义上报等应用监控能力。 #### 使用前提 使用SDK前，您需要注册华为云账号，并在App监控控制台创建移动端Android App。 #### 传输协议 HTTPS #### 版本更新说明 - SDK如何处理个人信息请参考[应用性能管理服务数据采集SDK隐私声明](https://support.huaweicloud.com/usermanual-apm2/apm_07_0168.html)。 - 您集成和使用华为的sdk时需要遵从个人信息保护基本要求，详情请参考[应用性能管理服务数据采集SDK开发者合规指南](https://support.huaweicloud.com/usermanual-apm2/apm_07_0169.html)。 表1版本更新说明 | 版本号 | SDK下载地址 | 检验信息下载地址 | 更新说明 | 系统 | |:---|:---|:---|:---|:---| | 2.1.1 | SDK[下载](https://js-agent.obs.cn-north-4.myhuaweicloud.com/apm-android-sdk-2.1.1.aar) 插件[下载](https://js-agent.obs.cn-north-4.myhuaweicloud.com/apm-plugin-core-2.1.1.jar) | SDK[下载](https://js-agent.obs.cn-north-4.myhuaweicloud.com/apm-android-sdk-2.1.1.aar.sha256) 插件[下载](https://js-agent.obs.cn-north-4.myhuaweicloud.com/apm-plugin-core-2.1.1.jar.sha256) | Native函数调用栈添加共享库的Build Id。 | Android 5 及以上 | | 2.1.0 | SDK[下载](https://js-agent.obs.cn-north-4.myhuaweicloud.com/apm-android-sdk-2.1.0.aar) 插件[下载](https://js-agent.obs.cn-north-4.myhuaweicloud.com/apm-plugin-core-2.1.0.jar) | SDK[下载](https://js-agent.obs.cn-north-4.myhuaweicloud.com/apm-android-sdk-2.1.0.aar.sha256) 插件[下载](https://js-agent.obs.cn-north-4.myhuaweicloud.com/apm-plugin-core-2.1.0.jar.sha256) | 兼容APM Flutter SDK。 | Android 5 及以上 | | 2.0.24 | SDK[下载](https://js-agent.obs.cn-north-4.myhuaweicloud.com/apm-android-sdk-2.0.24.aar) 插件[下载](https://js-agent.obs.cn-north-4.myhuaweicloud.com/apm-plugin-core-2.0.24.jar) | SDK[下载](https://js-agent.obs.cn-north-4.myhuaweicloud.com/apm-android-sdk-2.0.24.aar.sha256) 插件[下载](https://js-agent.obs.cn-north-4.myhuaweicloud.com/apm-plugin-core-2.0.24.jar.sha256) | 修复链路追踪问题。 | Android 5 及以上 | | 2.0.23 | SDK[下载](https://js-agent.obs.cn-north-4.myhuaweicloud.com/apm-android-sdk-2.0.23.aar) 插件[下载](https://js-agent.obs.cn-north-4.myhuaweicloud.com/apm-plugin-core-2.0.23.jar) | SDK[下载](https://js-agent.obs.cn-north-4.myhuaweicloud.com/apm-android-sdk-2.0.23.aar.sha256) 插件[下载](https://js-agent.obs.cn-north-4.myhuaweicloud.com/apm-plugin-core-2.0.23.jar.sha256) | 修复HttpURLConnection网络监控问题。 | Android 5 及以上 | | 2.0.22 | SDK[下载](https://js-agent.obs.cn-north-4.myhuaweicloud.com/apm-android-sdk-2.0.22.aar) 插件[下载](https://js-agent.obs.cn-north-4.myhuaweicloud.com/apm-plugin-core-2.0.22.jar) | SDK[下载](https://js-agent.obs.cn-north-4.myhuaweicloud.com/apm-android-sdk-2.0.22.aar.sha256) 插件[下载](https://js-agent.obs.cn-north-4.myhuaweicloud.com/apm-plugin-core-2.0.22.jar.sha256) | 修复启动耗时数值异常。 | Android 5 及以上 | | 2.0.21 | SDK[下载](https://js-agent.obs.cn-north-4.myhuaweicloud.com/apm-android-sdk-2.0.21.aar) 插件[下载](https://js-agent.obs.cn-north-4.myhuaweicloud.com/apm-plugin-core-2.0.21.jar) | SDK[下载](https://js-agent.obs.cn-north-4.myhuaweicloud.com/apm-android-sdk-2.0.21.aar.sha256) 插件[下载](https://js-agent.obs.cn-north-4.myhuaweicloud.com/apm-plugin-core-2.0.21.jar.sha256) | 修复特定环境下的插桩失败。 | Android 5 及以上 | | 2.0.20 | SDK[下载](https://js-agent.obs.cn-north-4.myhuaweicloud.com/apm-android-sdk-2.0.20.aar) 插件[下载](https://js-agent.obs.cn-north-4.myhuaweicloud.com/apm-plugin-core-2.0.20.jar) | SDK[下载](https://js-agent.obs.cn-north-4.myhuaweicloud.com/apm-android-sdk-2.0.20.aar.sha256) 插件[下载](https://js-agent.obs.cn-north-4.myhuaweicloud.com/apm-plugin-core-2.0.20.jar.sha256) | 修复OkHttp2自定义拦截器失效问题。 | Android 5 及以上 | | 2.0.19 | SDK[下载](https://js-agent.obs.cn-north-4.myhuaweicloud.com/apm-android-sdk-2.0.19.aar) 插件[下载](https://js-agent.obs.cn-north-4.myhuaweicloud.com/apm-plugin-core-2.0.19.jar) | SDK[下载](https://js-agent.obs.cn-north-4.myhuaweicloud.com/apm-android-sdk-2.0.19.aar.sha256) 插件[下载](https://js-agent.obs.cn-north-4.myhuaweicloud.com/apm-plugin-core-2.0.19.jar.sha256) | 修复OkHttp3网络监控问题。 | Android 5 及以上 | | 2.0.17 | SDK[下载](https://js-agent.obs.cn-north-4.myhuaweicloud.com/apm-android-sdk-2.0.17.aar) 插件[下载](https://js-agent.obs.cn-north-4.myhuaweicloud.com/apm-plugin-core-2.0.17.jar) | SDK[下载](https://js-agent.obs.cn-north-4.myhuaweicloud.com/apm-android-sdk-2.0.17.aar.sha256) 插件[下载](https://js-agent.obs.cn-north-4.myhuaweicloud.com/apm-plugin-core-2.0.17.jar.sha256) | 修复HttpURLConnection网络监控问题。 | Android 5 及以上 | | 2.0.16 | SDK[下载](https://js-agent.obs.cn-north-4.myhuaweicloud.com/apm-android-sdk-2.0.16.aar) 插件[下载](https://js-agent.obs.cn-north-4.myhuaweicloud.com/apm-plugin-core-2.0.16.jar) | SDK[下载](https://js-agent.obs.cn-north-4.myhuaweicloud.com/apm-android-sdk-2.0.16.aar.sha256) 插件[下载](https://js-agent.obs.cn-north-4.myhuaweicloud.com/apm-plugin-core-2.0.16.jar.sha256) | 修复HttpURLConnection网络监控问题。 | Android 5 及以上 | | 2.0.15 | SDK[下载](https://js-agent.obs.cn-north-4.myhuaweicloud.com/apm-android-sdk-2.0.15.aar) 插件[下载](https://js-agent.obs.cn-north-4.myhuaweicloud.com/apm-plugin-core-2.0.15.jar) | SDK[下载](https://js-agent.obs.cn-north-4.myhuaweicloud.com/apm-android-sdk-2.0.15.aar.sha256) 插件[下载](https://js-agent.obs.cn-north-4.myhuaweicloud.com/apm-plugin-core-2.0.15.jar.sha256) | 修复网络请求白名单未生效的问题。 | Android 5 及以上 | | 2.0.14 | SDK[下载](https://js-agent.obs.cn-north-4.myhuaweicloud.com/apm-android-sdk-2.0.14.aar) 插件[下载](https://js-agent.obs.cn-north-4.myhuaweicloud.com/apm-plugin-core-2.0.14.jar) | SDK[下载](https://js-agent.obs.cn-north-4.myhuaweicloud.com/apm-android-sdk-2.0.14.aar.sha256) 插件[下载](https://js-agent.obs.cn-north-4.myhuaweicloud.com/apm-plugin-core-2.0.14.jar.sha256) | 1. 支持采样率。 2. 优化崩溃采集。 | Android 5 及以上 | | 2.0.13 | SDK[下载](https://js-agent.obs.cn-north-4.myhuaweicloud.com/apm-android-sdk-2.0.13.aar) 插件[下载](https://js-agent.obs.cn-north-4.myhuaweicloud.com/apm-plugin-core-2.0.13.jar) | SDK[下载](https://js-agent.obs.cn-north-4.myhuaweicloud.com/apm-android-sdk-2.0.13.aar.sha256) 插件[下载](https://js-agent.obs.cn-north-4.myhuaweicloud.com/apm-plugin-core-2.0.13.jar.sha256) | 1. 解决AGP8.0+兼容性问题。 2. minSDK支持到21。 | Android 5 及以上 | | 2.0.12 | SDK[下载](https://repo1.maven.org/maven2/io/github/apm-sdk/apm-sdk-android/2.0.12/apm-sdk-android-2.0.12.aar) 插件[下载](https://repo1.maven.org/maven2/io/github/apm-sdk/apm-sdk-plugin/2.0.12/apm-sdk-plugin-2.0.12.jar) | SDK[下载](https://repo1.maven.org/maven2/io/github/apm-sdk/apm-sdk-android/2.0.12/apm-sdk-android-2.0.12.aar.sha1) 插件[下载](https://repo1.maven.org/maven2/io/github/apm-sdk/apm-sdk-plugin/2.0.12/apm-sdk-plugin-2.0.12.jar.sha1) | 兼容Gradle 6.7.1、AGP 4.2.0、JDK 11、Android 30（compileSdk）。 | Android 7 及以上 | | 2.0.11 | SDK[下载](https://js-agent.obs.cn-north-4.myhuaweicloud.com/apm-android-sdk-2.0.11.aar) 插件[下载](https://js-agent.obs.cn-north-4.myhuaweicloud.com/apm-plugin-core-2.0.11.jar) | SDK[下载](https://js-agent.obs.cn-north-4.myhuaweicloud.com/apm-android-sdk-2.0.11.aar.sha256) 插件[下载](https://js-agent.obs.cn-north-4.myhuaweicloud.com/apm-plugin-core-2.0.11.jar.sha256) | 优化数据上传逻辑。 | Android 7 及以上 | | 2.0.10 | SDK[下载](https://js-agent.obs.cn-north-4.myhuaweicloud.com/apm-android-sdk-2.0.10.aar) 插件[下载](https://js-agent.obs.cn-north-4.myhuaweicloud.com/apm-plugin-core-2.0.10.jar) | SDK[下载](https://js-agent.obs.cn-north-4.myhuaweicloud.com/apm-android-sdk-2.0.10.aar.sha256) 插件[下载](https://js-agent.obs.cn-north-4.myhuaweicloud.com/apm-plugin-core-2.0.10.jar.sha256) | - 修复网络错误时上报有null的问题。 - 修复插件加载时会出现未完成配置的问题。 - 修复插件插桩异常后复制文件失败的问题。 | Android 7 及以上 | | 2.0.9 | SDK[下载](https://js-agent.obs.cn-north-4.myhuaweicloud.com/apm-android-sdk-2.0.9.aar) 插件[下载](https://js-agent.obs.cn-north-4.myhuaweicloud.com/apm-plugin-core-2.0.9.jar) | SDK[下载](https://js-agent.obs.cn-north-4.myhuaweicloud.com/apm-android-sdk-2.0.9.aar.sha256) 插件[下载](https://js-agent.obs.cn-north-4.myhuaweicloud.com/apm-plugin-core-2.0.9.jar.sha256) | - 插件添加功能开关配置，帮助调试定位问题。 - 修复了链路追踪开关的远程配置生效时机错误的问题。 - 修复了ANR错误栈日志显示重复的问题。 | Android 7 及以上 | | 2.0.8 | SDK[下载](https://js-agent.obs.cn-north-4.myhuaweicloud.com/apm-android-sdk-2.0.8.aar) 插件[下载](https://js-agent.obs.cn-north-4.myhuaweicloud.com/apm-plugin-core-2.0.8.jar) | SDK[下载](https://js-agent.obs.cn-north-4.myhuaweicloud.com/apm-android-sdk-2.0.8.aar.sha256) 插件[下载](https://js-agent.obs.cn-north-4.myhuaweicloud.com/apm-plugin-core-2.0.8.jar.sha256) | 修复工程配置导致的冲突问题。 | Android 7 及以上 | | 2.0.7 | SDK[下载](https://js-agent.obs.cn-north-4.myhuaweicloud.com/apm-android-sdk-2.0.7.aar) 插件[下载](https://js-agent.obs.cn-north-4.myhuaweicloud.com/apm-plugin-core-2.0.7.jar) | SDK[下载](https://js-agent.obs.cn-north-4.myhuaweicloud.com/apm-android-sdk-2.0.7.aar.sha256) 插件[下载](https://js-agent.obs.cn-north-4.myhuaweicloud.com/apm-plugin-core-2.0.7.jar.sha256) | 支持远程配置功能。 | Android 7 及以上 | | 2.0.6 | SDK[下载](https://js-agent.obs.cn-north-4.myhuaweicloud.com/apm-android-sdk-2.0.6.aar) 插件[下载](https://js-agent.obs.cn-north-4.myhuaweicloud.com/apm-plugin-core-2.0.6.jar) | SDK[下载](https://js-agent.obs.cn-north-4.myhuaweicloud.com/apm-android-sdk-2.0.6.aar.sha256) 插件[下载](https://js-agent.obs.cn-north-4.myhuaweicloud.com/apm-plugin-core-2.0.6.jar.sha256) | 修复了配置导致SDK启动失败的问题。 | Android 7 及以上 | | 2.0.5 | SDK[下载](https://js-agent.obs.cn-north-4.myhuaweicloud.com/apm-android-sdk-2.0.5.aar) 插件[下载](https://js-agent.obs.cn-north-4.myhuaweicloud.com/apm-plugin-core-2.0.5.jar) | SDK[下载](https://js-agent.obs.cn-north-4.myhuaweicloud.com/apm-android-sdk-2.0.5.aar.sha256) 插件[下载](https://js-agent.obs.cn-north-4.myhuaweicloud.com/apm-plugin-core-2.0.5.jar.sha256) | 适配了 Gradle8.0及以上版本的 transform API。 | Android 7 及以上 | | 2.0.4 | SDK[下载](https://js-agent.obs.cn-north-4.myhuaweicloud.com/apm-android-sdk-2.0.4.aar) 插件[下载](https://js-agent.obs.cn-north-4.myhuaweicloud.com/apm-plugin-core-2.0.4.jar) | SDK[下载](https://js-agent.obs.cn-north-4.myhuaweicloud.com/apm-android-sdk-2.0.4.aar.sha256) 插件[下载](https://js-agent.obs.cn-north-4.myhuaweicloud.com/apm-plugin-core-2.0.4.jar.sha256) | - 适配配置文件字段，修复插件无法响应日志字段的问题。 - 网络拦截升级，修复了使用 URLConnection 时，特殊情况无法上报的问题 | Android 7 及以上 | | 2.0.1 | SDK[下载](https://js-agent.obs.cn-north-4.myhuaweicloud.com/apm-android-sdk-2.0.1.aar) 插件[下载](https://js-agent.obs.cn-north-4.myhuaweicloud.com/apm-plugin-core-2.0.1.jar) | SDK[下载](https://js-agent.obs.cn-north-4.myhuaweicloud.com/apm-android-sdk-2.0.1.aar.sha256) 插件[下载](https://js-agent.obs.cn-north-4.myhuaweicloud.com/apm-plugin-core-2.0.1.jar.sha256) | 提供采集上报App启动性能、崩溃、卡顿、错误、网络请求、终端设备、自定义上报等应用监控能力。 | Android 7 及以上 | #### 操作步骤 1. 集成接入SDK。 - 方法1：maven仓库集成。 1. 在build.gradle中添加依赖。 ``` buildscript { dependencies { ... classpath 'io.github.apm-sdk:apm-sdk-plugin:2.1.1' ... } } plugins { ... id 'org.jetbrains.kotlin.android' version 'KOTLIN_VERSION' apply false // 添加kotlin插件，最低支持1.6.20版本 ... } ``` 2. 在app/build.gradle中添加依赖。 ``` plugins { ... id 'org.jetbrains.kotlin.android' id 'kotlin-kapt' id 'com.cloud.apm.plugin' // 添加依赖插件 ... } dependencies { ... implementation 'io.github.apm-sdk:apm-sdk-android:2.1.1' // 添加APM SDK依赖 ... } ``` 3. 在settings.gradle中添加maven仓库源。 ``` pluginManagement{ ... repositories { ... // 加入下面内容 mavenCentral() } } dependencyResolutionManagement { ... repositories { ... // 加入下面内容 mavenCentral() } } ``` - 方法2：手动集成。 1. 下载SDK和插件的文件包。 2. 将扩展名为jar文件的插件包添加到您的项目工程中。 3. 在build.gradle中添加依赖。 ``` buildscript { dependencies { classpath fileTree(dir: $dir, include: '*.jar') // 填入jar所在的文件夹，例如 libs } } ``` 4. 将扩展名为aar文件的SDK包添加到您的项目工程中。 5. 在app/build.gradle中添加依赖。 ``` dependencies { ... implementation fileTree(dir: $dir, include: ['*.aar']) // 填入aar所在的文件夹，例如 libs implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-core:1.4.0' implementation 'androidx.core:core-ktx:1.6.0' implementation 'com.google.code.gson:gson:2.8.9' kapt 'androidx.room:room-compiler:2.4.0' api 'androidx.room:room-runtime:2.4.0' api 'androidx.room:room-common:2.4.0' ... } ``` 6. 在settings.gradle中添加maven仓库源。 ``` pluginManagement{ ... repositories { ... // 加入下面内容 google() mavenCentral() } } dependencyResolutionManagement { ... repositories { ... // 加入下面内容 google() mavenCentral() } } ``` 如果您的Gradle版本低于7.0 则需要将maven仓库源添加到build.gradle文件中。 2. 添加配置文件。 在控制台添加移动端Android App，下载apm-sdk-config.json的配置文件，将其拖拽至app的根目录，如下图所示： ![](https://support.huaweicloud.com/usermanual-apm2/zh-cn_image_0000002518175826.png "点击放大") 表2配置参数说明 | 参数名称 | 是否必填 | 默认值 | 描述 | |:---|:---|:---|:---| | appId | 是 | - | 移动端AppID。 | | authorization | 是 | - | 用于App的匹配。 | | region | 是 | - | 上报APM所处的region，目前支持cn-north-4。 | | uid | 否 | - | 用户自定义ID。 | | tag | 否 | - | 用户自定义标签，多个时使用英文逗号隔开。 | | url | 否 | - | 要上报APM的公网地址域名。 | | networkWhiteList | 否 | - | 网络监控白名单，排除监控。 | | cacheThreshold | 否 | 200条 | 当本地数据库存储条数达到该值会触发上报，取值范围为30-1000条。 | | timeInterval | 否 | 60秒 | 定时器每隔该值会触发上报，取值范围为60-1800秒。 | | reportBackground | 否 | true | 是否开启APP切后台上报功能。 | | reportLaunch | 否 | false | 是否开启APP启动时上报功能。如需开启，请在UIApplicationDidFinishLaunchingNotification通知发送前启动SDK。 | | enableNetwork | 否 | false | 是否开启网络采集。 | | enableCrash | 否 | false | 是否开启崩溃采集。 | | enableLaunch | 否 | false | 是否开启启动采集。 | | enableANR | 否 | false | 是否开启卡顿采集。 | | enableError | 否 | false | 是否开启错误采集。 | | enableDevice | 否 | false | 是否开启终端设备采集。 | | enableEvent | 否 | false | 是否开启用户自定义上报。 | | traceType | 否 | apm | 链路追踪类型。 - 开启：otel。 - 关闭：apm。 | | logLevel | 否 | off | 调试日志等级。 - debug - info - warn - error - off | | samplingRate | 否 | 1.0 | 采样率，取值范围0\~1.0。 | 3. 启动SDK。 - Kotlin代码示例。 ``` import com.cloud.apm.APMSDK // 根据apm-sdk-config.json配置文件启动SDK APMSDK.start(this) // （可选）设置自定义ID APMSDK.setUid("自定义ID") // （可选）设置自定义标签 APMSDK.addTag("自定义标签1,自定义标签2,自定义标签3") ``` - Java代码示例。 ``` import com.cloud.apm.APMSDK // 根据apm-sdk-config.json配置文件启动SDK APMSDK.start(); // （可选）设置自定义ID APMSDK.setUid("自定义ID"); // （可选）设置自定义标签 APMSDK.addTag("自定义标签1,自定义标签2,自定义标签3"); ``` 4. 自定义上报统计 （可选步骤）。 | 方法名称 | 参数说明 | |:---|:---| | fun \ event(key: String, event: HashMap\); fun \ event(key: String, event: Array\) fun event(key: String, event: Number) fun event(key: String, event: String) | key：事件名称, String类型，最大长度为2048个字符。value：事件内容，支持String，Array，HashMap， Number等有效的JSON对象，转JSON字符串最大长度为30720个字符。 | Kotlin 代码示例： ``` // 事件统计示例 APMSDK.event("User Information", hashMapOf(Pair("name","zhang san"))) APMSDK.event("Call Stack", listOf("0x0000000101ee9c6c","0x0000600000e61d80").toTypedArray()) APMSDK.event("Error Description", "The request timed out.") // 数值统计示例 APMSDK.event("Purchase Statistic", 1653) APMSDK.event("Custom Load Time", 1.653) ``` Java 代码示例： ``` // 事件统计示例 HashMap user = new HashMap(); user.put("name","zhang san"); APMSDK.event("User Information", user); String[] stacks = {"0x0000000101ee9c6c", "0x0000600000e61d80"}; APMSDK.event("Call Stack", stacks); APMSDK.event("Error Description", "The request timed out."); // 数值统计示例 APMSDK.event("Purchase Statistic", 1653); APMSDK.event("Custom Load Time", 1.653); ``` #### 混淆配置 如App对代码进行混淆，请在混淆配置文件proguard-rules.pro添加代码： ``` # 请根据App自身要求选择性设置：保留源文件名、源代码行号 -keepattributes LineNumberTable, SourceFile # 防止APM SDK被混淆 -keep class com.cloud.apm.**{*;} # 如果使用gradle 8.x 请自行选择使用下面的配置 -keepclasseswithmembers class okhttp3.**{*;} # 使用okhttp3&okhttp4 -dontwarn okhttp3.** # 未使用okhttp3&okhttp4 -keepclasseswithmembers class com.squareup.okhttp.**{*;} # 使用 okhttp2 -dontwarn com.squareup.okhttp.** # 未使用 okhttp2 ``` #### ASM版本配置 如发生以下编译错误： ``` java.lang.UnsupportedOperationException: NestMember requires ASM7 at org.objectweb.asm.ClassVisitor.visitNestMember(ClassVisitor.java:265) at org.objectweb.asm.ClassReader.accept(ClassReader.java:697) at org.objectweb.asm.ClassReader.accept(ClassReader.java:425) at com.cloud.apm.plugin.tasks.trace.methodTrace.MethodTracer.innerTraceMethodFromJar(MethodTracer.kt:184) at com.cloud.apm.plugin.tasks.trace.methodTrace.MethodTracer.traceMethodFromJar$lambda-4$lambda-3(MethodTracer.kt:89) ``` 请在gradle.properties添加如下代码： ``` com.cloud.apm.asmApi=ASM7 ``` #### 权限配置 APMSDK需要Android的权限如下：网络权限、网络状态权限，权限已经在SDK的Manifest.xml 配置。 #### 数据上报策略 SDK支持四种上报策略：阈值上报、定时上报、应用切后台和启动时上报，根据场景选择合适的值配置cacheThreshold、timeInterval、reportBackground、reportLaunch等参数。 #### 开启调试日志 在开发过程中可以启用调试模式，借助控制台实时查看SDK运行状况，观察具体结果并根据需要进行调整，调试级别有：debug、info、warn、error、off（关闭）。 示例: 在配置文件apm-sdk-config.json中设置调试级别 ``` { "logLevel": "debug" } ```