首页 帮助中心 听云App Android平台-Gradle

听云Android平台SDK安装-Gradle部署方式

1 简介

Android SDK探针支持如下数据采集:
  • Http/Https协议数据收集
  • 崩溃/ANR异常数据收集
  • 事件性能数据收集
  • 视图性能数据收集
  • 进程内存和CPU使用率
Android SDK探针支持如下协议类库:
  • HttpURLConnection
  • Android HttpClient4.0
  • Apache HttpClient (>4.0)
  • Volley+OkHttpClient
  • OkHttp(>2.4.0)
  • Retrofit
  • WebView(原生)
Android SDK探针支持如下系统版本:
  • Android 4.0版本~Android8.0版本
用户体验分析采集应用启动及用户操作数据。
  • 应用启动数据采集需实现自定义的Application类。
  • 启动耗时
  • 启动次数
  • 启动期间的崩溃、事件性能数据
用户操作数据采集点击事件(onClick、onItemClick、ItemSelected、PageSelected等方法)。
  • 操作耗时
  • 阻塞耗时
  • 操作次数
  • 操作期间的崩溃、事件性能数据
Android SDK采集应用运行时发生的异常。
  • 崩溃
  • 自定义异常上传
Android SDK采集应用运行时发生的ANR。
  • ANR
  • 卡顿
Android SDK采集应用的网络数据。
  • 应用响应时间
  • DNS解析时间
  • TCP建连时间
  • SSL握手时间
  • 首包时间
  • 剩余包时间
  • 访问量
Android SDK探针也可以采集线程堆栈、数据库、自定义参数和HTTP请求参数。

1.1 Android SDK Theory

听云SDK通过虚拟机技术在应用打包编译过程中对应用采样点(Http标准协议和Https标准协议)进行嵌码操作,该操作会在协议类库方法前后部署听云SDK探针,该过程不会影响用户代码逻辑。
每当App启动时,听云Agent开始工作。应用有网络请求时,通过之前部署的听云SDK探针以一定的采集频率来采集数据,并对采集的数据进行汇总后,上传到服务器(报表展现)。
应用退出到后台或用户关闭App时,听云Agent停止工作,以便减少不必要的流量消耗。

1.2 Android SDK Theory

  • 应用App嵌码后体积增量为370KB左右。

1.3 Android SDK兼容性问题

  • 导致阿里Sophix补丁工具生成补丁失败,详见FAQ。

2 使用Gradle构建

2.1 工程相关依赖构建

注意:
需要确保已经安装了Gradle构建环境和AS开发环境 

1、打开项目根目录下的build.gradle(Project)文件

2、在repositories中引入听云仓库

maven { url "http://nexus2.tingyun.com/nexus/content/repositories/snapshots/" }

3、在dependencies中加入代码


Android_SDK版本列表

classpath 'com.networkbench.newlens.agent.android:agent-gradle-plugin:TingYun_Version'
//TingYun_Version为当前听云APP版本号

4、在allprojects的repositories中引入听云仓库

maven { url "http://nexus2.tingyun.com/nexus/content/repositories/snapshots/" }

5、打开app下的build.gradle文件

6、在dependencies模块中添加代码

compile "com.networkbench.newlens.agent.android:nbs.newlens.agent:TingYun_Version" 
// TingYun_Version为当前听云APP版本号

7、添加听云符号表插件

apply plugin:'newlens'

2.2 配置应用权限

  构建完成后,请在待监测的App工程的AndroidMainfest.xml文件中增加以下的权限

<uses-permissionandroid:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permissionandroid:name="android.permission.ACCESS_WIFI_STATE" />
<uses-permission android:name="android.permission.READ_PHONE_STATE"/>
<uses-permissionandroid:name="android.permission.READ_LOGS" />
<uses-permissionandroid:name="android.permission.INTERNET" />
<!--使用可视化操作命名功能需配置悬浮窗权限(选配)-->
<uses-permission android:name="android.permission.SYSTEM_ALERT_WINDOW"/>
<uses-permission android:name="android.permission.SYSTEM_OVERLAY_WINDOW" />

2.3可视化操作命名功能配置

1、获取URL Scheme
当您在听云报表“新建App”时,您可以看到URL Scheme。

您也可以随时进入“修改配置”页面中找到您的应用对应的URL Scheme。

2、可视化操作命名需要在AndroidMainfest.xml文件的启动Actvitiy增加scheme配置。
示例如下:

<activity android:name=".MainActivity">
            <intent-filter>
                <action android:name="android.intent.action.MAIN" />
                <category android:name="android.intent.category.LAUNCHER" />
            </intent-filter>
  <!--请添加这里的整个intent-filter区块,并确保其中只有一个data字段-->
            <intent-filter>
                <data android:scheme="tingyun.xxxx" />
<!--请将scheme中的“tingyun.xxxx”替换为您应用的URL Scheme-->
                <action android:name="android.intent.action.VIEW"/>
                <category android:name="android.intent.category.DEFAULT"/>
                <category android:name="android.intent.category.BROWSABLE"/>
            </intent-filter>
  <!--请添加这里的整个intent-filter区块,并确保其中只有一个data字段-->
 </activity>

3、设置控件ID
听云SDK会采集用户操作的控件ID,建议您在Layout文件中添加控件ID。对于动态生成的控件,可以使用 setViewId() 方法对它设置唯一的ID。

示例如下:
public void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.main);
    LinearLayout layout = findViewById(R.id.layout);
    final Button button = new Button(this);
    button.setLayoutParams(new ViewGroup.LayoutParams(ViewGroup.LayoutParams.WRAP_CONTENT, ViewGroup.LayoutParams.WRAP_CONTENT));
    button.setText("Login");
    //viewId最多包含32个字符,支持英文、数字、下划线
    NBSAgent.setViewId(button, "bt_login");
}

2.4 插入初始化探针代码

1、在嵌码项目工程的启动页面“Application”中import NBSAppAgent类

import com.networkbench.agent.impl.NBSAppAgent;

2、在“Application”中的onCreate()方法(如未找到该方法请新增onCreate())中初始化Android SDK

NBSAppAgent.setLicenseKey("AppKey").withLocationServiceEnabled(true).startInApplication(this.getApplicationContext());
//Appkey请从官网获取
注意:

SDK默认采集所有进程的数据,若只想采集主进程数据,请添加对应方法

NBSAppAgent.setLicenseKey("AppKey").withOnlyMainProcEnabled(true).start(this.getApplicationContext());
//Appkey请从官网获取

3、采集WebView数据需调用setWebViewClient方法,如嵌码App中未调用该方法,请添加如下内容

webview.setWebViewClient(new WebViewClient(){});

4、采集WebView数据需在WebChromeClient的onProgressChanged函数中调用接口:

NBSWebChromeClient.initJSMonitor(view, newProgress);例子如下:
webview.setWebChromeClient(new WebChromeClient(){
	@Override
        public void onProgressChanged(WebView view, int newProgress) {
        	NBSWebChromeClient.initJSMonitor(view, newProgress);
            super.onProgressChanged(view, newProgress);
        }
});

2.5 使用Gradle命令打包编译

gradle clean build

2.6 配置混淆

1、发布前请在proguard混淆配置文件中增加以下内容,以免tingyunSDK不可用

# ProGuard configurationsfor NetworkBench Lens
-keep classcom.networkbench.** { *; }
-dontwarncom.networkbench.**
-keepattributesExceptions, Signature, InnerClasses
# End NetworkBench Lens

2、若需要保留行号信息,请在proguard.cfg 中添加以下内容

-keepattributesSourceFile,LineNumberTable

3 嵌码验证

1、数据收集服务器校验

2、嵌码完成后可通过“LogCat”查看听云SDK日志输出结果,用以进行数据收集服务器校验TAG为NBSAgent,标准日志输出结果如下所示:

NBSAgent start
NBSAgent enabled
NBSAgent V “TingYun_Version” //TingYun_Version 为当前SDK的版本号
connect success

3、数据功能完整性校验

嵌码完成后可通过“LogCat”查看听云SDK日志输出结果,用以进行数据功能完整性校验TAG为TingYun,标准日志输出结果如下所示:

D/TingYun: Crash switch is true
D/TingYun: webView switch is true
D/TingYun: ANR monitor switch is true
D/TingYun: UserAction Switch  is true
D/TingYun: cdnSwitch Switch  is true

4 高级功能

4.1 用户自定义ID

1、功能说明

用户自定义ID为当前用户设置唯一标示码,在任意位置均可设置UserID。

2、相关接口

//UserID最多包含64个字符,支持中文、英文、数字、下划线,但不能包含空格或其他的转义字符
NBSAppAgent.setUserIdentifier("userIdentifier");

3、代码示例

public class MainActivity extends Activity {
    public void onCreate(BundlesavedInstanceState) {
        super.onCreate(savedInstanceState);
        String userIdentifier =getUserID();
        NBSAppAgent.setLicenseKey("AppKey").withLocationServiceEnabled(true).start(this.getApplicationContext());
        NBSAppAgent.setUserIdentifier(userIdentifier);
      }
}

4.2 面包屑

1、功能说明

面包屑能够更好的协助用户调查崩溃发生的原因,可以知晓用户发生崩溃之前的代码逻辑与崩溃轨迹结合使用能够更好的复现用户崩溃场景。

2、相关接口

//最多包含100个字符,支持中文、英文、数字、下划线 
NBSAppAgent.leaveBreadcrumb("keyPressed”);
NBSAppAgent.leaveBreadcrumb("loginDone");

3、代码示例

public MyActivity extends Activity {
         publicvoid onCreate(Bundle savedInstanceState) {
            super.onCreate(savedInstanceState);          
            NBSAppAgent.setLicenseKey("AppKey").withLocationServiceEnabled(true).start(this.getApplicationContext());
            NBSAppAgent.leaveBreadcrumb("login MyActivityonCreate");
         }
         publicvoid onResume() {
            super.onResume();
            NBSAppAgent.leaveBreadcrumb("login MyActivityonResume");
         }
         publicvoid logginPressed(View view) {
             NBSAppAgent.leaveBreadcrumb("login MyActivitylogginPressed");
             new LoginAsyncTask.execute();
         }
         publicvoid onStop() {
             super.onStop();
             NBSAppAgent.leaveBreadcrumb("login MyActivityonStop");
         }
}

4.3 自定义Event

1、功能说明

自定义事件用于统计App中的任意事件,开发者可以在SDK初始化后的任意位置添加自定义事件,并设置对应上传参数。如:真实用户操作时候点击某个功能按钮或触发了某个功能事件等。

2、相关接口

//EVENT_ID最多包含32个字符,支持中文、英文、数字、下划线,但不能包含空格或其他的转义字符
NBSAppAgent.onEvent(String EVENT_ID);

3、代码示例

@Override
public void onClick(View v) {
    …………
        NBSAppAgent.onEvent("添加购物车");
      …………
}

4.4 自定义Trace

注意:

由于自定义Trace是成对出现的,请勿跨方法、跨进程以及在异步加载和递归调用中使用该接口。

1、功能说明

听云SDK默认采集系统类和方法的性能数据,无法采集开发者自定义类和方法的性能数据。使用“自定义Trace”接口就可以帮助开发者时刻了解所写代码的健壮性及其性能数据。如:开发者想要了解某个自定义方法的初始化耗时及性能消耗情况,就可以在该自定义方法前后添加“自定义Trace”接口即可。

2、相关接口

//Name 为当前方法所在方法名或自定义名称,支持中文、英文、数字、下划线,但不能包含空格或其他的转义字符
NBSAppAgent.beginTracer("String Name");
NBSAppAgent.endTracer("String Name");

3、代码示例

//用户可以在SDK初始化后的任意方法前后添加自定义Trace
public void onCreate(Bundle savedInstanceState) {
      super.onCreate(savedInstanceState);
      setContentView(R.layout.main);
      init();
     }
private void init() {
     //方法开始前添加beginTracer
     NBSAppAgent.beginTracer(“这是Init方法”); 
        try {
            ………
        } catch(NameNotFoundException e) {
           e.printStackTrace();
        }
     //方法结束后添加endTracer
     NBSAppAgent.endTracer(“这是Init方法”);
}

4.5 自定义Log

注意:

收集LogCat信息,需要使用READ_LOGS权限,请将下列代码添加到应用程序的AndroidManifest.xml文件中,默认收集50行,最多收集100行日志。

< uses-permissionandroid:name="android.permission.READ_LOGS" >

1、功能说明

  开发者可通过Android日志系统的LogCat,来收集和查看系统调试输出的信息,通过打印输出的Log信息来调查Bug发生时的应用程序信息,并通过听云SDK上传自定义Log日志。

2、控制开关

NBSAppAgent.setLicenseKey("AppKey").withLocationServiceEnabled(true).
enableLogging(true).start(this.getApplicationContext());

3、相关接口

NBSAppAgent.setLogging(int lineNumber);
NBSAppAgent.setLogging(String filter);
NBSAppAgent.setLogging(int lineNumber,String filter);

4、代码示例

public void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
     setContentView(R.layout.main);
      // Enablelogging
      NBSAppAgent.setLicenseKey("AppKey").withLocationServiceEnabled(true).enableLogging(true).start(this.getApplicationContext());
      // Log last 100messages
      NBSAppAgent.setLogging(100);
}

4.6 自定义附加信息

1、功能说明

  用户可以在初始化之后任意位置配置该接口,最多可添加10条附加信息,每条附加信息最大支持100个字节随崩溃上传。

2、相关接口

NBSAppAgent.setUserCrashMessage(String key,Stringvalue);

3、代码示例

public void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
     setContentView(R.layout.main);        
     NBSAppAgent.setLicenseKey("AppKey").withLocationServiceEnabled(true).start(this.getApplicationContext());
     //初始化后的任意位置插入自定义附加信息
     NBSAppAgent.setUserCrashMessage(“张三”,“13700001234”);
}

4.7 控制台版本提示

1、功能说明

用户调试时会在控制台输出版本更新提示,当开启调试模式且当前使用SDK版本低于线上最新版本时,App运行后打印输出。

注:项目工程只有debug模式才会开启此功能。
可通过在AndroidMainfest.xml文件中的application标签添加debuggable属性控制是否开启调试模式。 
<application android:debuggable="true">

2、相关接口
默认开启,若无需提示,可关闭控制台提示功能。

NBSAppAgent.closeLogForUpdateHint();

3、代码示例

public void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
     setContentView(R.layout.main);
     NBSAppAgent.setLicenseKey("AppKey").withLocationServiceEnabled(true). closeLogForUpdateHint().start(this.getApplicationContext());
     //初始化时调用接口关闭版本提示功能
}

5 设置本地配置文件

5.1 新建tingyun.properties配置文件

  在嵌码项目工程根目录下,新建tingyun.properties配置文件即可。

5.2 配置Crash反混淆(mapping)

  听云SDK提供了两种方式进行反混淆设置。

通过报表上传mapping文件

1、报表中选择“崩溃”模块,在“崩溃历史记录列表”打开“dSYM/Mapping文件管理”。

2、找到所需版本,并上传本地mapping文件即可。

通过tingyun.properties文件自动上传mapping文件

1、添加如下配置到tingyun.properties文件

shell
authKey=听云API账号授权Key,由报表系统生成
appKey=听云AppKey
mapping_file_auto_upload=true

2、配置Authkey授权码

4、开启混淆器

mapping_file_auto_upload=true

控制开关只有在启用混淆器的时候才会生效,开启控制开关后,听云SDK会将本地目录下的mapping文件自动上传到听云服务器。若未开启混淆器则该配置项不生效。

6 FAQ

1、应用启动数据未采集或缺失生命周期方法

1.检查AndroidMainfest.xml文件中存在非UTF-8字符(例如,注释中的中文引号“”),如存在需删除。
2.若AndroidMainfest.xml文件中注册了自定义的MyBaseActivity,请删除它,或对其配置过滤嵌码。
需要在tingyun.properties文件中添加以下内容:
#等号“=”后替换为需要过滤听云嵌码的类的路径,如有多个路径,使用英文逗号隔开
noInstrumentedClasses=com/nbs/ui/base/MyBaseActivity
3.应用需实现自定义的Application类
4.听云SDK初始化较晚(如在启动Activity的onResume()方法中初始化),未能及时获取到Activity生命周期方法的回调
5.ant或eclipse编译,需在tingyun.properties文件中配置以下内容:
#等号“=”后替换为需要过滤听云嵌码的类的路径,如有多个路径,使用英文逗号隔开applicationName=com/nbs/app/MyApp

2、用户操作数据采集少

听云SDK编译时对点击事件(如onClick、onItemClick、ItemSelected、PageSelected等方法)嵌码,仅支持点击数据采集
暂不支持触摸、长按、滑动等操作。

3、未采集到崩溃或采集的崩溃数量偏少

1.听云SDK只采集java层崩溃,不支持Native层异常采集。
2.听云SDK初始化前的崩溃无法采集。
3.检查报表的崩溃采集开关是否开启。
4.若应用中存在应用自身异常捕获或第三方崩溃采集逻辑,需放在听云SDK之前初始化。

4、OKHttp网络数据未采集

不能对OKHttp混淆。在项目的proguade-rules.pro文件中,添加
#OKHttp3配置
-keep class okhttp3.** { *;}
-dontwarn okhttp3.**
#OKHttp2配置
-keep class com.squareup.okhttp.**

5、TCP、首包数据为0

1.听云SDK需在应用自身网络请求发起之前初始化
2.暂不支持安卓9.0TCP数据采集。
3.使用Http代理时无法获取TCP数据。
4.WebView跨域资源响应头未配置Timing-Allow-Origin: *

6、 WebView数据未采集或只采集到了网络错误、Http错误

1.未在WebChromeClient的onProgressChanged方法中调用NBSWebChromeClient.initJSMonitor(view, newProgress);
2.不支持腾讯X5框架
3.不支持SPA单页面应用数据采集。
4.不支持使用loadDataWithBaseURL加载html代码

7、URL过滤、错误过滤未生效

1.检查报表上配置是否正确,可以通过在线正则工具检查,需注意报表配置正则的前后需要加斜杠“/”。
2.过滤配置是SDK连接听云服务器成功后下发的,再此之前的网络数据无法过滤。

8、如项目使用MultiDex分包,安卓5.0以下设备可能会出现java.lang.NoClassDefFoundError异常

需将报错的类分配至主dex中,可参考Google提供的解决方案
https://developer.android.com/studio/build/multidex.html?hl=zh-cn

9、Sophix补丁工具生成补丁失败

听云SDK为了采集应用启动数据,会在编译时对Application类的attachBaseContext()及onCreate()方法嵌码。
而阿里Hotfix补丁工具自3.2.1版本开始,要求在initialize之前,不能调用非Android官方API类,导致生成补丁失败。

10、编译时出现java.util.zip.ZipEexeption异常

SDK jar包重复引用,检查libs目录及build.gradle文件,确保只有一份nbs.newlens.agent.jar引用。

11、项目使用Lambda时编译失败

将听云插件放在lambda后面
apply plugin: 'me.tatarka.retrolambda'
apply plugin: 'newlens'