Bugly Android SDK 高级配置

更多的Bugly行为控制

我们提供了UserStrategy类作为Bugly的初始化扩展,在这里您可以修改本次初始化Bugly数据的版本、渠道及部分初始化行为。通过以下方式传入:

UserStrategy strategy = new UserStrategy(appContext);
//...在这里设置strategy的属性,在bugly初始化时传入
//...
CrashReport.initCrashReport(appContext, APPID, true, strategy);

如果通过UserStrategy设置了版本号和渠道号,则会覆盖“AndroidManifest.xml”里面配置的版本号和渠道。

用户策略(UserStrategy)

设置设备id

3.4.4及之后版本不再采集Android id,为了使得crash率统计更精准,建议设置业务自己的deviceId(业务唯一id)给bugly sdk。

3.4.4版本前默认读取Android id作为设备id,App开发者可以在初始化bugly sdk的时候设置自定义的deviceId,为了避免合规问题,请务必升级到最新合规版本。

// 通过UserStrategy设置
strategy.setDeviceID("userdefinedId");

// 也可以通过CrashReport类设置,适合无法在初始化sdk时获取到deviceId的场景,context和deviceId不能为空(或空字符串)
CrashReport.setDeviceId(Context context, String deviceId);

设置设备型号

最新版本默认不再获取手机型号,App开发者可在合规获取到手机型号后设置给sdk。

// 通过UserStrategy设置
strategy.setDeviceModel("userdefinedModel");

// 也可以通过CrashReport类设置,适合无法在初始化sdk时获取到deviceModel的场景,context和deviceModel不能为空(或空字符串)
CrashReport.setDeviceModel(Context context, String deviceModel);

设置App版本、渠道、包名

Bugly默认读取AndroidManifest.xml文件中VersionName、Package信息。若您有自己的版本或渠道设定需求,可通过该接口修改。

strategy.setAppChannel("myChannel");  //设置渠道
strategy.setAppVersion("1.0.1");      //App的版本
strategy.setAppPackageName("com.tencent.xx");  //App的包名

// 也可以通过CrashReport类设置,适合在初始化sdk时无法获取到对应数据的场景,context、appChannel/appVersion/appPackage不能为空(或空字符串)
CrashReport.setAppChannel(Context context, String appChannel);
CrashReport.setAppVersion(Context context, String appVersion);
CrashReport.setAppPackage(Context context, String appPackage);

设置Bugly初始化延迟

Bugly会在启动10s后联网同步数据。若您有特别需求,可以修改这个时间。

strategy.setAppReportDelay(20000);   //改为20s

设置anr trace采集

最新版SDK支持trace文件采集和anr过程中的主线程堆栈信息采集,由于抓取堆栈的系统接口 Thread.getStackTrace 可能造成crash,建议只对少量用户开启

// 设置anr时是否获取系统trace文件,默认为false
strategy.setEnableCatchAnrTrace(boolean enable); 

// 设置是否获取anr过程中的主线程堆栈,默认为true
strategy.setEnableRecordAnrMainStack(boolean enable);

系统trace文件信息和anr过程中主线程堆栈信息都会展示到bugly平台上-crash详情页-跟踪数据栏下,如图

Alt text

注:anr过程中主线程堆栈抓取逻辑:主线程卡顿2秒后开始抓取,2-5秒内每500ms抓取1次,超过5秒会每1秒、2秒、4秒...抓取,可以通过该文件记录的信息辅助分析对anr贡献最大的堆栈,如果同一个堆栈出现次数越多,说明它对anr的贡献越大,则约有可能是造成anr的原因。

设置crash和anr时是否获取全部堆栈

由于抓取全部堆栈接口Thread.getAllStackTraces()可能引起crash,建议只对少量用户开启

// crashEnable和anrEnable默认值为true
CrashReport.setAllThreadStackEnable(Context context, boolean crashEnable, boolean anrEnable);

设置标签

自定义标签,用于标明App的某个“场景”。在发生Crash时会显示该Crash所在的“场景”,以最后设置的标签为准,标签id需大于0。例:当用户进入界面A时,打上9527的标签:

CrashReport.setUserSceneTag(context, 9527); // 上报后的Crash会显示该标签

打标签之前,需要在Bugly产品页配置中添加标签,取得标签ID后在代码中上报。

设置自定义Map参数

自定义Map参数可以保存发生Crash时的一些自定义的环境信息。在发生Crash时会随着异常信息一起上报并在页面展示。

CrashReport.putUserData(context, "userkey", "uservalue");
  • 最多可以有50对自定义的key-value(超过则添加失败);
  • key限长50字节,value限长200字节,过长截断;

设置开发设备

在开发测试阶段,可以在初始化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<String, String> 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<String, String> onCrashHandleStart(int crashType, String errorType, 
            String errorMessage, String errorStack) {
        LinkedHashMap<String, String> map = new LinkedHashMap<String, String>();
        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平台,并展示在附件中:

Alt text

注意,需要尽量保证回调的逻辑简单和稳定,绝对不能在回调中Kill掉进程,否则会影响Crash的上报。如果需要执行类似于Crash之后Kill掉进程并重新拉起的动作,建议自定义一个Crash handler,并在初始化Bugly之前注册。

增加上报进程控制

如果App使用了多进程且各个进程都会初始化Bugly(例如在Application类onCreate()中初始化Bugly),那么每个进程下的Bugly都会进行数据上报,造成不必要的资源浪费。

因此,为了节省流量、内存等资源,建议初始化的时候对上报进程进行控制,只在主进程下上报数据:判断是否是主进程(通过进程名是否为包名来判断),并在初始化Bugly时增加一个上报进程的策略配置。

Context context = getApplicationContext();
// 获取当前包名
String packageName = context.getPackageName();
// 获取当前进程名
String processName = getProcessName(android.os.Process.myPid());
// 设置是否为上报进程
UserStrategy strategy = new UserStrategy(context);
strategy.setUploadProcess(processName == null || processName.equals(packageName));
// 初始化Bugly
CrashReport.initCrashReport(context, "注册时申请的APPID", isDebug, strategy);
// 如果通过“AndroidManifest.xml”来配置APP信息,初始化方法如下
// CrashReport.initCrashReport(context, strategy);

其中获取进程名的方法“getProcessName”有多种实现方法,推荐方法如下:

/**
 * 获取进程号对应的进程名
 * 
 * @param pid 进程号
 * @return 进程名
 */
private static String getProcessName(int pid) {
    BufferedReader reader = null;
    try {
        reader = new BufferedReader(new FileReader("/proc/" + pid + "/cmdline"));
        String processName = reader.readLine();
        if (!TextUtils.isEmpty(processName)) {
            processName = processName.trim();
        }
        return processName;
    } catch (Throwable throwable) {
        throwable.printStackTrace();
    } finally {
        try {
            if (reader != null) {
                reader.close();
            }
        } catch (IOException exception) {
            exception.printStackTrace();
        }
    }
    return null;
}

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 <第三方WebView对象>.getUrl();
    }

    /**
     * 开启JavaScript.
     *
     * @param flag true表示开启,false表示关闭
     */
    @Override
    public void setJavaScriptEnabled(boolean flag) {
        // 下面仅为例子,请用真正逻辑代替
        WebSettings webSettings = <第三方WebView对象>.getSettings();
        webSettings.setJavaScriptEnabled(flag);
    }

    /**
     * 加载URL.
     *
     * @param url 要加载的URL
     */
    @Override
    public void loadUrl(String url) {
        // 下面仅为例子,请用真正逻辑代替
        <第三方WebView对象>.loadUrl();
    }

    /**
     * 添加JavaScript接口对象.
     *
     * @param jsInterface JavaScript接口对象
     * @param name JavaScript接口对象名称
     */
    @Override
    public void addJavascriptInterface(H5JavaScriptInterface jsInterface, String name) {
        // 下面仅为例子,请用真正逻辑代替
        <第三方WebView对象>.addJavascriptInterface(jsInterface, name);
    }

    /**
     * 获取WebView的内容描述.
     *
     * @return WebView的内容描述.
     */
    @Override
    public CharSequence getContentDescription() {
        // 下面仅为例子,请用真正逻辑代替
        return <第三方WebView对象>.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中:
<html>
  <script src="bugly.js" ></script>
<body>
    ...
</body>
</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"))) = "<SO文件版本号>"

此后,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不在堆栈中显示):

Alt text