文档中心

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。

添加额外的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

v1.0.0

Bugly Android SDK 高级配置

更多的Bugly行为控制

用户策略（UserStrategy）

设置设备id

设置设备型号

设置App版本、渠道、包名

设置Bugly初始化延迟

设置anr trace采集

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

设置标签

设置自定义Map参数

设置开发设备

设置Crash回调

增加上报进程控制

Javascript的异常捕获功能

自动注入

手动注入

更多的Bugly日志附加信息

添加额外的SO文件信息

SO文件的版本号

添加SO文件的UUID