听云Android平台SDK安装-Ant部署方式
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版本（8.0暂不支持TCP数据采集）
Android SDK通过在指定的方法中嵌码的方式来采集下列指标数据：
- 应用响应时间
- DNS解析时间
- TCP建连时间
- SSL握手时间
- 首包时间
Android SDK探针也可以采集线程堆栈、数据库、自定义参数和HTTP请求参数。
1.1 Android SDK目录结构
- nbs-newlens-android-sdk
- nbs.newlens.agent.jar
- nbs.newlens.class.rewriter.jar
1.2 Android SDK Theory
听云SDK通过虚拟机技术在应用打包编译过程中对应用采样点（Http标准协议和Https标准协议）进行嵌码操作，该操作会在协议类库方法前后部署听云SDK探针，该过程不会影响用户代码逻辑。
每当App启动时，听云Agent开始工作。应用有网络请求时，通过之前部署的听云SDK探针以一定的采集频率来采集数据，并对采集的数据进行汇总后，上传到服务器（报表展现）。
应用退出到后台或用户关闭App时，听云Agent停止工作，以便减少不必要的流量消耗。
1.3 Android SDK Theory
- 应用App嵌码后体积增量为600KB左右。
2 使用Ant构建
2.1 安装探针
注意：
1、操作员需要确保已经安装了Ant构建环境和ADT开发环境
2、如已存在build.xml请忽略本配置
在待监测的App工程根目录下执行：
android update project –p .
android命令在android sdk目录的tools子目录下，需要您设置好PATH环境变量，才可直接使用android命令行。
步骤：
1、选择探针版本 Android_SDK
2、将解压后的nbs-newlens-android.jar拷贝至嵌码项目工程的libs目录下，如未找到该目录，需新建libs目录并添加。
2.2 配置应用权限
构建完成后，请在待监测的App工程的AndroidMainfest.xml文件中增加以下的权限
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
<uses-permission android:name="android.permission.READ_PHONE_STATE"/>
<uses-permission android:name="android.permission.READ_LOGS" />
<uses-permission android:name="android.permission.INTERNET" />
<!--使用可视化操作命名功能需配置悬浮窗权限(选配)-->
<uses-permission android:name="android.permission.SYSTEM_ALERT_WINDOW"/>
2.3可视化操作命名功能配置(选配)
1、获取URL Scheme
当您在听云报表“新建App”时，您可以看到URL Scheme。
您也可以随时进入“修改配置”页面中找到您的应用对应的URL Scheme。
2、可视化操作命名需要在AndroidMainfest.xml文件的启动Actvitiy增加scheme配置。
示例如下：
"> <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、在嵌码项目工程的启动页面“MainActivity”中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请从官网获取
2.5 配置临时环境变量
注意：
请不要将临时环境变量添加到系统环境变量中，以免出现不必要的问题。
1、Mac、Linux环境下配置临时环境变量
export ANT_OPTS=”-javaagent:/path/to/nbs-android-agent/nbs.newlens.class.rewriter.jar”//path/to/nbs-android-agent/为当前SDK的绝对路径
2、Windows环境下配置临时环境变量
SETANT_OPTS=”-javaagent:C:\path\to\nbs-android-agent\nbs.newlens.class.rewriter.jar”//path/to/nbs-android-agent/ 为当前SDK的绝对路径
2.6 使用Ant命令打包编译
ant clean release install
2.7 配置混淆
1、发布前请在proguard混淆配置文件中增加以下内容，以免tingyunSDK不可用
# ProGuard configurations for NetworkBench Lens
-keep class com.networkbench.** { *; }
-dontwarn com.networkbench.**
-keepattributes Exceptions, Signature, InnerClasses
# End NetworkBench Lens
2、若需要保留行号信息，请在proguard.cfg 中添加以下内容
-keepattributes SourceFile,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”);
}
5 设置本地配置文件
5.1 新建tingyun.properties配置文件
在嵌码项目工程根目录下，新建tingyun.properties配置文件即可。
5.2 配置Crash反混淆(mapping)
听云SDK提供了两种方式进行反混淆设置。
通过报表上传mapping文件
1、报表中选择“崩溃”模块，在“崩溃历史记录列表”打开“dSYM/Mapping文件管理”。
2、找到所需版本，并上传本地mapping文件即可。
通过tingyun.properties文件自动上传mapping文件
1、添加如下配置到tingyun.properties文件
authKey=听云API账号授权Key，由报表系统生成
appKey=听云AppKey
mapping_file_auto_upload=true
2、配置Authkey授权码
4、开启混淆器
mapping_file_auto_upload=true
控制开关只有在启用混淆器的时候才会生效，开启控制开关后，听云SDK会将本地目录下的mapping文件自动上传到听云服务器。若未开启混淆器则该配置项不生效。
5.3 配置WebView控制开关
1、请将如下配置添加到tingyun.properties配置文件中
webview=true
2、采集WebView数据需调用setWebViewClient方法，如嵌码App中未调用该方法，请添加如下内容
webview.setWebViewClient(new WebViewClient(){});
3、采集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);
}
});
6 其他注意事项
6.1 编译相关
1、如项目使用MultiDex分包，安卓5.0以下设备可能会出现java.lang.NoClassDefFoundError异常。此时需将报错的类分配至主dex中。
可参考Google提供的解决方案
https://developer.android.com/studio/build/multidex.html?hl=zh-cn
6.2 数据采集相关
1、为了采集OKHttp网络数据，项目不能对OKHttp进行混淆。
以okhttp3为例，在项目的proguade-rules.pro文件中，添加-keep class okhttp3.** { *;}
-dontwarn okhttp3.**
2、采集启动数据需实现自定义的Application类
在tingyun.properties文件中配置以下内容：
applicationName=com/nbs/app/MyApp(等号“=”后替换为项目实际application的路径)
3、若AndroidMainfest.xml文件中存在非UTF-8字符（例如，注释中的中文引号“”），可能会导致听云SDK解析失败，无法对Activity嵌码，请删除AndroidMainfest.xml文件中的非UTF-8字符字符。
4.若AndroidMainfest.xml文件中注册了自定义的MyBaseActivity，请删除它，因为这是多余的，还可能会影响启动数据的采集。
如必须在清单文件中注册BaseActivity，则需要在tingyun.properties文件中添加以下内容:
// 等号“=”后替换为需要过滤听云嵌码的类的路径，如有多个路径，使用英文逗号隔开
noInstrumentedClasses=com/nbs/ui/base/MyBaseActivity