You need to enable JavaScript to run this app.
导航

应用接入Android SDK

最近更新时间2024.03.04 10:17:01

首次发布时间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无需下载,根据以下初始化配置说明接入即可。

  1. 在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/"
            }
        }
    }
    
  2. 接入应用性能监控全链路版。

    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.4.cn-rc.1'
      implementation 'com.volcengine:apm_insight_crash:1.5.0'
      

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

说明

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

崩溃相关功能

  1. 在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?
  2. 启动崩溃监控,开始收集数据。

    注意

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

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

性能相关功能

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

    注意

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

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

    注意

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

    //在同意隐私合规后调用
    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泄露的回调
    //   }
    //});
    
    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());
    
  3. 在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符号表管理

自动上传

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

    classpath "com.volcengine:apmplus_upload_plugin:0.0.1"
    
  2. 在应用工程的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,请删除这行代码。

相关文档

  • 应用接入Android SDK后,如果需要验证各模块的数据上报,请参见验证数据上报
  • 应用接入Android SDK后,如果需要使用SDK扩展能力,请参见使用高阶功能