文档中心

应用接入Android SDK

最近更新时间：2023.11.30 14:53:05

首次发布时间：2021.06.15 18:04:50

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

注意事项

Android SDK目前仅限在中国大陆应用使用（不包括港澳台地区）。
调用SDK初始化接口不会采集用户信息，调用SDK启动接口会开始采集用户信息，请确保采集用户信息之前已经获得用户授权SDK隐私政策。

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

// 关闭设备OAID的采集
AppLog.setOAIdEnabled(false);
// 关闭设备GAID的采集
AppLog.setGAIdEnabled(false);

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/"
        }
    }
}

接入应用性能监控全链路版。
1. 在project级别的build.gradle文件的dependencies中，添加以下代码，接入插件组件。
```
classpath "com.volcengine:apm_insight_plugin:1.4.2"
```
2. 在app module的build.gradle文件的dependencies中，添加以下代码，完成插桩。
  插桩是为了辅助收集启动耗时、页面加载、网络监控的数据，这部分只适用于接入App进行监控的用户，不适用接入SDK进行监控的用户。
```
//在文件头添加
apply plugin: 'apm-plugin'
// 在dependencies中添加
implementation 'com.volcengine:apm_insight:1.5.2.cn'
implementation 'com.volcengine:apm_insight_crash:1.4.9'
```

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

崩溃相关功能

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

MonitorCrash.Config config = MonitorCrash.Config.app({{AppId}})
                .token({{AppToken}})// 设置鉴权token，可从平台应用信息处获取，token错误无法上报数据
//              .versionCode(1)// 可选，默认取PackageInfo中的versionCode
//              .versionName("1.0")// 可选，默认取PackageInfo中的versionName
//              .channel("test")// 可选，设置App发布渠道，在平台可以筛选
//              .url("www.xxx.com")// 默认不需要，私有化部署才配置上报地址
                //可选，可以设置自定义did，不设置会使用内部默认的
//              .dynamicParams(new MonitorCrash.Config.IDynamicParams() {
//                  @Override
//                  public String getDid() {//返回空会使用内部默认的did
//                      return null;
//                  }
//
//                  @Override
//                  public String getUserId() {
//                      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.enableWebViewMonitor(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.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是回调类的参数可以初始化后再设置。
         return "userid";
    }
    
});

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

在app module的build.gradle文件最外层，添加以下代码，完成插桩。
启动分析和页面体验相关功能依赖插件插桩，需配置ApmPlugin的whiteList为自己的包名，配置后该目录下的代码会被插桩。

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
    // 白名单下的包进行插桩，需要填写要插桩类所在的包名，支持前缀配置
    whiteList = [
            "com"
    ]
    // 黑名单包下类不进行插桩，可以配置包名和类名，没有可以填空
    blackList = [
            "com.xxx"
    ]
}

WebView页面监控

WebView初始化一般在某个Activity或者某个Fragment内，添加以下代码，将待监控的Webview进行封装。

//设置webView的WebChromeClient如下或者继承WebViewMonitorWebChromeClient
webView.setWebChromeClient( new WebViewMonitorWebChromeClient());
//设置webView的WebViewClient如下或者继承WebViewMonitorWebViewClient
webView.setWebViewClient(new WebViewMonitorWebViewClient());
//WebView加载url时候需要调用如下函数
WebViewMonitorHelper.getInstance().onLoadUrl(webView, url);
webView.loadUrl(url);

步骤三：上传符号表

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

手动上传

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

自动上传

在project级别的build.gradle文件的dependencies中，添加以下代码，接入插件组件。
```
classpath "com.volcengine:apmplus_upload_plugin:0.0.1"
```

在应用工程的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
 //       updateVersionCode = -1 // 默认不用写这一行， 除非您在初始化的时候手动指定了非标准版本号（或SDK版本号）; 此处一定要与初始化的版本号一致
//       mappingUrl = "https://www.xxx.com" // 默认不用写这一行，如果是私有化，这里配置私有化平台域名
}

注意

接入SDK时，updateVersionCode字段的值必须与初始化APMPlus传入的值一致。
接入App时，不需要配置updateVersionCode，请删除这行代码。

应用性能监控全链路版