Android SDK接入

使用前提

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

传输协议

HTTPS

版本更新说明

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

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

操作步骤

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

        buildscript {
            dependencies {
                ...
                classpath 'io.github.apm-sdk:apm-sdk-plugin:2.0.4'
                ...
            }
        }
        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.4' // 添加APM SDK依赖
            ...
        }

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

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

   方法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.5.0'
         implementation 'com.google.code.gson:gson:2.8.9'
         kapt 'androidx.room:room-compiler:2.3.0'
         api 'androidx.room:room-runtime:2.3.0'
         api 'androidx.room:room-common:2.3.0'
         ...
     }

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

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

   

   如果你的Gradle版本低于7.0 则需要将mavan仓库源添加到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.**{*;} 

权限配置

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

开启调试日志

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

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