温馨提示：这篇文档可能会花费你 10 分钟左右的时间阅读完成，但我们相信这 10 分钟你将有所收获，
在介绍如何使用之前，先看看 Bugtags 到底是做什么的吧！ 如果你只想看 Bugtags Web 的使用说明，请点 这里。

Bugtags 是什么？

Bugtags 是移动时代首选 Bug 管理系统，针对不同的使用场景，Bugtags 具有以下强大特性：

移动应用 Bug 管理

Bugtags 可以直接在应用中所见即所得提交 Bug，自动上传截图、操作步骤、控制台日志等数据。

移动应用崩溃管理

智能发现并上报所有崩溃数据，包含截图、堆栈、操作步骤、控制台日志等数据。

移动应用用户反馈管理

用户遇到问题只需手机摇一摇并标注，相关数据即可实时同步到你的管理云端。

网站应用 Bug 管理

强大的浏览器插件支持，任何网页 Bug 都可轻松标注并提交。

Bugtags 的优势是什么？

1. 宿主应用里所见即所得的提交 Bug，体验流畅，方便快捷；
2. 自动获取 Bug 产生时的界面截图；
3. 直接在宿主应用中标签化描述问题，所提即所指；
4. 自动获取移动设备的硬件参数（型号、系统版本、屏幕分辨率等）；
5. 自动获取应用运行上下文数据（如：网络状态、用户数据、后端数据、用户操作步骤等）；
6. 自动提交闪退 Bug，附带硬件参数、运行上下文数据、堆栈数据等；
7. 强大的浏览器插件，支持在任何网页上直接截屏并标注 Bug；
8. 云端管理 Bug，操作简单，零成本部署。

Bugtags 与其他产品的区别是什么？

1. Bugtags 不是做统计的 SDK;
2. Bugtags 不只是收集闪退的 SDK;
3. Bugtags 不是做自动化测试的 SDK;
4. Bugtags 不是做内测分发的 SDK;
5. Bugtags 不是普通的 Bug 管理系统;
6. Bugtags 不需要布署，云端注册即可使用，简单便捷。

Bugtags SDK 的集成方式

iOS 集成 （两种方式）

一、通过 CocoaPods 集成 SDK

注意：

• SDK 最低兼容 iOS 6.0；
• 请勿与其他带有崩溃分析的 SDK 同时使用，否则将有可能影响崩溃捕捉功能的正常使用；
• 集成有问题，请查看集成视频，查看 FAQ，或者进入 QQ 群：428020377；
• App 在联机 Debug 状态下，SDK 默认不自动上报闪退，如需上报，请手动设置BugtagsOptions -> trackingCrashes 参数；
• 使用说明请参阅产品说明文档。

步骤：

1. 在你项目的 Podfile 中添加以下代码

   1	pod 'Bugtags'

2. 执行 pod 安装命令

   1	pod install

如果无法获取到最新版本的 Bugtags SDK，请运行以下命令更新本地的 pod 仓库

1

pod repo update

运行完成后，重新执行安装命令 pod install

1. 重要！ 执行完 pod 命令后，请确认在应用对应 target 的设置中，Build Settings -> Linking 项下的 Other Linker Flags 中是否已自动添加 $(inherited)，如果未添加，请手动添加
   Other Linker Flags
2. 在 AppDelegate.m 中导入头文件

   1	#import <Bugtags/Bugtags.h>

如果是 Swift 项目，请在对应的 bridging-header.h 中导入

1. 在项目 AppDelegate 的 application didFinishLaunchingWithOptions 方法中初始化Bugtags（请不要在异步线程中调用）

   Objective-C

   1 2 3 4 5

   - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions { [Bugtags startWithAppKey:@"APP_KEY" invocationEvent:BTGInvocationEventBubble]; return YES; }

   Swift

   1 2 3 4 5

   func application(application: UIApplication, didFinishLaunchingWithOptions launchOptions: [NSObject: AnyObject]?) -> Bool { Bugtags.startWithAppKey("APP_KEY", invocationEvent: BTGInvocationEventBubble) return true }

2. 如果你需要自定义 Bugtags 的功能，可以向 Bugtags 的初始化方法中传入BugtagsOptions 参数：

   Objective-C

   1 2 3 4 5 6 7

   - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions { BugtagsOptions *options = [[BugtagsOptions alloc] init]; options.trackingCrashes = YES; // 具体可设置的属性请查看 Bugtags.h [Bugtags startWithAppKey:@"APP_KEY" invocationEvent:BTGInvocationEventBubble options:options]; return YES; }

   Swift

   1 2 3 4 5 6 7

   func application(application: UIApplication, didFinishLaunchingWithOptions launchOptions: [NSObject: AnyObject]?) -> Bool { let options = BugtagsOptions() options.trackingCrashes = true // 具体可设置的属性请查看 Bugtags.h Bugtags.startWithAppKey("APP_KEY", invocationEvent: BTGInvocationEventBubble, options: options) return true }

编译运行 App，将会在 App 中看到一个小球，成功了！看不到悬浮球？

参考资源：

• FAQ 列表
• API 文档
• 示例应用
• ****
• 产品说明文档
• CocoaPods 官网

二、手动集成 SDK

注意：

• SDK 最低兼容 iOS 6.0；
• 请勿与其他带有崩溃分析的 SDK 同时使用，否则将有可能影响崩溃捕捉功能的正常使用；
• 集成有问题，请查看集成视频，查看 FAQ，或者进入 QQ 群：428020377；
• App 在联机 Debug 状态下，SDK 默认不自动上报闪退，如需上报，请手动设置BugtagsOptions -> trackingCrashes 参数；
• 使用说明请参阅产品说明文档。

步骤：

1. 下载 SDK 压缩包 并解压缩
2. 将 Bugtags.framework 和 Bugtags.bundle 文件夹拖到 Xcode 项目中

3. 在应用的设置中，Build Phases -> Link Binary With Libraries 里添加以下framework：

   1 2	UIKit AVFoundation Foundation SystemConfiguration QuartzCore CoreLocation ImageIO Security CFNetwork

4. 重要！ 在应用对应 target 的设置中，Build Settings -> Linking 项下的 Other Linker Flags 中添加 -ObjC（如果已有，则不需要再添加）注意 O,C 大写
   Other Linker Flags
   添加 -ObjC 导致编译出错？

5. 在 AppDelegate.m 中导入头文件

   1	#import <Bugtags/Bugtags.h>

如果是 Swift 项目，请在对应的 bridging-header.h 中导入

1. 在项目 AppDelegate 的 application didFinishLaunchingWithOptions 方法中初始化Bugtags（请不要在异步线程中调用）

   Objective-C

   1 2 3 4 5

   - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions { [Bugtags startWithAppKey:@"APP_KEY" invocationEvent:BTGInvocationEventBubble]; return YES; }

   Swift

   1 2 3 4 5

   func application(application: UIApplication, didFinishLaunchingWithOptions launchOptions: [NSObject: AnyObject]?) -> Bool { Bugtags.startWithAppKey("APP_KEY", invocationEvent: BTGInvocationEventBubble) return true }

2. 如果你需要自定义 Bugtags 的功能，可以向 Bugtags 的初始化方法中传入BugtagsOptions 参数：

   Objective-C

   1 2 3 4 5 6 7

   - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions { BugtagsOptions *options = [[BugtagsOptions alloc] init]; options.trackingCrashes = YES; // 具体可设置的属性请查看 Bugtags.h [Bugtags startWithAppKey:@"APP_KEY" invocationEvent:BTGInvocationEventBubble options:options]; return YES; }

   Swift

   1 2 3 4 5 6 7

   func application(application: UIApplication, didFinishLaunchingWithOptions launchOptions: [NSObject: AnyObject]?) -> Bool { let options = BugtagsOptions() options.trackingCrashes = true // 具体可设置的属性请查看 Bugtags.h Bugtags.startWithAppKey("APP_KEY", invocationEvent: BTGInvocationEventBubble, options: options) return true }

编译运行 App，将会在 App 中看到一个小球，成功了！看不到悬浮球？

参考资源：

• FAQ 列表
• API 文档
• 示例应用
• ****
• 产品说明文档

Android 集成 （两种方式）

一、通过 Maven 集成 SDK

注意:

• 最新版为 1.1.0，如需更新，请修改并重新同步 build.gradle 文件；
• 请勿与其他带有崩溃分析的 SDK 同时使用，否则将有可能影响崩溃捕捉功能的正常使用；
• App 在联机 Debug 状态下，SDK 默认不自动上报闪退，如需上报，请设置启动参数BugtagsOptions -> trackingCrashes 参数；
• 关于小米手机悬浮小球等问题，请查看：Android 常见问题；

v1.1.0 重大升级

• 支持 Cocos2d-x 游戏截屏，请参考集成文档；
• 须配置 gradle 插件，请参考以下方式进行配置；

第一步：配置依赖

• Bugtags SDK 已经同步到 jcenter 和 MavenCentral，请在项目的 build.gradle（项目最外层的 build.gradle 文件，所谓的 Top-level build file）设置 buildscript dependencies ：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

buildscript {
    repositories {
        jcenter()
        mavenCentral()
    }
    dependencies {
        classpath 'com.android.tools.build:gradle:1.3.0'
        //**重要**
        classpath 'com.bugtags.library:bugtags-gradle:latest.integration'
    }
}
allprojects {
    repositories {
        jcenter() //注：repository 1
        mavenCentral()  //注：repository 2
    }
}

• 在模块的 build.gradle 应用插件和添加依赖：

1
2
3
4
5
6
7
8
9
10
11
12

//应用插件
apply plugin: 'com.bugtags.library.plugin'

//自动上传插件
bugtags {
    appKey APP_KEY  //这里是你的 appKey
    appSecret APP_SECRET    //这里是你的 appSecret，管理员在设置页可以查看
}

dependencies {
    compile 'com.bugtags.library:bugtags-lib:latest.integration'
}

如下图：

Bugtags-Android-Studio

第二步：添加回调

在你的 Activity 基类（或所有的 Activity）中添加3个回调：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

package your.package.name;
import android.app.Activity;
import android.os.Bundle;
import android.view.MotionEvent;
import com.bugtags.library.Bugtags;

public class BaseActivity extends Activity{
    @Override
    protected void onResume() {
        super.onResume();
        //注：回调 1
        Bugtags.onResume(this);
    }

    @Override
    protected void onPause() {
        super.onPause();
        //注：回调 2
        Bugtags.onPause(this);
    }

    @Override
    public boolean dispatchTouchEvent(MotionEvent event) {
        //注：回调 3
        Bugtags.onDispatchTouchEvent(this, event);
        return super.dispatchTouchEvent(event);
    }
}

第三步：启动 SDK

• 继承 Application，在 onCreate() 方法中初始化 Bugtags：

1
2
3
4
5
6
7
8

public class MyApplication extends Application {
    @Override
    public void onCreate() {
        super.onCreate();
        //在这里初始化
        Bugtags.start("APP_KEY", this, Bugtags.BTGInvocationEventBubble);
    }
}

• 修改 AndroidManifest.xml，使用 MyApplication 类,例如：

1
2
3
4
5
6

<application
    android:name=".MyApplication"
    android:label="@string/app_name"
    android:theme="@style/AppTheme" >
    ....
</application>

关于如何使用 Android Studio 以及 gradle，请参考 bugtags 博客系列文章。

编译运行 App，将会在 App 内部看到一个小球，成功了!

更多

• 使用启动参数

1
2
3
4
5
6
7
8
9
10

BugtagsOptions options = new BugtagsOptions.Builder().
                trackingLocation(true).//是否获取位置
                trackingCrashLog(true).//是否收集crash
                trackingConsoleLog(true).//是否收集console log
                trackingUserSteps(true).//是否收集用户操作步骤
                versionName("1.0.1").//自定义版本名称
                versionCode(10).//自定义版本号
                build();

Bugtags.start("APP_KEY", this, Bugtags.BTGInvocationEventBubble, options);

• Proguard 混淆规则：

1
2
3
4
5
6
7

-keepattributes LineNumberTable,SourceFile

-keep class com.bugtags.library.** {*;}
-dontwarn org.apache.http.**
-dontwarn android.net.http.AndroidHttpClient
-dontwarn com.bugtags.library.vender.**
-dontwarn com.bugtags.library.**

• SDK 最低兼容 Android 2.3(API 9) 及以上版本；集成有问题请进入 QQ 群：210286347；
• 以上的配置方式对于 Android Studio 和 Intellij IDEA 是通用的，Bugtags 推荐使用 Android Studio。Let's embrace change!

参考资源

• FAQ 列表
• API 文档
• bugtags-demo-app
• bugtags-demo-apk
• ****
• 产品说明文档

二、手动集成 SDK

注意:

• 最新版为 1.1.0，如需更新，重新下载 SDK 进行集成；
• 请勿与其他带有崩溃分析的 SDK 同时使用，否则将有可能影响崩溃捕捉功能的正常使用；
• App 在联机 Debug 状态下，SDK 默认不自动上报闪退，如需上报，请设置启动参数BugtagsOptions -> trackingCrashes 参数；
• 关于小米手机悬浮小球等问题，请查看：Android 常见问题；

第一步：添加权限和服务

• 下载 SDK

• import Bugtags-Android-Eclipse-Lib 到项目的工作空间

• 将其添加为您的工程的库依赖。

添加依赖这一步非常重要！

方法为：> 项目->右键->property->Android->Library中添加”Bugtags-Android-Eclipse-Lib”项目作为依赖，要十分注意support-v4包重复的问题！

如下图：

Bugtags-Eclipse

• 在 AndroidManifest.xml 中添加以下权限

1
2
3
4
5
6
7
8
9
10

<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.READ_LOGS" />
<uses-permission android:name="android.permission.READ_PHONE_STATE" />
<uses-permission android:name="android.permission.SYSTEM_ALERT_WINDOW" />

• 在 AndroidManifest.xml 中添加所需的 activity 和服务

1
2
3
4
5
6
7
8
9
10
11
12

<activity
	android:name="com.bugtags.library.BugtagsActivity"
	android:configChanges="keyboardHidden|orientation|screenSize"
	android:theme="@android:style/Theme.NoTitleBar.Fullscreen"/>
<receiver
	android:name="com.bugtags.library.BugtagsReceiver">
	<intent-filter>
		<action android:name="android.net.conn.CONNECTIVITY_CHANGE"/>
	</intent-filter>
</receiver>
<service
	android:name="com.bugtags.library.BugtagsService"/>

第二步：添加回调

在你的 Activity 基类（或所有的 Activity）中添加3个回调：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

package your.package.name;
import android.app.Activity;
import android.os.Bundle;
import android.view.MotionEvent;
import com.bugtags.library.Bugtags;

public class BaseActivity extends Activity{
    @Override
    protected void onResume() {
        super.onResume();
        //注：回调 1
        Bugtags.onResume(this);
    }

    @Override
    protected void onPause() {
        super.onPause();
        //注：回调 2
        Bugtags.onPause(this);
    }

    @Override
    public boolean dispatchTouchEvent(MotionEvent event) {
        //注：回调 3
        Bugtags.onDispatchTouchEvent(this, event);
        return super.dispatchTouchEvent(event);
    }
}

第三步：启动 SDK

• 继承 Application，在 onCreate() 方法中初始化 Bugtags：

1
2
3
4
5
6
7
8

public class MyApplication extends Application {
    @Override
    public void onCreate() {
        super.onCreate();
        //在这里初始化
        Bugtags.start("APP_KEY", this, Bugtags.BTGInvocationEventBubble);
    }
}

• 修改 AndroidManifest.xml，使用 MyApplication 类,例如：

1
2
3
4
5
6

<application
    android:name=".MyApplication"
    android:label="@string/app_name"
    android:theme="@style/AppTheme" >
    ....
</application>

编译运行 App，将会在 App 内部看到一个小球，成功了!

更多

• 使用启动参数

1
2
3
4
5
6
7
8
9
10

BugtagsOptions options = new BugtagsOptions.Builder().
                trackingLocation(true).//是否获取位置
                trackingCrashLog(true).//是否收集crash
                trackingConsoleLog(true).//是否收集console log
                trackingUserSteps(true).//是否收集用户操作步骤
                versionName("1.0.1").//自定义版本名称
                versionCode(10).//自定义版本号
                build();

Bugtags.start("APP_KEY", this, Bugtags.BTGInvocationEventBubble, options);

• Proguard 混淆规则：

1
2
3
4
5
6
7

-keepattributes LineNumberTable,SourceFile

-keep class com.bugtags.library.** {*;}
-dontwarn org.apache.http.**
-dontwarn android.net.http.AndroidHttpClient
-dontwarn com.bugtags.library.vender.**
-dontwarn com.bugtags.library.**

• SDK 最低兼容 Android 2.3(API 9) 及以上版本；集成有问题请进入 QQ 群：210286347；

参考资源

• FAQ 列表
• API 文档
• bugtags-demo-app
• bugtags-demo-apk
• ****
• 产品说明文档

SDK 集成后的使用

集成 SDK 后，可在应用中所见即所得的提交 Bug，并且 Bugtags 会自动提交闪退 Bug

提交Bug主要分为以下几步：

1. 登录（可选）；
2. 添加一个标签；
3. 填写描述、类型、优先级、指派人；
4. 提交。

登录

SDK 集成后，会在应用界面上出现 Bugtags 浮动小球，通过点击小球提交 Bug。
在提交 Bug 前建议先登录，以确保团队成员可以看到 Bug 提交者。

登录

• 添加标签

点击小球后，会看到一个蓝色添加按钮，点击后 Bugtags 会自动将当前界面截屏。

添加标签

• 填写描述、设置类型、优先级、指派人

点击界面上有错误的位置，即会弹出完善 Bug 信息的弹框，根据实际情况设置类型、优先级、指派人。
点击确定，即会在界面上显示一个 Bug 标签，若想继续增加，重复上述步骤即可，最多可以添加 3 个标签。

完善信息

• 提交

点击蓝色“对勾”按钮提交Bug。提交后，可在 Bugtags 云端 查看。

提交

如果你在集成SDK中遇到问题，请查看 帮助

Web

创建应用

在你的首页中，可以通过导航栏中的添加应用按钮添加应用。
添加应用后会生成 App Key。将这个 App Key 粘贴到 SDK 中相应位置即可。
应用支持 iOS 、Android 和 Web 三种类型。

创建应用

首页

显示了当前应用状态，基本信息、最新的应用状态，以及目前指派给你的问题、你提交过的问题以及你跟踪的问题。

首页

问题

当前应用中的所有问题，可通过左侧筛选栏过滤，也可通过右侧列表上方的搜索进行关键字查找问题，
在列表中，一个问题可以包含3个标签，可轻松通过右侧的操作按钮，更换标签状态、优先级、指派人。
左侧的筛选支持对标签类型、状态、优先级、版本号、指派人、提交人、你跟踪的以及时间段进行过滤，并且可以对筛选条件进行保存。
右侧的列表中，支持搜索、排序，以及将结果集导出到 Excel。
管理员可以进行批量删除以及批量修改标签状态操作。
如下图：

问题列表

问题详情

详情页分为左右两个区域，左侧问题操作区，右侧为展示区。如图：

问题详情

• 操作区

可对标签的状态、类型、优先级、指派人、跟踪者进行修改。

操作区

重复标签可以指定哪个标签与此标签重复，方便查找。删除标签是应用管理员才可以使用的功能。

重复标签

• 展示区

展示区中分为 5 个 栏目，设备信息、用户数据、用户步骤、控制台日志、Bugtags 日志，可以查看到这个问题更为详细的信息。

详情展示

• 崩溃展示区

Bugtags 支持自动捕捉崩溃功能，当应用崩溃后，Bugtags 会记录当时的界面截图、设备信息，堆栈信息，
以及其它有助于定位 Bug 的数据。并且，系统将崩溃次数、影响机型、影响用户的统计数据进行了汇总，
如果这个崩溃发生在很多设备上，不会重复上报此问题，而会将此问题进行合并，汇总数据自动累加。
当应用重新被打开时，这些数据将会被提交到云管理平台。

崩溃展示区

点击详细数据后，会看到这个崩溃所涉及的设备信息及系统版本信息，可通过点击对某一设备查看详细数据。

详细数据

• 历史记录

在历史记录中，可以追溯到这个问题从开始到关闭的每一步操作，防止疏漏。并且可以进入留言，支持 @ 某人，或#链接其他标签。
并可以上传附件，支持文档、图片、压缩包以及安装包格式，当上传的是 apk 或 ipa 安装包时，会生成二维码，扫码后即可在手机中安装。

历史记录

统计

Bugtags 带有统计功能。可以查看当前应用的整体数据或切换版本查看最近两周每日的崩溃次数、各版本标签状态统计、累计标签按状态统计、
新增标签按状态统计、累计标签按类型统计、新增标签按类型统计、开发者标签状态统计、提交者标签状态统计，
同时还可以查看到崩溃的设备分布及系统分布，实时了解项目测试进度。

统计

所有成员标签状态

成员标签状态

崩溃数据分布

数据分布

SDK

在后台中，同样有SDK的介绍以及示例应用，可以参照示例应用将 SDK 集成到应用当中。根据你的应用类型，显示相应的 SDK 集成方式。

SDK

设置

在设置中，可以看到应用的基本信息，管理员有进行编辑和修改的权限。

• 应用成员

在应用成员中，可以看到已经加入到这个应用中的所有成员。邀请成员需要有管理员权限。
管理员可以对应用成员进行管理，可设置其他成员为管理员，或移除成员操作。
邀请成员支持三种方式：批量邮箱邀请、导入其他应用中的成员和导入邀请过的成员，便于你快速将成员加入到新的应用中。

应用成员

• 传符号表

SDK 捕获上报的异常堆栈中通常都是地址信息，如果要显示详细的出错位置，则需要上传应用的符号表。
上传相应的符号表后，云端会自动将对应的符号表与崩溃信息匹配，使崩溃的堆栈信息更加详细。
有关上传符号表的步骤请 参考这里

传符号表

• 邮件提醒

可对邮件提醒进行自定义设置，避免邮件过多造成的困扰。

邮件提醒

• 高级设置

高级设置中，可以对默认指派者进行设置，以及设置是否允许匿名用户在 SDK 中提交问题。

高级设置

Web 新建问题

有时候，你可能会提一些需求或者改进，而这个操作需要在电脑上完成，Bugtags 提供了 Web 新建问题功能，可以很好的将这些问题提交上去，
并且支持手机直传，比如你要提交一个 Bug，并需要上传一张手机中的图片，可以扫描手机直传二维码，
并在手机中选择图片，网页中将会自动同步这张图片。
同时，Bugtags 还为你提供了强大的 Chrome 截图插件和 Safari 截图插件，方便你在任何网页上截图并提交问题。

新建问题

Chrome 截图插件安装页

Chrome 插件

使用说明请点 这里

桌面通知

桌面通知

桌面通知是指你在打开 Bugtags 网站并处于登录状态，当最小化浏览器窗口或切换至其他窗口时，也能够收到通知提示，可以帮助你更加及时地收到相关问题的进度与状态，提高协作效率。
点击页面右上角头像后，点击可「桌面通知」设置。
桌面通知

关于浏览器配置桌面通知，请点这里

看到这里，Bugtags 的基本功能已经介绍完了，在 Bugtags Web 中还隐藏着一些彩蛋，比如任何页面输入“?”看看~
更多彩蛋等你去发现。
Bugtags 希望能够帮助广大开发者提高测试及解决缺陷的效率，连接发现缺陷与提交缺陷之间的用户体验，