操作场景
本文指导您使用 Android SDK 的集成与初始化。
说明:
操作步骤
步骤一:Gradle 集成
1. 在 settings.gradle 中添加 maven 仓库源。
参考代码:
pluginManagement {...repositories {...// 加入下面内容maven { url 'https://qapm-maven.pkg.coding.net/repository/qapm_sdk/android_release/' }}}dependencyResolutionManagement {...repositories {...// 加入下面内容maven { url 'https://qapm-maven.pkg.coding.net/repository/qapm_sdk/android_release/' }}}
注意:
如果您的 gradle 版本低于 7.0,请在 project 的 build.gradle 添加 maven 仓库源,如下所示:
2. 在 project 的 build.gradle 文件下增加插件的依赖。
参考代码:
buildscript {...dependencies {...// 加入下面的内容classpath 'com.tencent.qapmplugin:qapm-plugin:3.2'...}}
注意:
如果您的 gradle 版本小于 7.4,则将插件版本改为 2.39。
3. 在 app 的 build.gradle 文件下增加以下代码:
参考代码:
plugins {...id('qapm-plugin') //添加插件...}...preBuild.dependsOn(UUIDGenerator) //生成唯一标识,用于后续堆栈翻译...dependencies {...//添加qapmsdk依赖implementation 'com.tencent.qapm:qapmsdk:5.5.0-pub'...}
4. 请通过以下内容检查是否需要执行此步骤。
请在 Application 所在的类中输入 attachBaseContext,检查是否有这个的重写方法,如有重写方法则忽略该步骤,如没有请执行下一步。
请将 Application 的包名路径添加进以下配置,如下所示:
参考代码:
QAPMPluginConfig {// 可选,默认为空。请在Application所在的类中输入attachBaseContext,检查是否有这个重写方法,如果没有则需要配置该项,如下图所示就是无需配置该项的校验// tinkerApplication = 'com/tencent/qapm/demoApplication'}
5. 此时您可以尝试进行编译。编译相关的 FAQ 可以查看此步骤。
Q1:如果编译时出现 “feature is disabled” 的错误,如下:
A1: 这是因为插件需要动态在 BuildConfig 插入属性,请在 app 模块的 build.gradle 文件下增加以下代码。
参考代码:
android {...// 加入下面内容buildFeatures {...buildConfig true}...}
Q2: 如果编译时出现 “类冲突” 的错误,如下:
A2: 这是由于 qapm 与您的工程使用了 android 不同的 support 库,这里请在依赖的时候移除掉qapm 的 android.support 库,如下:
参考代码:
dependencies {...implementation ('com.tencent.qapm:qapmsdk:5.5.0-pub') {// 加入下面内容exclude group: 'com.android.support'}...}
注意:
如果未使用 qapm-plugin 插件,则会影响启动、网络的监控。
步骤二:参数配置
1. 在 AndroidManifest.xml 中添加以下权限。
<!--上报信息所需--><uses-permission android:name="android.permission.INTERNET" /><!--采集信息所需--><uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" /><uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
2. 为了避免混淆 SDK,在 App 的 proguard-rules.pro 文件中增加以下配置:
-keep class com.tencent.qapmsdk.**{*;}# 如需要网络监控,请确保okhttp3不被混淆-keep class okhttp3.**{*;}
步骤三:初始化 SDK
1. 登录 腾讯云可观测平台 控制台,在终端性能监控页面 ,选择 应用管理 > 应用设置 后,获取 Appkey(上报 ID)。
2. 拷贝下面代码,并修改其中部分字段。确保必需的接口被正确配置,其余接口配置请参考初始化的接口分析(建议在 Application 中初始化 QAPM)
。
// 为响应工信部“26号文”要求,提供该设置用于告知SDK是否可以进行可选个人信息的采集,该设置需要最先配置,一旦设置则全局生效。默认可以采集,设置为false则不采集,可能会影响到控制台的搜索、展示等。QAPM.setProperty(QAPM.PropertyKeyCollectOptionalFields, true);//该设置默认为false,设置为true时,QAPM的SDK网络监控数据中的个例数据和腾讯云可观测平台的应用性能监控的全链路数据将会打通,另外有以下几点业务方需要注意:// 业务网络请求的requestHeader会增加sw8、traceparent相关协议下的value值,如果业务自行组建了全链路监控则可以设置为falseQAPM.setProperty(QAPM.PropertyNeedOpenTrace, false);// 设置手机型号和设备ID,在隐私合规政策下,QAPM不可直接/间接获取mac地址、imei、androidid等隐私信息,但为了确保指标统计的准确性,需要用户参考 隐私合规 的建议,在统一获取相关信息后将信息按照既定方式处理,生成不敏感的QAPM设备唯一标识符并传参给SDK// 需要传入设备的唯一标识(必需!!)QAPM.setProperty(QAPM.PropertyKeyDeviceId, "设备的唯一标识");// 需要传入手机型号(必需!!)QAPM.setProperty(QAPM.PropertyKeyModel, "填写手机型号");// 设置Application(必需)QAPM.setProperty(QAPM.PropertyKeyAppInstance, getApplication());// 设置AppKey(必需,用于区分上报的产品,该值由移动监控的产品配置页面获取 )QAPM.setProperty(QAPM.PropertyKeyAppId, "Your AppKey");// 设置产品版本,用于后台检索字段(必需)QAPM.setProperty(QAPM.PropertyKeyAppVersion, "Your App Version");// 设置UUID,用于拉取被混淆堆栈的mapping (必需,若使用了QAPM符号表上传插件,可以直接使用该变量,否则请遵循UUID格式,自行传入该参数,请注意UUID与一次构建是相互对应关系,为了区分不同的构建版本,建议每次构建更新该参数),该变量会在编译前生成,报错信息可忽略QAPM.setProperty(QAPM.PropertyKeySymbolId, BuildConfig.QAPM_UUID);// 设置用户ID,用于后台检索字段(必需)QAPM.setProperty(QAPM.PropertyKeyUserId, "123456");// 设置Log等级(可选),线上版本请设置成QAPM.LevelOff 或者 QAPM.LevelWarnQAPM.setProperty(QAPM.PropertyKeyLogLevel, QAPM.LevelInfo);// 设置QAPM的外网上报域名(必需)。国内站:https://app.rumt-zh.comQAPM.setProperty(QAPM.PropertyKeyHost,"https://app.rumt-zh.com");
说明:
AppKey 可参考步骤三-步骤1,在 终端性能监控 > 应用管理 > 应用设置 页面获取。
崩溃、ANR、启动、JSError 功能是全量上报,其他功能为了帮助您控制初始接入时的费用,默认采取采样上报,采样率为0.1%(千分之一)。验证过程中如果需要确保指定设备不受采样影响,可以将设置好的 userId 或者 deviceId 通过 应用管理 页面添加到白名单里;若需要整体调整指定功能在线上的采样率,请 联系我们 帮您调整,App 将会在下次启动时生效采样率变更。
多个进程需要各自初始化 QAPM。
步骤四:接入验证
1. 若打印以下日志,代表该用户未被抽样命中,需参考前面步骤将该设备添加到白名单:
参见 TAG : QAPM_manager_QAPMLauncher
2. 若打印以下日志,则代表初步接入成功,可以验证数据上报/尝试开启高级功能:
参见 TAG : QAPM_manager_QAPMPluginManager
步骤五:监控功能启用
代码如下:
// 启动QAPM
QAPM
.
beginScene
(
QAPM
.
SCENE_ALL
,
QAPM.ModeStable
)
;
接口说明如下:
public static boolean beginScene(String sceneName, int mode)//用途: 开启监控//参数: sceneName —— 场景名//参数: mode —— 开启的功能//可选项 ↓QAPM.ModeStable //--->开启稳定功能(包含卡顿、掉帧、用户行为、Crash、ANR、启动, 网络、WebView)QAPM.ModeCrash //--->开启Crash监控QAPM.ModeANR //--->开启Anr监控QAPM.ModeLaunch //--->开启启动监控QAPM.ModeLooper //--->开启卡顿监控QAPM.ModeDropFrame //--->开启掉帧监控QAPM.ModeHTTP //--->开启原生层网络监控QAPM.ModeBreadCrumb //--->开启原生层用户行为监控QAPM.ModeWebView //--->开启WebView页面加载监控QAPM.ModeJsError //--->开启WebView的JS异常监控QAPM.ModeHTTPInWeb //--->开启WebView的网络监控QAPM.ModeBreadCrumbInWeb //--->开启WebView的用户行为监控
注意:
使用或运算的方式自定义开启性能模块,如开启 Crash 和 Anr:
beginScene(“Crash&ANR”, QAPM.ModeCrash| QAPM.ModeANR)
。掉帧监控需先伴随其他功能启动,如
beginScene(“Crash&DropFrame”, QAPM.ModeCrash| QAPM.ModeDropFrame)
,之后参考 掉帧率采集 进行埋点统计。为响应工信部“26号文”要求,我们依据工信部对性能监控类 SDK 基础功能的定义,将网络监控与用户行为监控划分为
扩展业务功能
,这意味着为了避免采集网络日志信息、用户操作记录等个人信息,您可以选择性开启这两个功能。操作层面您可以在自定义性能模块开启配置中避免填入QAPM.ModeHTTP
、QAPM.ModeHTTPInWeb
两个参数,以关闭网络监控功能;以此类推,您可以在自定义性能模块开启配置中避免填入QAPM.ModeBreadCrumb
、QAPM.ModeBreadCrumbInWeb
两个参数,以关闭用户行为监控功能。public static boolean endScene(String sceneName, long mode)//用途: 结束监控(只针对掉帧采集有效)//参数: sceneName —— 需要关掉的场景名(与beginScene的要相对应)//可选项 ↓QAPM.ModeDropFrame //--->关闭掉帧监控
其他问题
说明:
通过 qapm 插件编译打包 App 时,App 需要一个 uuid 作为构建 id,如果项目目录下存在 qapm.properties 文件,并且文件里 qapm_uuid 属性的值存在,该值将被作为构建 id,否则插件会随机生成一个构建 id。
qapm-plugin 2.39及之前版本在编译 App 的过程中会报 IO 错误:java.io.FileNotFoundException,qapm.properties (No such file or directory)。
该报错仅在编译期间产生,不会影响 App 运行。