Bugly错误监测Android SDK接入

库文件导入

Bugly支持自动集成和手动集成两种方式，如果您使用Gradle编译Apk，强烈推荐您使用自动接入方式配置库文件。

自动集成（推荐）

Bugly支持JCenter仓库和Maven Central仓库。为了实现更加灵活的配置，Bugly SDK（2.1.5及以上版本）和NDK（SO库）目前已经分开成两个独立的仓库：

• SDK：com.tencent.bugly:crashreport
• NDK：com.tencent.bugly:nativecrashreport

其中，集成Bugly NDK时，需要同时集成Bugly SDK。

集成SDK

在Module的build.gradle文件中添加依赖和属性配置：

dependencies {
    compile 'com.tencent.bugly:crashreport:latest.release' //其中latest.release指代最新Bugly SDK版本号，也可以指定明确的版本号，例如2.2.0
}

同时集成SDK和NDK

在Module的build.gradle文件中添加依赖和属性配置：

android {
    defaultConfig {
        ndk {
            // 设置支持的SO库架构
            abiFilters 'armeabi' //, 'x86', 'armeabi-v7a', 'x86_64', 'arm64-v8a'
        }
    }
}

dependencies {
    compile 'com.tencent.bugly:crashreport:latest.release' //其中latest.release指代最新Bugly SDK版本号，也可以指定明确的版本号，例如2.1.9
    compile 'com.tencent.bugly:nativecrashreport:latest.release' //其中latest.release指代最新Bugly NDK版本号，也可以指定明确的版本号，例如3.0
}

同时集成Bugly SDK和NDK的配置如下图所示，后续更新Bugly SDK和NDK时，只需变更配置脚本中的版本号即可。

注意：自动集成时会自动包含Bugly SO库，建议在Module的build.gradle文件中使用NDK的“abiFilter”配置，设置支持的SO库架构。

如果在添加“abiFilter”之后Android Studio出现以下提示：

NDK integration is deprecated in the current plugin. Consider trying the new experimental plugin.

则在项目根目录的gradle.properties文件中添加：

android.useDeprecatedNdk=true

手动集成

如果您不采用上述自动导入方式，也可以手动集成Bugly SDK。

下载Bugly库文件

• 下载Bugly的Android SDK包；
• 如果您的工程有Native代码（C/C++）或者集成了其他第三方SO库，建议下载Bugly的NDK动态库。

Bugly NDK包含多个架构的SO库：

• armeabi
• armeabi-v7a
• arm64-v8a
• x86
• x86_64

在集成Bugly SO库时，请注意只保留支持的架构SO库。

Eclipse工程

• 将Bugly库文件复制到工程的libs目录下；
• Refresh一下工程；
• 添加工程依赖：鼠标右键点击Bugly的JAR文件，添加到编译路径中。

Android Studio工程

• 将Bugly库文件复制到工程的libs目录下；
• 如果集成Bugly NDK，则在Module的buid.gradle文件中添加SO库目录配置：

android {
    sourceSets {
        main.jniLibs.srcDirs = ['libs']
    }
}

• 点击Sync，同步配置。

为了使APP Crash堆栈的可读性更高，建议您配置符号表文件，更准确地定位问题：

• 纯Java代码的工程：只需要配置混淆后生成的Mapping文件即可；
• 含有Native代码的工程：建议配置符号表工具从Debug SO中提取的Symbol符号表文件。

Bugly支持手动和自动配置两种方式，具体的配置方法请参考：《Bugly Android符号表配置》

参数配置

• 在AndroidManifest.xml中添加权限：

<uses-permission android:name="android.permission.READ_PHONE_STATE" />
<uses-permission android:name="android.permission.INTERNET" />
<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_LOGS" />

• 请避免混淆Bugly，在Proguard混淆文件中增加以下配置：

-dontwarn com.tencent.bugly.**
-keep public class com.tencent.bugly.**{*;}

最简单的初始化

获取APP ID并将以下代码复制到项目Application类onCreate()中，Bugly会为自动检测环境并完成配置：

CrashReport.initCrashReport(getApplicationContext(), "注册时申请的APPID", false); 

为了保证运营数据的准确性，建议不要在异步线程初始化Bugly。

第三个参数为SDK调试模式开关，调试模式的行为特性如下：

• 输出详细的Bugly SDK的Log；
• 每一条Crash都会被立即上报；
• 自定义日志将会在Logcat中输出。

建议在测试阶段建议设置成true，发布时设置为false。

此外，Bugly2.0及以上版本还支持通过“AndroidManifest.xml”来配置APP信息。如果同时又通过代码中配置了APP信息，则最终以代码配置的信息为准。

在“AndroidManifest.xml”的“Application”中增加“meta-data”配置项：

<application
    -- 配置APP ID -->
    <meta-data
            android:name="BUGLY_APPID"
            android:value="" />
    
    <meta-data
            android:name="BUGLY_APP_VERSION"
            android:value="" />
    
    <meta-data
            android:name="BUGLY_APP_CHANNEL"
            android:value="" />
    
    <meta-data
            android:name="BUGLY_ENABLE_DEBUG"
            android:value="" />
application>

不同于“android:versionName”，“BUGLY_APP_VERSION”配置的是Bugly平台的APP版本号。

通过“AndroidManifest.xml”配置后的初始化方法如下：

CrashReport.initCrashReport(getApplicationContext());

Bugly默认从“AndroidManifest.xml”文件中读取“VersionName”作为版本号，自定义设置请使用参考“高级设置”。

增加上报进程控制

如果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;
}

测试

现在您可以制造一个Crash（建议通过“按键”来触发），来体验Bugly的能力了。在初始化Bugly的之后，调用Bugly测Java Crash接口。

CrashReport.testJavaCrash();

执行到这段代码时会发生一个Crash，Logcat的TAG=CrashReportInfo中输出为：

现在您已经可以在“崩溃”页面看到刚才触发的Crash issue了（延迟一般在10s以内）。

如果项目包含了Native工程或者使用了代码混淆，建议配置符号表文件。

更多的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字节，过长截断。

设置开发设备

在开发测试阶段，可以在初始化Bugly之前通过以下接口把调试设备设置成“开发设备”。

CrashReport.setIsDevelopmentDevice(context, true);

ADT 17增加了BuildConfig特性，可以通过获取BuildConfig类的DEBUG变量来设置：

CrashReport.setIsDevelopmentDevice(context, BuildConfig.DEBUG);

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方式，且需要在HTML手动嵌入Bugly.js，请下载Bugly SDK包；
• 由于Android 4.4以下版本存在反射漏洞，接口默认只对Android 4.4及以上版本有效；
• 接口不会设置webView的WebViewClient和Listener；
• 接口默认会开启webView的JS执行能力；

自动注入

建议在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"))) = "

此后，NDK编译的SO文件将带有一个具有版本信息的段（.bugly_version）。之所以把段名 定义为“.bugly_version”，是为了Bugly的NDK解析的统一性。查看SO文件的版本号的一个方法如下（需要readelf或类似工具）：

readelf -p .bugly_version libxxx.so

添加SO文件的UUID

在“/build/core/import-locals.mk”文件的最后加上一行：

LOCAL_LDFLAGS += -Xlinker --build-id

此后，NDK构建的SO文件将带有一个段（.note.gnu.buildid）专门存放构建的UUID。查看SO文件的UUID的一个方法如下（需要readelf或类似工具）：

readelf -x .note.gnu.build-id 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。

Native堆栈例子如下图（UUID不在堆栈中显示）：