Bugly Android SDK 高级配置
更多的Bugly行为控制
我们提供了UserStrategy类作为Bugly的初始化扩展,在这里您可以修改本次初始化Bugly数据的版本、渠道及部分初始化行为。通过以下方式传入:
UserStrategy strategy = new UserStrategy(appContext);
//...在这里设置strategy的属性,在bugly初始化时传入
//...
CrashReport.initCrashReport(appContext, APPID, true, strategy);
如果通过UserStrategy设置了版本号和渠道号,则会覆盖“AndroidManifest.xml”里面配置的版本号和渠道。
用户策略(UserStrategy)
设置App版本、渠道、包名
Bugly默认读取AndroidManifest.xml文件中VersionName、Package信息。若您有自己的版本或渠道设定需求,可通过该接口修改。
strategy.setAppChannel("myChannel"); //设置渠道
strategy.setAppVersion("1.0.1"); //App的版本
strategy.setAppPackageName("com.tencent.xx"); //App的包名
设置Bugly初始化延迟
Bugly会在启动10s后联网同步数据。若您有特别需求,可以修改这个时间。
strategy.setAppReportDelay(20000); //改为20s
设置标签
自定义标签,用于标明App的某个“场景”。在发生Crash时会显示该Crash所在的“场景”,以最后设置的标签为准,标签id需大于0。例:当用户进入界面A时,打上9527的标签:
CrashReport.setUserSceneTag(context, 9527); // 上报后的Crash会显示该标签
打标签之前,需要在Bugly产品页配置中添加标签,取得标签ID后在代码中上报。
设置自定义Map参数
自定义Map参数可以保存发生Crash时的一些自定义的环境信息。在发生Crash时会随着异常信息一起上报并在页面展示。
CrashReport.putUserData(context, "userkey", "uservalue");
最多可以有9对自定义的key-value(超过则添加失败);
key限长50字节,value限长200字节,过长截断;
key必须匹配正则:[a-zA-Z[0-9]]+。
设置开发设备
在开发测试阶段,可以在初始化Bugly之前通过以下接口把调试设备设置成“开发设备”。
CrashReport.setIsDevelopmentDevice(context, true);
ADT 17增加了BuildConfig特性,可以通过获取BuildConfig类的DEBUG变量来设置:
CrashReport.setIsDevelopmentDevice(context, BuildConfig.DEBUG);
设置Crash回调
Crash回调类(CrashReport的子类)的定义如下:
public abstract static class CrashHandleCallback {
public static final int CRASHTYPE_JAVA_CRASH = 0; // Java crash
public static final int CRASHTYPE_JAVA_CATCH = 1; // Java caught exception
public static final int CRASHTYPE_NATIVE = 2; // Native crash
public static final int CRASHTYPE_U3D = 3; // Unity error
public static final int CRASHTYPE_ANR = 4; // ANR
public static final int CRASHTYPE_COCOS2DX_JS = 5; // Cocos JS error
public static final int CRASHTYPE_COCOS2DX_LUA = 6; // Cocos Lua error
/**
* Crash处理.
*
* @param crashType 错误类型:CRASHTYPE_JAVA,CRASHTYPE_NATIVE,CRASHTYPE_U3D ,CRASHTYPE_ANR
* @param errorType 错误的类型名
* @param errorMessage 错误的消息
* @param errorStack 错误的堆栈
* @return 返回额外的自定义信息上报
*/
public abstract Map onCrashHandleStart(int crashType, String errorType,
String errorMessage, String errorStack);
/**
* Crash处理.
*
* @param crashType 错误类型:CRASHTYPE_JAVA,CRASHTYPE_NATIVE,CRASHTYPE_U3D ,CRASHTYPE_ANR
* @param errorType 错误的类型名
* @param errorMessage 错误的消息
* @param errorStack 错误的堆栈
* @return byte[] 额外的2进制内容进行上报
*/
public abstract byte[] onCrashHandleStart2GetExtraDatas(int crashType, String errorType,
String errorMessage, String errorStack);
}
设置方法如下:
UserStrategy strategy = new UserStrategy(appContext);
strategy.setCrashHandleCallback(new CrashReport.CrashHandleCallback() {
public Map onCrashHandleStart(int crashType, String errorType,
String errorMessage, String errorStack) {
LinkedHashMap map = new LinkedHashMap();
map.put("Key", "Value");
return map;
}
@Override
public byte[] onCrashHandleStart2GetExtraDatas(int crashType, String errorType,
String errorMessage, String errorStack) {
try {
return "Extra data.".getBytes("UTF-8");
} catch (Exception e) {
return null;
}
}
});
CrashReport.initCrashReport(appContext, APPID, true, strategy);
两个回调返回的数据将伴随Crash一起上报到Bugly平台,并展示在附件中:
注意,需要尽量保证回调的逻辑简单和稳定,绝对不能在回调中Kill掉进程,否则会影响Crash的上报。如果需要执行类似于Crash之后Kill掉进程并重新拉起的动作,建议自定义一个Crash handler,并在初始化Bugly之前注册。
Javascript的异常捕获功能
Bugly Android SDK 1.2.8及以上版本提供了Javascript的异常捕获和上报能力,以便开发者可以感知到 WebView中发生的Javascript异常。
/**
* 设置Javascript的异常监控
*
* @param webView 指定被监控的webView
* @param autoInject 是否自动注入Bugly.js文件
* @return true 设置成功;false 设置失败
*/
CrashReport.setJavascriptMonitor(WebView webView, boolean autoInject)
“Bugly.js”文件在Bugly SDK包中,可以在HTML手动嵌入;
如果使用自动集成SDK方式,可以使用自动注入和手动注入两种方式。如果使用自动集成+手动注入的方式 需要下载“Bugly.js”文件;
由于Android 4.4以下版本存在反射漏洞,接口默认只对Android 4.4及以上版本有效;
接口不会设置webView的WebViewClient和Listener;
接口默认会开启webView的JS执行能力;
如果使用了非Android官方的WebView(例如使用X5内核),需要下载2.5.0或以上版本Bugly Android SDK并按照以下方法使用:
CrashReport.WebViewInterface webView = new CrashReport.WebViewInterface() {
/**
* 获取WebView URL.
*
* @return WebView URL
*/
@Override
public String getUrl() {
// 下面仅为例子,请用真正逻辑代替
return .getUrl();
}
/**
* 开启JavaScript.
*
* @param flag true表示开启,false表示关闭
*/
@Override
public void setJavaScriptEnabled(boolean flag) {
// 下面仅为例子,请用真正逻辑代替
WebSettings webSettings = .getSettings();
webSettings.setJavaScriptEnabled(flag);
}
/**
* 加载URL.
*
* @param url 要加载的URL
*/
@Override
public void loadUrl(String url) {
// 下面仅为例子,请用真正逻辑代替
.loadUrl();
}
/**
* 添加JavaScript接口对象.
*
* @param jsInterface JavaScript接口对象
* @param name JavaScript接口对象名称
*/
@Override
public void addJavascriptInterface(H5JavaScriptInterface jsInterface, String name) {
// 下面仅为例子,请用真正逻辑代替
.addJavascriptInterface(jsInterface, name);
}
/**
* 获取WebView的内容描述.
*
* @return WebView的内容描述.
*/
@Override
public CharSequence getContentDescription() {
// 下面仅为例子,请用真正逻辑代替
return .getContentDescription();
}
};
// 调用Bugly设置JS异常捕获接口时传入创建的WebView接口对象即可
自动注入
建议在WebChromeClient的onProgressChanged函数中调用接口:
CrashReport.setJavascriptMonitor(webView, true);
例子如下:
WebView webView = new WebView(this);
// 设置WebChromeClient
webView.setWebChromeClient(new WebChromeClient() {
@Override
public void onProgressChanged(WebView webView, int progress) {
// 增加Javascript异常监控
CrashReport.setJavascriptMonitor(webView, true);
super.onProgressChanged(webView, progress);
}
});
// 加载HTML
webView.loadUrl(url);
手动注入
下载Bugly.js文件并添加到需要监控Javascript异常的HTML中:
...
在WebView加载完该HTML后设置Javascript的异常捕获功能:
WebView webView = new WebView(this);
// 加载HTML
webView.loadUrl(url);
// 增加Javascript异常监控
CrashReport.setJavascriptMonitor(webView, false);
在Bugly Android SDK捕获到Javascript异常后,默认会上报以下信息:
Android设备的相关信息;
Javascript异常堆栈和其他信息;
Java堆栈;
WebView的信息,目前只包括ContentDescription。
更多的Bugly日志附加信息
我们提供了一些信息记录API供您补充额外的内容。这些信息会随着异常一起上报。例如App环境、用户属性等等。主要包含以下接口:
1、设置用户ID
您可能会希望能精确定位到某个用户的异常,我们提供了用户ID记录接口。
例:网游用户登录后,通过该接口记录用户ID,在页面上可以精确定位到每个用户发生Crash的情况。
CrashReport.setUserId("9527"); //该用户本次启动后的异常日志用户ID都将是9527
2、主动上报开发者Catch的异常
您可能会关注某些重要异常的Catch情况。我们提供了上报这类异常的接口。
例:统计某个重要的数据库读写问题比例。
try {
//...
} catch (Throwable thr) {
CrashReport.postCatchedException(thr); // bugly会将这个throwable上报
}
3、自定义日志功能
我们提供了自定义Log的接口,用于记录一些开发者关心的调试日志,可以更全面地反应App异常时的前后文环境。使用方式与android.util.Log一致。用户传入TAG和日志内容。该日志将在Logcat输出,并在发生异常时上报。有如下
BuglyLog.v(tag, log)
BuglyLog.d(tag, log)
BuglyLog.i(tag, log)
BuglyLog.w(tag, log)
BuglyLog.e(tag, log)
注意:
使用BuglyLog接口时,为了减少磁盘IO次数,我们会先将日志缓存在内存中。当缓存大于一定阈值(默认10K),会将它持久化至文件。您可以通过setCache(int byteSize)接口设置缓存大小,范围为0-30K。例:BuglyLog.setCache(12 * 1024) //将Cache设置为12K
如果您没有使用BuglyLog接口,且初始化Bugly时isDebug参数设置为false,该Log功能将不会有新的资源占用;
为了方便开发者调试,当初始化Bugly的isDebug参数为true时,异常日志同时还会记录Bugly本身的日志。请在App发布时将其设置为false;
上报Log最大30K。
添加额外的SO文件信息
为了更好得区分不同构建或者版本的SO文件以方便地管理Native代码,建议给SO文件加上独立的版本号或者UUID。
SO文件的版本号
在任意一个源码文件(建议是专门控制版本相关信息的源码文件)中加入一行:
extern "C" const char SO_FILE_VERSION[] __attribute__ ((section (".bugly_version"))) = ""
此后,NDK编译的SO文件将带有一个具有版本信息的段(.bugly_version)。之所以把段名 定义为“.bugly_version”,是为了Bugly的NDK解析的统一性。查看SO文件的版本号的一个方法如下(需要readelf或类似工具):
readelf -p .bugly_version libxxx.so
其中“readelf”是GNU Binary Utilities一个工具,用于解析ELF格式文件(SO文件属于ELF格式文件)。Linux下默认安装了;Windows下可使用NDK提供的readelf(\toolchains\xxx\prebuit\windowsxxx\bin\xxxreadelf.exe)或者安装MinGW或者Cygwin;Mac下如果没有该工具,可从GNU Binary Utilities官网下载安装或者使用NDK提供的readelf。
添加SO文件的UUID
在“Android.mk”文件中加上一行:
LOCAL_LDFLAGS += -Xlinker --build-id
此后,NDK构建的SO文件将带有一个段(.note.gnu.buildid)专门存放构建的UUID。查看SO文件的UUID的一个方法如下(需要readelf或类似工具):
readelf -x .note.gnu.build-id libxxx.so
Native堆栈例子如下图(UUID不在堆栈中显示):