Android SDK接入

使用前提

使用SDK前，您需要注册华为账号，并在App监控控制台创建移动端Android App。

传输协议

HTTPS

版本更新说明

sdk如何处理个人信息请参考华为云应用性能分析服务数据采集SDK隐私声明。

您集成和使用华为的sdk时需要遵从个人信息保护基本要求，详情请参考华为云应用性能分析服务数据采集SDK开发者合规指南。

操作步骤

1. 集成接入SDK。
   1. 方法1：maven仓库集成。
      • 在build.gradle中添加依赖。

        buildscript {
            dependencies {
                ...
                classpath 'io.github.apm-sdk:apm-sdk-plugin:2.0.10'
                ...
            }
        }
        plugins {
            ...
            id 'org.jetbrains.kotlin.android' version 'KOTLIN_VERSION' apply false  // 添加kotlin插件，最低支持1.6.20版本
            ...
        }

      • 在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.0.10' // 添加APM SDK依赖
            ...
        }

      • 在 settings.gradle中添加maven仓库源。

        pluginManagement{
            ...
            repositories {
                ...
                // 加入下面内容
                mavenCentral()
           }
        }
        dependencyResolutionManagement {
            ...
            repositories {
                ...
                // 加入下面内容
                mavenCentral()
           }
        }

   2. 方法2：手动集成
      • 下载SDK和插件的文件包。
      • 将扩展名为jar文件的插件包添加到您的项目工程中。
      • 在build.gradle中添加依赖。

        buildscript {
            dependencies {
                classpath fileTree(dir: $dir, include: '*.jar') // 填入jar所在的文件夹，例如 libs
            }
        }

      • 将扩展名为aar文件的SDK包添加到您的项目工程中。
      • 在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'
            ...
        }

      • 在 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的根目录，如下图所示：

   

   配置参数说明：

   参数名称	是否必填	默认值	描述
   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启动时上报功能。如需开启，请在Application的onCreate方法中启动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。

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 <T> event(key: String, event: HashMap<String, T>); fun <T> event(key: String, event: Array<T>) 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<String, String> user = new HashMap(){{
       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);

数据上报策略

SDK支持四种日志上报策略：阈值上报、定时上报、应用切后台和启动时上报，根据场景选择合适的值配置cacheThreshold、timeInterval、reportBackground、reportLaunch等参数。

混淆配置

如App对代码进行乱序混淆，则在混淆配置文件中添加代码段：

-keep class com.cloud.apm.**{*;} 
# 如果使用gradle 8.x 请自行选择使用下面的配置
-keep classeswithmembers class okhttp3.**{*;} # 使用okhttp3&okhttp4
-dontwarn okhttp3.** # 未使用okhttp3&okhttp4
-keep classeswithmembers class com.squareup.okhttp.**{*;} # 使用 okhttp2
-dontwarn com.squareup.okhttp.** # 未使用 okhttp2

权限配置

APMSDK 需要 Android 的权限如下：网络权限、网络状态权限，权限已经在SDK的Manifest.xml 配置。

开启调试日志

在开发过程中可以启用调试模式，借助控制台日志实时查看SDK运行状况，观察具体结果并根据需要进行调整，调试级别有：debug、info、warn、error、off（关闭）。

示例: 在配置文件apm-sdk-config.json中设置调试级别