文档中心

应用性能监控全链路版

Android SDK 接入

应用接入Android SDK

本文介绍Android SDK的详细接入步骤。接入SDK后，验证数据上报成功，即可在应用性能监控全链路版平台上使用相关分析功能。

注意事项

Android SDK有中国和海外两个版本，功能相同上报地址不同。

中国发布的应用：使用cn版本，上报到中国国内。

海外发布的应用：使用oversea版本，上报到马来西亚柔佛。

调用SDK初始化接口不会采集用户信息，调用SDK启动接口会开始采集用户信息，请确保采集用户信息之前已经获得用户授权SDK隐私政策。

Demo说明

APMPlus_Android

Demo已经接入了所有ApmPlus的性能和稳定性监控的能力。

您可以通过Demo模拟一些异常和性能数据。

您可以配置成自己的Appid，将数据上报到平台，进行SDK功能测试。

步骤一：获取SDK包，引入依赖

应用性能监控全链路版的Android SDK无需下载，根据以下初始化配置说明接入即可。

在project级别的build.gradle文件中，添加maven地址。

buildscript {
repositories {
maven {
url "https://artifact.bytedance.com/repository/Volcengine/"
}
maven {
url "https://artifact.bytedance.com/repository/byteX/"
}
}
}
allprojects {
repositories {
maven {
url "https://artifact.bytedance.com/repository/Volcengine/"
}
}
}

接入应用性能监控全链路版。

在project级别的build.gradle文件的dependencies中，添加以下代码，接入插件组件辅助插桩。apm_insight_plugin 国内海外使用同一个版本。

classpath "com.volcengine:apm_insight_plugin:1.4.2"

在app module的build.gradle文件的dependencies中，添加以下代码，根据国内应用还是海外应用选择下面两个版本的一个。

国内应用接入cn版本，上报到中国，使用如下依赖：

// 国内应用在dependencies中添加
implementation 'com.volcengine:apm_insight:1.5.25.cn'
implementation 'com.volcengine:apm_insight_crash:1.5.21'

海外应用接入oversea版本，上报到马来西亚柔佛，使用如下依赖：

// 海外应用在dependencies中添加
implementation 'com.volcengine:apm_insight:1.5.24.oversea'
implementation 'com.volcengine:apm_insight_crash:1.5.21.oversea'

步骤二：初始化SDK并开启监控

说明

初始化SDK阶段，不获取用户个人信息。

崩溃相关功能

在Application中onCreate中，添加以下代码，初始化崩溃相关功能。

MonitorCrash.Config config = MonitorCrash.Config.app({{AppId}})
.token({{AppToken}})// 设置鉴权token，可从平台应用信息处获取，token错误无法上报数据
// .versionCode(1)// 可选，默认取PackageInfo中的versionCode
// .versionName("1.0")// 可选，默认取PackageInfo中的versionName
// .channel("google play")// 可选，设置App的下载渠道，可以在平台进行筛选。例如，谷歌应用商店渠道可以设置“google play”。
// .url("www.xxx.com")// 默认不需要，私有化部署才配置上报地址
//可选，可以设置自定义did，不设置会使用内部默认的
// .dynamicParams(new MonitorCrash.Config.IDynamicParams() {
// @Override
// public String getDid() {//返回空会使用内部默认的did。
// return null;
// }
//
// @Override
// public String getUserId() {//可选。用户的唯一标识，支持用户自定义UserId把平台数据和自己用户关联起来。内部每次使用会回调getUserId()函数，返回可以定义为变量，用户登录有UserId时对变量进行赋值。
// return null;
// }
// })
//可选，添加业务自定义数据，在崩溃详情页->现场数据展示
// .customData(crashType -> {
// HashMap<String, String> map = new HashMap<>();
// map.put("app_custom", "app_value");
// return map;
// })
.exitType(ExitType.EXCEPTION) // 可选，上报应用退出原因，EXCEPTION会过滤USER_REQUEST类型
.enableApmPlusLog(true) // 可选，是否将崩溃信息等写入APMPlus日志，默认值为false
// .crashProtect(true) //可选，是否开启崩溃防护，默认值为false
// .enableOptimizer(true) //可选，是否开启崩溃优化方案，默认值为false
.autoStart(false) // 可选，是否在初始化时自动开启监控，默认值为true（不调用该方法初始化时自动开启监控）
// .debugMode(true) // 可选，线下使用的日志开关，线上不要调用或设置为false
// 可选，添加pv事件的自定义tag，可以用来筛选崩溃率计算的分母数据
//.pageViewTags(<<Map<String, String>>>)
.build();
MonitorCrash monitorCrash = MonitorCrash.init(ApplicationContext, config);

说明

Context建议传递ApplicationContext。

参数都不能为null，否则初始化会失败。

versionInt为数字版本号，例如100；versionString为字符版本号，例如"1.0.0"。

初始化返回的MonitorCrash实例为后续配置的入口。

避免重复调用初始化方法，并对init返回对象做空指针判断。

aid可以在平台项目浏览器的URL上面获取。

AppID和AppToken获取方法，请参见如何查询AppID和AppToken？。

启动崩溃监控，开始收集数据。

注意

请在用户同意隐私政策后，再调用方法收集数据。

// 启动监控，当初始化时autoStart传入false设置为初始化时不自动开启监控，需要在合适的位置调用start方法开启监控；如果初始化时未设置autoStart参数或者设置为true，将自动开启监控，不需要调用start方法。
if (monitorCrash != null) {
monitorCrash.start();
}

性能相关功能

在Application中onCreate中，添加以下代码，初始化性能相关功能。

注意

请在主线程中添加初始化性能相关功能的代码。

//必须放到Application的onCreate里面，会注册监听生命周期，不涉及数据采集和隐私合规问题
ApmInsight.getInstance().init(application);
//初始化自定日志，配置自定义日志最大占用磁盘，内部一般配置20，代表最大20M磁盘占用。1.4.1版本开始存在这个api
VLog.init(this,20);

启动性能监控，开始收集数据。

注意

请在用户同意隐私政策后，再调用方法收集数据。

//在同意隐私合规后调用
ApmInsightInitConfig.Builder builder = ApmInsightInitConfig.builder();
//设置分配的appid
builder.aid({{app_id}});
//设置分配的AppToken
builder.token({{AppToken}});
//是否开启卡顿功能
builder.blockDetect(true);
//是否开启严重卡顿功能
builder.seriousBlockDetect(true);
//是否开启流畅性和丢帧
builder.fpsMonitor(true);
//控制是否打开WebView监控
builder.enableHybridMonitor(true);
//控制是否打开内存监控
builder.memoryMonitor(true);
//控制是否打开电量监控
builder.batteryMonitor(true);
//控制是否打开CPU监控
builder.cpuMonitor(true);
//控制是否打开磁盘监控
builder.diskMonitor(true);
//控制是否打开流量监控
builder.trafficMonitor(true);
//控制是否打开用户使用时长的监控
builder.operateMonitor(true);
//控制是否打开启动监控，开启需要同时配置apm-plugin插件
builder.startMonitor(true);
//控制是否打开页面Activity耗时监控，开启需要同时配置apm-plugin插件
builder.pageMonitor(true);
//控制是否打开网络监控，开启需要同时配置apm-plugin插件
builder.netMonitor(true);
//是否打印日志，注：线上release版本要配置为false
builder.debugMode(true);
//默认不需要，私有化部署才需要配置数据上报的域名（内部有默认域名，测试支持设置http://www.xxx.com 默认是https协议
//builder.defaultReportDomain("www.xxx.com");
//设置渠道。1.3.16版本增加接口

//开启泄露和泄露兜底检测能力，泄露检测和泄露兜底需要分别在平台配置采样
//builder.detectActivityLeak(new IActivityLeakListener() {
// @Override
// public void onActivityLeaked(Activity activity) {
// //activity泄露的回调
// }
//});

// 可选，设置App的下载渠道，可以在平台进行筛选。例如，谷歌应用商店渠道可以设置“google play”。
builder.channel("google play");
//打开自定义日志回捞能力。1.4.1版本新增接口
builder.enableLogRecovery(true);
//打开APMPlus日志能力，可以通过回捞获取APMPlus日志
builder.enableAPMPlusLocalLog(true);
//设置数据和Rangers Applog数据打通，设备标识did必填。1.3.16版本增加接口
builder.setDynamicParams(new IDynamicParams() {
@Override
public String getUserUniqueID() {
//可选。依赖AppLog可以通过AppLog.getUserUniqueID()获取，否则可以返回null。
return null;
}

@Override
public String getAbSdkVersion() {
//可选。如果依赖AppLog可以通过AppLog.getAbSdkVersion()获取，否则可以返回null。getAbSdkVersion是回调类的参数可以初始化后再设置。
return null;
}

@Override
public String getSsid() {
//可选。依赖AppLog可以通过AppLog.getSsid()获取，否则可以返回null。getSsid是回调类的参数可以初始化后再设置。
return null;
}

@Override
public String getDid() {
//1.4.0版本及以上可选，其他版本必填。设备的唯一标识，如果依赖AppLog可以通过 AppLog.getDid() 获取，也可以自己生成。getDid是回调类的参数可以初始化后再设置。
return null;
}

@Override
public String getUserId() {
//可选。用户的唯一标识，支持用户自定义user_id把平台数据和自己用户关联起来。内部每次使用会回调getUserId()函数，返回可以定义为变量，用户登录有UserId时对变量进行赋值。
return "userid";
}

});

ApmInsight.getInstance().start(builder.build());

在app module的build.gradle文件最外层，添加以下代码，完成插桩。

插桩是为了简化接入网络监控、启动监控和页面监控，和其他监控能力无关。当前支持最高AGP版本7.0.2，编译异常相关解决方案见文档Apmplus plugin编译异常。编译出现冲突和异常也可以直接使用非插桩方式接入，具体请参见如何根据非插桩方案接入监控能力？。

//在文件头添加
apply plugin: 'apm-plugin'

ApmPlugin {
// 是否进行插桩
enable true
// 是否在Debug包插桩，默认不插桩
enableInDebug true
// DEBUG("DEBUG"), INFO("INFO"), WARN("WARN"), ERROR("ERROR");
// DEBUG 级别Log会汇总所有被插桩处理的类供查看，路径 app/build/ByteX/ApmPlugin/ApmPlugin_log.txt
logLevel "DEBUG"
// 启动分析开关：监控App启动耗时，需要同时开启pageLoadSwitch
startSwitch = true
// 页面响应开关：监控Activity的生命周期耗时
pageLoadSwitch = true
// 网络监控开关：监控okhttp3的网络请求
okHttp3Switch = true
//插桩显示HttpUrlConnection的网络请求开关
httpUrlConnectionSwitch = true
// 重要：白名单下的包进行插桩，需要填写要插桩类所在的包名，支持前缀配置，默认可以写com
whiteList = [
"com"
]
// 黑名单包下类不进行插桩，可以配置包名和类名，没有可以不填
blackList = [
]
}

WebView页面监控

WebView初始化一般在某个Activity或者某个Fragment内，添加以下代码，将待监控的Webview进行封装。上报数据会在新H5监控模块展示。

可选配置

如果因为隐私合规需要关闭一些数据的采集，请在初始化SDK前，修改如下配置。

通过平台的SDK上报配置配置开关可以控制是否开启相关能力和数据采集上报，例如可以通过磁盘监控和内存优化等开关和采样控制磁盘和内存数据的采集上报。

权限说明：如下权限是可选权限，默认不需要业务特殊处理。

步骤三：上传符号表

符号表可以解析崩溃堆栈的内容，将日志里的堆栈信息由原始堆栈转化成经过符号化之后的解析堆栈。符号表主要支持手动上传和自动上传两种方式。

说明

您也可以选择通过自定义脚本等方式上传符号表，详情请参见如何自定义上传符号表。

手动上传

手动上传在符号表管理页面进行操作。详情请参见Android符号表管理。

自动上传

在project级别的build.gradle文件的dependencies中，添加以下代码，接入插件组件。

classpath "com.volcengine:apmplus_upload_plugin:0.0.14"

在应用工程的build.gradle中，添加以下代码，配置自动上传符号表。

apply plugin: 'apmplus-upload-plugin'
ApmPlusUploadConfig {
api_token = "" // 从平台的全部功能->符号表管理->系统选择 Android->下面可以看到api key和api token。或者联系开发同学获取到的对应appId的一个token，私有化部署不用设置
api_key = 0 // 从平台的全部功能->符号表管理->系统选择 Android->下面可以看到api key和api token。或者联系开发同学获取到的对应appId的一个key，私有化部署不用设置
aid = 12345 // 应用性能监控全链路版上的appid
// oversea = true // 海外域名版本符号表上传时设置为true，使用国内平台不需要填写或者设置为false
// updateVersionCode = -1 // 默认不用写这一行，除非您在初始化的时候手动指定了非标准版本号（或SDK版本号）; 此处一定要与初始化的版本号一致
// mappingUrl = "https://www.xxx.com" // 默认不用写这一行，如果是私有化，这里配置私有化平台域名
}

注意

接入SDK时，updateVersionCode字段的值必须与初始化APMPlus传入的值一致。

接入App时，不需要配置updateVersionCode，请删除这行代码。