Android SDK接入指引

本文介绍Bugly专业版Android SDK的接入步骤。注册产品，接入SDK后，验证数据上报成功，即可在Bugly 专业版的官网使用相关分析功能。

接入前准备

在接入sdk之前，请务必认真阅读《开发者合规指南》。
SDK在初始化过程中，可能会采集部分用户信息。请在用户同意《Bugly专业版SDK个人信息保护规则》之后，再进行SDK的初始化。SDK在初始化前，不会收集任何信息。

Demo示例

Android体验Demo

Demo已经接入了Bugly专业版的性能监控和稳定性监控的所有能力。
你可以通过Demo模拟各种异常和性能数据。
你可以配置成自己注册产品的AppID及AppKey，将数据上报到Bugly平台，进行SDK功能测试。
测试完成后，请使用自己注册产品的AppID及AppKey初始化Bugly SDK。
Demo上报的数据有流量限制，超过限制部分会被丢弃。

步骤一：注册产品，获取AppID及AppKey

请参考快速入门，在Bugly专业版上创建新产品，创建成功后，在设置-->产品信息中，复制AppID及AppKey。

快速验证提示

如果只是为了验证SDK，可以使用 Android体验Demo 的AppID以及AppKey。

Demo

步骤二：集成SDK

自动集成（推荐）

Bugly Pro支持 Maven Central 仓库。

1. 在project级别的build.gradle添加maven地址。

buildscript {
    repositories {
        maven { url 'https://repo1.maven.org/maven2/' }
    }
}

allprojects {
    repositories {
        maven { url 'https://repo1.maven.org/maven2/' }
    }
}

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

android {
    defaultConfig {
        ndk {
            abiFilters 'armeabi-v7a', 'arm64-v8a'
        }
    }
}

dependencies {
    implementation "com.tencent.bugly:bugly-pro:4.4.1.8"
}

手动集成（不推荐）

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

1. 下载Bugly专业版Android SDK的aar文件。

Bugly专业版Android SDK 下载地址：Central Repository: com/tencent/bugly/bugly-pro

选择恰当的版本，如本示例中的 4.4.1.8, 点击下载 bugly-pro-4.4.1.8.aar

Demo

2. Android Studio工程中引入依赖。

将aar文件复制到module的libs目录下，在module的gradle文件中添加依赖

dependencies {
    // bugly sdk 的依赖
    implementation 'org.jetbrains.kotlin:kotlin-android-extensions-runtime:1.3.41'
    implementation 'org.jetbrains.kotlin:kotlin-stdlib-jdk7:1.3.41'
    implementation 'com.squareup.leakcanary:shark:2.7'
    implementation 'androidx.annotation:annotation:1.2.0'
    // 手动集成
    implementation files('libs/bugly-pro-4.3.2.9.aar')
}

提醒

如果手工集成「4.3.0.6」及其之前的版本，依赖库还需要添加以下行：

implementation 'androidx.startup:startup-runtime:1.1.1'

步骤三：初始化SDK

参考以下代码初始化Bugly 专业版SDK，我们推荐尽可能早初始化，这样才能及时捕获异常。

public static void initBugly(Context context) {
    // 1. 初始化参数预构建，必需设置初始化参数
    String appID = "a278f01047"; // 【必需设置】在Bugly 专业版 注册产品的appID
    String appKey = "1e5ab6b3-b6fa-4f9b-a3c2-743d31dffe86"; // 【必需设置】在Bugly 专业版 注册产品的appKey
    BuglyBuilder builder = new BuglyBuilder(appID, appKey);
    
    // 2. 基本初始化参数，推荐设置初始化参数
    builder.uniqueId = "unique_id"; // 【推荐设置】设置设备唯一ID，必须保证唯一性，不设置则由Bugly生成唯一ID，影响设备异常率的统计以及联网设备数的统计,建议sp保存复用;  
    builder.userId = "user_id"; // 【推荐设置】设置用户ID，影响用户异常率的统计,建议sp保存复用，同一进程生命周期里面，暂不支持多次设置;
    builder.deviceModel = Build.MODEL; // 【推荐设置】设置设备类型，设置机型后，Bugly SDK不再读取系统的机型
    builder.appVersion = "1.0.0"; // 【推荐设置】设置App版本号，不设置则从packageManager中读取。建议按应用的规范，主动设置，需要跟上传符号表的应用版本参数保持一致。
    builder.buildNumber = "builderNum"; // 【推荐设置】设置App版本的构建号，用于Java堆栈翻译关联版本，跟上传符号表的构建号参数保持一致。
    builder.appVersionType = BuglyAppVersionMode.Debug; // 【推荐设置】设置版本类型
    
    // 3. 更多初始化参数，按需设置初始化参数
    builder.appChannel = "appChannel"; // 设置App的渠道
    builder.logLevel = BuglyLogLevel.LEVEL_DEBUG; // 设置日志打印级别，级别可从BuglyLogLevel中获取
    builder.enableAllThreadStackCrash = true; // 设置Crash时是否抓取全部线程堆栈，默认开启
    builder.enableAllThreadStackAnr = true; // 设置Anr时是否抓取全部线程堆栈，默认开启
    builder.enableCrashProtect = true; // 设置性能监控时开启Crash保护模式，默认开启
    builder.debugMode = false; // 设置debug模式，可在调试阶段开启

    // 4. 设置回调方法，按需设置初始化参数
    builder.setCrashHandleListener(crashHandleListener); // 设置Crash处理回调接口，详情见回调接口
    builder.setUploadHandleListener(uploadhandleListener); // 设置Crash上报回调接口，详情见回调接口
        
    // 5. 初始化，必需调用
    Bugly.init(context, builder);
}

初始化SDK注意事项

Context需要传递ApplicationContext。
设备ID非常重要，Bugly使用设备ID来计算设备异常率，强烈建议应用设置正确的设备ID，以确保设备的唯一性。
BuglyBuilder需在init方法前创建，且应避免重复调用init方法。
需要在调用Bugly.init接口，完成初始化后，再调用其他接口，进行定制化设置，否则设置不生效。
性能监控项可在控制管理台的设置/SDK配置中进行采样调整，通过调整设备采样率来开启或者关闭性能监控项。
建议在用户授权《Bugly专业版SDK个人信息保护规则》后再初始化Bugly。

步骤三：验证数据上报

提示

详细使用参考 Android体验Demo 。

前提条件

崩溃、ANR、OOM是100%上报，不支持采样，默认开启。除崩溃、ANR、OOM外，其他监控项支持采样。一般情况下，性能指标监控默认开启，性能异常监控默认关闭，用户可以通过SDK配置调整开启情况。在接入时，请务必确认功能的开启情况符合你的预期。
需要在控制管理台的 设置/SDK配置 中，创建配置任务。有关配置功能的详细说明，见《SDK配置使用指引》。
在接入期间，建议参考SDK配置-测试号码设置测试号码白名单，即将所有采样率调整为1.0，方便验证数据上报。接入完成后，再根据需要，调整采样率。
或者创建多个配置任务，根据版本类型（对应初始化的BuglyBuilder#appVersionType），配置开发任务，灰度任务，以及正式任务。开发任务打开所有的监控项，灰度阶段按需采样，正式发布根据需要降低采样。
检查待接入的产品是否已经购买并绑定「生效中的资源包」。如果产品没有绑定生效中的资源包，该产品将无法上报数据，见「快速入门」。

注意事项

验证数据上报前，请检查「前提条件」，重点关注配置是否正确，产品是否已经购买并绑定生效中的资源包。
一般情况下，性能指标监控默认开启，性能异常监控默认关闭。在接入时，请务必确认功能的开启情况符合你的预期。

崩溃监控

初始化完成后，可以模拟Java异常，或Native异常来验证SDK的上报情况，详细可以参考BuglyProDemo。

崩溃发生后，部分异常问题需要在第二次启动才能完成上报，为保证当次崩溃处理完成，二次启动的时间与崩溃发生时间最好间隔10s以上。上报可能存在延时，测试时建议手动多触发数次后，再刷新展示界面。

Bugly.testCrash(Bugly.JAVA_CRASH); // 模拟Java异常

Bugly.testCrash(Bugly.NATIVE_CRASH); // 模拟Native异常

崩溃上报后，在崩溃/问题列表中可以看到上报的问题，点击进入问题详情，查看上报详情。

需注意，进程信息只能在二次启动时上报，Java异常不会上报进程信息，其他异常中若没有看到进程信息的展示，请尝试手动重启进程触发上报后，再刷新展示界面。

崩溃监控

ANR监控

跟崩溃类似，可以通过Bugly提供的测试接口来模拟ANR，也可以自行在UI线程执行异常耗时任务。

Bugly.testCrash(Bugly.ANR_CRASH); // 模拟ANR

或者在UI线程执行以下耗时逻辑，触发ANR。

private void testANR(){
    try {
        Thread.sleep(30000);
    } catch (Exception e){
        // do nothing
    }
}

ANR上报后，在 ANR/问题列表可以看到上报的问题，点击进入问题详情，查看上报详情。

ANR监控

OOM监控

OOM是属于Crash问题的一种，例如java.lang.OutOfMemoryError，类似的还有FD OOM、Native OOM，分别代表因为FD资源不够导致的崩溃和因为Native内存不够导致的崩溃，Bugly将这类异常单独筛选出来，方便用户查看、分析。可以通过以下代码来模拟一个Java OOM：

private void tooManyMemory() {
    Thread thread = new Thread(new Runnable() {
        @Override
        public void run() {
            int bufferSize = 1024 * 1024 * 1024;
            List<Object> list = new ArrayList<>();
            for (;;){
                list.add(new byte[bufferSize]);
            }
        }
    });
    thread.start();
}

OOM上报后，在 OOM/问题列表可以看到上报的问题，点击进入问题详情，查看上报详情。

OOM监控

错误监控

错误一般是指用户自定义的异常，如已经捕获的Java异常，或者C#异常、JS异常、lua异常等。一般通过Bugly的handleCatchException或者postException来上报（详细参考其他接口/上报自定义异常或者上报Java catch异常部分）。

可以参考以下示例代码，上报Java捕获异常：

private void testJavaCatchError(){
     String content = "a illegal string.";
     try {
         JSONObject jsonObject = new JSONObject(content);
         double price  = jsonObject.getDouble("price");
     } catch (Throwable t) {
         Bugly.handleCatchException(Thread.currentThread(), t,
                            "in test code for json parse fail.", content.getBytes(), true);
    }
}

参考以下示例代码，上报自定义异常：

Bugly.postException(4, "testErrorType", "testErrorMsg", "testStack", null);

错误上报后，在错误/问题列表看到上报的问题，点击进入问题详情，查看上报详情。

错误监控

Bugly.handleCatchException(Thread thread, Throwable exception, String extraMsg, byte[] extraData)的参数中，thread提供出错线程，exception提供了详细的出错堆栈，extraMsg和extraData分别展示在附件中。

错误监控

启动监控

在开启启动监控的情况下，启动模块会自动安装监控，并且在Bugly初始化后，进行启动数据上报。用户可以通过Bugly.reportAppFullLaunch接口自定义启动结束点，也支持自定义标签以及通过打点接口，监控启动过程中的耗时任务。

请查看 API说明/启动监控 部分了解更多启动接口的使用。

private void costJobOne() {
    AppLaunchProxy.getAppLaunch().addTag("has_cost_job_one");
    AppLaunchProxy.getAppLaunch().spanStart("costJobOne", null);
    try {
        Thread.sleep(300);
    } catch (Throwable t) {
        Bugly.handleCatchException(Thread.currentThread(), t, "costJobOne sleep fail", null, true);
    }
    AppLaunchProxy.getAppLaunch().spanEnd("costJobOne");
}
    
private void finalJob() {
    AppLaunchProxy.getAppLaunch().reportAppFullLaunch();
}

启动监控

卡顿监控

卡顿指标：FPS及挂起率

在开启卡顿指标（"looper_metric"）的情况下，SDK会在初始化完成后，监控应用的流畅度情况。在应用一次运行期间，会先收集数据，保存本地，下次启动时再聚合上报。为了避免影响应用的启动，Bugly SDK 会在初始化5分钟后，再将缓存的数据聚合上报后台。

FPS：帧率，在应用运行时，GPU和CPU合作可产生的图像的数量，计量单位是帧/秒（FramePerSecond，缩写FPS），通常是评估硬件性能与应用体验流畅度的指标。

挂起率：如果应用两帧之间的刷新延时超过200ms，则认为此时应用不能很好地响应用户的交互，累加到挂起时间中。一个设备的挂起率，指这个设备在一天中，总的挂起时间除以其前台总时长，单位是秒/小时。

可以通过BuglyProDemo中，测试滑动卡顿来观察列表滑动情况下的FPS以及挂起率。

卡顿监控

在开启卡顿监控（"looper_stack"）的情况下，在UI线程执行耗时逻辑，耗时超过500ms的情况下，会触发卡顿上报。卡顿监控通过监控UI线程的消息执行来判断当前UI线程是否发生卡顿。

在验证阶段，建议将卡顿监控的"event_sample_ratio"（消息采样率）以及"sample_ratio"（设备采样率）都设置为1。这样只要满足卡顿的耗时阈值，即可触发卡顿上报。

参考以下示例代码模拟一个卡顿上报：

    private void testLongLag() {
        showToast("测试长卡顿");
        sleep(200);
        callFunctionA();
        callFunctionB();
    }

    private void callFunctionA() {
        sleep(400);
        callFunctionB();
    }

    private void callFunctionB() {
        sleep(300);
    }
    
    private static void sleep(long timeInMs) {
        try {
            Thread.sleep(timeInMs);
        } catch (Throwable t) {
            Bugly.handleCatchException(Thread.currentThread(), t, "sleep", null, false);
        }
    }

卡顿上报后，在卡顿/问题列表可以看到上报的问题，点击进入问题详情，查看上报详情。

卡顿监控

内存监控

内存峰值

内存峰值是指，应用在整个运行期间的内存使用峰值。Bugly通过定时任务，查询应用的内存使用情况，并且保存整个运行期间的最大使用量，应用下次启动后再上报。

物理内存峰值：一次运行期间，应用使用的物理内存峰值，即 PSS 峰值。

虚拟内存峰值：一次运行期间，应用使用的虚拟内存峰值，即 VSS 峰值。

Java 堆内存峰值：一次运行期间，应用所使用的 Java 堆内存峰值。

Java内存泄露

Java内存泄露，支持自动监听Activity/Fragment的生命周期，监控Activity或者Fragment的泄露情况。另外还提供了Bugly.startInspectLeakObj接口，检测应用关注的其他Java对象的泄露情况。简单来讲，就是在一个Java对象不再被使用，预期应该被回收时，开启这个对象的泄露检测。如果发现该对象存在泄露，则会dump应用的内存信息，分析对象的泄露链。

可以通过以下示例代码来验证：

private void testJavaObjLeak() {
    showToast("测试Java对象泄露");
    ArrayList<String> list = new ArrayList<>(1000);
    for (int i = 0; i < 50000; i++) {
        list.add(String.format(Locale.getDefault(), "%d: %s", i, UUID.randomUUID().toString()));
    }
    LeakKeeper.leakObj(list);
    Bugly.startInspectLeakObj(list);
}

泄露发生并且上报后，在Java内存泄露/问题列表可以看到上报的问题，点击进入问题详情，查看上报详情。

Java内存泄露

大图分析

大图分析，监控进程中图片的过度解码情况。发现解码后的Bitmap的宽高大于承载其的View宽高时，会收集相关信息上报服务器。

可以参考BuglyProDemo，构造场景，使用小尺寸的View来展示大尺寸的图片。

大图分析

API说明

回调接口

1. 设置Crash处理回调

Bugly处理Crash异常时可以回调业务，业务可以在回调中加入自定义的逻辑，或提供额外信息跟随异常一起上报。

public interface CrashHandleListener {

    /**
     * Crash处理回调时，此接口返回的数据以附件的形式上报，附件名userExtraByteData
     * @param isNativeCrashed 是否Native异常
     * @param crashType 异常的类型
     * @param crashStack 异常堆栈
     * @param nativeSiCode native异常时的SI_CODE，非Native异常此数据无效
     * @param crashTime native异常的发生时间
     * @return 上报的附件字节流
     */
    byte[] getCrashExtraData(boolean isNativeCrashed, String crashType, String crashAddress,
            String crashStack, int nativeSiCode, long crashTime);

    /**
     * Crash处理回调时，此接口返回的数据在附件extraMessage.txt中展示
     * @param isNativeCrashed 是否Native异常
     * @param crashType 异常的类型
     * @param crashStack 异常堆栈
     * @param nativeSiCode native异常时的SI_CODE，非Native异常此数据无效
     * @param crashTime native异常的发生时间
     * @return 上报的数据
     */
    String getCrashExtraMessage(boolean isNativeCrashed, String crashType, String crashAddress,
            String crashStack, int nativeSiCode, long crashTime);

    /**
     * Crash处理回调前，执行此接口
     * @param isNativeCrashed 是否Native异常
     */
    void onCrashHandleStart(boolean isNativeCrashed);

    /**
     * Crash处理回调后，执行此接口
     * @param isNativeCrashed 是否Native异常
     * @return 返回值没有实际作用，不影响方法正常使用，可忽略
     */
    boolean onCrashHandleEnd(boolean isNativeCrashed);

    /**
     * Crash处理回调时，执行此接口
     * @param isNativeCrashed 是否NativeCrash
     * @param crashType Crash类型
     * @param crashMsg Crash消息， 例如 “Attempt to invoke virtual method 'int java.lang.String.length()' on a null object reference” （4.4.1.2新增）
     * @param crashAddress Crash地址
     * @param crashStack Crash堆栈
     * @param nativeSiCode native异常时有效，SI_CODE
     * @param crashTime crash时间
     * @param userId crash时用户ID
     * @param deviceId crash时的设备ID
     * @param crashUuid 这条异常的唯一标识
     * @return 返回值没有实际作用，不影响方法正常使用，可忽略
     */
    boolean onCrashSaving(boolean isNativeCrashed, String crashType, String crashMsg, String crashAddress,
        String crashStack, int nativeSiCode, long crashTime, String userId, String deviceId,
        String crashUuid, String processName);
}

在初始化阶段，通过BuglyBuilder设置，如下所示：

CrashHandleListener crashHandleListener = xxx;
buglyBuilder.setCrashHandleListener(crashHandleListener);

2. 设置Crash上报回调

Bugly上报Crash异常时可以回调业务，业务可以在回调中加入自定义的逻辑。

public interface UploadHandleListener {

        /**
         * 上报开始时回调
         * @param requestKey 上报关键字
         */
        public void onUploadStart(int requestKey);

        /**
         * 上报结束后回调
         * @param requestKey 上报关键字  
         * @param responseKey 回包的关键字
         * @param sended 发送的字节流
         * @param recevied 接受的字节流
         * @param result true则上报成功，否则失败
         * @param exMsg 额外信息
         */
        public void onUploadEnd(int requestKey, int responseKey, long sended, long recevied, boolean result, String exMsg);
} 

在初始化阶段，通过BuglyBuilder设置，如下所示：

UploadHandleListener uploadHandleListener = null;
buglyBuilder.setUploadHandleListener(uploadHandleListener);

其他接口

其他接口的调用均需在Bugly初始化之后，初始化之前调用无效，Bugly提供其他接口功能如下。

1. 更新设备ID

/**
 * 更新设备id（初始化后）
 * @param context context
 * @param deviceId 设备id
 */
public static void updateUniqueId(Context context, String deviceId);

2. 更新用户ID

/**
 * 更新用户id（初始化后）
 * @param context context
 * @param userId 用户id
 */
public static void updateUserId(Context context, String userId);

3. 更新设备型号

Bugly SDK默认不获取手机型号，业务可以在合规获取到手机型号后通过该接口更新至Bugly。

/**
 * 更新设备型号（初始化后）
 * @param context context
 * @param model 设备型号
 */
public static void updateDeviceModel(Context context, String model);

4. 更新日志等级

/**
 * 更新日志等级（初始化后）
 * @param logLevel 日志等级，级别可从BuglyLogLevel中获取
 */
public static void updateLogLevel(int logLevel);

5. 上报自定义异常

如业务需要上报除Java Crash、Native Crash、ANR之外的错误，如C#异常等，可以通过自定义异常接口上报至Bugly，上报的数据在「错误」栏目中展示。

/**
 * 上报自定义异常
 * @param thread 出错线程, 默认当前线程
 * @param category 异常类型 u3d c# : 4 ｜ js : 8 ｜ cocos2d lua : 6
 * @param errorType 错误类型
 * @param errorMsg 错误信息
 * @param stack 出错堆栈
 * @param extraInfo 额外信息
 */
public static void postException(Thread thread, int category, String errorType, String errorMsg,
                                     String stack, Map<String, String> extraInfo);
public static void postException(int category, String errorType, String errorMsg,
                                     String stack, Map<String, String> extraInfo);

6. 上报Java catch异常

如业务在Java中通过try catch方式捕获到异常，希望上报到Bugly，可以使用上报Java catch异常接口，上报的数据在「错误」栏目中展示。

/**
 * 处理catch异常并上报.
 * @param thread 出错线程
 * @param exception 异常
 * @param extraMsg 额外信息
 * @param extraData 额外数据
 * @param enableAllThreadStack 开启全部线程抓栈，默认开启
 * @return 上报结果
 */
public static boolean handleCatchException(Thread thread, Throwable exception, String extraMsg,
                                               byte[] extraData, boolean enableAllThreadStack);
public static boolean handleCatchException(Thread thread, Throwable exception, String extraMsg,
                                               byte[] extraData);                                               

7. 设置个例标签

/**
 * 设置个例标签，来自Bugly管理台的标签ID
 * 1. 先在Bugly管理台添加标签，得到标签ID；
 * 2. 通过setCaseLabels设置标签ID，需要设置多个时，通过英文竖线分割；
 * 3. 异常个例上报时会同时上报这些标签ID；
 * 示例："123|456|789"
 * SDK版本: 4.3.2.9+
 * @param labels 个例标签
 */
public static void setCaseLabels(String labels);

8. 设置业务下钻

/**
 * 设置「业务下钻」标签，设置多个标签时通过英文的竖线分割
 * 最多只允许设置30个标签，超出时，只取前面30个
 * 每个标签最长不超过1024个字符，超出时会添加失败
 * 示例："test_one|test_two|test_three"
 * SDK版本: 4.4.1+
 * @param labels 业务下钻标签
 */
public static void setTestLabels(String labels);

9. 设置Java内存泄漏嫌疑对象（性能监控）

在开启Bugly Java内存泄漏监控后，可以通过如下接口设置疑似泄漏的对象给Bugly进行监控，若不设置该接口，Bugly只对Activity/Fragment对象的内存泄漏进行监控。

/**
 * 设置Java内存泄漏嫌疑对象
 * @param leakObj 嫌疑对象
 */
public static void startInspectLeakObj(Object leakObj);

10. 测试接口

Bugly SDK提供接口测试崩溃异常，业务在调试时可以使用该接口进行崩溃采集上报的测试。

/**
 * 测试crash
 * @param crashType crash类型，可填入Bugly.JAVA_CRASH、Bugly.NATIVE_CRASH、Bugly.ANR_CRASH
 */
public static void testCrash(@CrashTypeKey int crashType);

11. 业务自定义日志接口

Bugly SDK提供异常时业务自定义日志携带能力，业务可以在崩溃发生前（不含回调）调用以下接口写入自定义日志。

public class BuglyCustomLog {
    public static void v(String tag, String msg) {
        BuglyLog.v(tag, msg);
    }

    public static void d(String tag, String msg) {
        BuglyLog.d(tag, msg);
    }

    public static void i(String tag, String msg) {
        BuglyLog.i(tag, msg);
    }

    public static void w(String tag, String msg) {
        BuglyLog.w(tag, msg);
    }

    public static void e(String tag, String msg) {
        BuglyLog.e(tag, msg);
    }

    public static void e(String tag, String msg, Throwable throwable) {
        BuglyLog.e(tag, msg, throwable);
    }

    /**
     * 设置写入日志的缓存大小，日志将根据设置的缓存大小循环写入
     * @param size 日志缓存大小
     */
    public static void setCache(int size) {
        BuglyLog.setCache(size);
    }
}

在写入自定义日志后，如果进程发生异常，会将自定义日志进行上报展示，展示为 附件 中的 BuglyLog.zip。

BuglyLog

自定义数据

1. 添加/移除自定义数据（Crash监控）

Bugly支持业务添加自定义数据，可以保存在Crash发生时、或发生前的一些自定义环境信息。自定义数据会随异常一起上报，并在异常个例详情界面的「自定义字段」中展示。自定义数据最多支持50对key-value。

/**
 * 添加自定义数据
 * @param context context
 * @param key key
 * @param value value
 */
public static void putUserData(Context context, String key, String value);

如需移除自定义数据，可通过如下接口进行移除操作。

/**
 * 移除用户自定义数据.
 * @param key key
 * @return 如果存在，则返回对应key的值
 */
public static String removeUserData(Context context, String key);

2. 设置/更新自定义文件上传路径（Crash监控）

Bugly支持业务上传自定义大文件，并关联至异常个例。自定义文件的上传采用独立于异常上报的通道，对异常处理流程无干扰，且支持配置多个文件。业务可以在发生异常之前的任意时间段，通过如下接口设置/更新文件路径的数组。进程发生异常重启后，会上报这些自定义文件，在异常个例的「附件」中，展示为custom_log.zip。

/**
 * 设置或更新自定义文件路径数组
 * @param files 文件路径数组，最多10个文件，且压缩后大小不能超过10MB
 * @return 设置结果
 */
public static boolean setAdditionalAttachmentPaths(String[] files);

注意事项

该接口最多设置10个文件路径。
需上传文件压缩后的大小限制为10MB，若超过该大小，则不会被上传。
该接口可被多次调用，更新的文件路径会覆盖之前的值。
自定义文件的上传时机在进程二次启动时，与异常上报间存在一定延迟。
频繁发生崩溃异常会触发文件清理逻辑，可能会导致文件漏传。
可以通过配置设置自定义文件上传的采样率，配置方式可以参见《SDK配置使用指引》。

3. 进入/退出自定义场景（性能监控）

在性能监控中，业务可以自定义场景，并根据场景来执行特定的监控或回调操作。使用如下接口来进入、退出自定义场景。

/**
 * 进入自定义场景
 * @param sceneName 场景名称
 */
public static void enterScene(String sceneName);

/**
 * 退出自定义场景
 * @param sceneName 场景名称
 */
public static void exitScene(String sceneName);

注意事项

enterScene --- exitScene 期间，各监控能力监控到问题时，上报的场景取[自定义场景];
exitScene后, 各监控能力监控到问题时，上报的场景取[simpleName Of lastResumedActivity]；
推荐使用enterScene/exitScene成对调用，如下所示：
enterScene(A) --> exitScene(A) --> enterScene(B) --> exitScene(B)
如果没有使用成对调用，如下示例：

enterScene(A) --> 自定义场景为A
enterScene(B) --> 自定义场景为B
enterScene(C) --> 自定义场景为C
exitScene(B) --> 自定义场景为C
exitScene(C) --> 自定义场景为空
exitScene(A) --> 自定义场景为空

如果 sceneName 为空，直接返回。

4. 添加/移除自定义数据采集器（性能监控）

Bugly性能监控模块的自定义设置方式不同于Crash监控模块，性能监控模块的自定义数据支持两类，「自定义维度」与「自定义字段」。

自定义数据采集器

「自定义维度」 指由 SDK指定了三组Key（详细见ICustomDataEditor），每组10个。应用可以根据需要，选择合适的Key上报数据。在控制管理台，用户可以给这些Key设置别名，方便查看和分析。对于自定义维度，服务器存储时是一个字段，一个字段分开存储的。后续可以提供丰富的查询和分析能力。当前支持全局设置，或者数据上报前的回调设置。当前支持通过Bugly.getGlobalCustomDataEditor获取全局接口，设置自定义维度，也可以通过指标类回调（ICustomDataCollector）或问题类回调（ICustomDataCollectorForIssue），设置或者更新自定义维度。

「自定义字段」 指Key和Value都由应用自由设置，SDK不理解字段的类型，统一作为字符串存储。用户可以在控制管理台，在问题列表和问题详情，通过自定义字段查询包含指定内容的上报。当前只支持通过问题类回调ICustomDataCollectorForIssue，设置自定义字段。

全局设置 ：指应用可以随时调用全局设置接口，设置自定义维度，相同key的数据，重复设置表示更新。性能上报在需要上报时，会获取全局缓存的自定义维度数据。

可以通过如下接口来获取默认的全局自定义维度收集回调，并设置全局自定义维度。

/**
 * 获取全局自定义维度设置接口
 * @return 全局自定义维度设置类
 */
public static ICustomDataEditor getGlobalCustomDataEditor();

// 设置示例
ICustomDataEditor customDataEditor = Bugly.getGlobalCustomDataEditor();
customDataEditor.putStringParam(ICustomDataEditor.STRING_PARAM_1, getAppStateDesc());
customDataEditor.putNumberParam(ICustomDataEditor.NUMBER_PARAM_1, Debug.getPss());

回调设置：指应用设置回调，在监控到相关问题上报前，会回调应用的接口，应用根据具体的问题及场景，分别采集额外的现场信息。回调设置分为，指标类回调以及问题类回调。

// 添加回调，指标类回调和问题类回调需要分别设置。
Bugly.addCustomDataCollector(customDataEditor);

// 移除回调，指标类回调和问题类回调需要分别移除。
Bugly.removeCustomDataCollector(customDataDditor);

指标类回调：ICustomDataCollector，如卡顿指标，内存峰值属于指标类回调。会在信息采集，缓存数据前，回调应用是否需要补充额外信息。

/**
 * 设置指标数据回调，对于不同监控项、不同场景可设置多个
 * @param dataCollector 全局自定义数据回调类
 */
public static void addCustomDataCollector(ICustomDataCollector dataCollector);
/**
 * 移除全局自定义数据回调
 * @param dataCollector 全局自定义数据回调类
 */
public static void removeCustomDataCollector(ICustomDataCollector dataCollector);

// 设置示例
ICustomDataEditor customDataEditor = new ICustomDataCollector() {
    @Override
    public void collectCustomData(String pluginName, String scene, ICustomDataEditor customDataEditor) {
        customDataEditor.putStringParam(ICustomDataEditor.STRING_PARAM_1, getAppStateDesc());
        customDataEditor.putNumberParam(ICustomDataEditor.NUMBER_PARAM_1, Debug.getPss());
    }
};

// 设置指标类回调
Bugly.addCustomDataCollector(customDataEditor);
// 移除指标类回调
Bugly.removeCustomDataCollector(customDataDditor);

问题类回调：ICustomDataCollectorForIssue，如卡顿问题监控，Java内存泄露，大图分析属于问题类回调，会在监控到异常问题时，回调用户是否需要补充额外信息。

/**
 * 设置单个指标、问题自定义数据回调，对于不同监控项、不同场景可设置多个
 * @param issueDataCollector 单个指标、问题自定义数据回调类
 */
public static void addCustomDataCollector(ICustomDataCollectorForIssue issueDataCollector);
/**
 * 移除单个指标、问题自定义数据回调
 * @param issueDataCollector 单个指标、问题自定义数据回调类
 */
public static void removeCustomDataCollector(ICustomDataCollectorForIssue issueDataCollector);

// 设置示例
ICustomDataCollectorForIssue issueDataCollector = new ICustomDataCollectorForIssue() {
    @Override
    public void collectCustomData(String pluginName, String scene, ICustomDataEditorForIssue customDataEditor) {
        // 允许覆盖全局设置的自定义维度
        customDataEditor.putStringParam(ICustomDataEditor.STRING_PARAM_1, getAppStateDesc());
        customDataEditor.putNumberParam(ICustomDataEditor.NUMBER_PARAM_1, Debug.getPss());
    }
}
// 设置问题类回调
Bugly.addCustomDataCollector(issueDataCollector);
// 移除问题类回调
Bugly.removeCustomDataCollector(issueDataCollector);

动态开关

如业务需在指定场景中，动态开关Bugly Crash监控项或性能监控项，可以通过如下接口进行动态开关。但需注意，崩溃异常的动态开关非必要不应使用，会导致异常的漏报。

/**
 * crash监控动态开关
 * @param crashType crash类型，可填入Bugly.JAVA_CRASH、Bugly.NATIVE_CRASH、Bugly.ANR_CRASH
 * @param isAble true 打开，false 关闭
 */
public static void setCrashMonitorAble(@CrashTypeKey int crashType, boolean isAble);

/**
 * 性能监控动态开关(开关一组监控项)
 * @param monitorList 监控项list，可从BuglyMonitorName中获取
 * @param isAble true 打开，false 关闭
 */
public static void setPerformanceMonitorsAble(List<String> monitorList, boolean isAble);

/**
 * 性能监控动态开关(开关单个监控项)
 * @param monitorName 监控项
 * @param isAble true 打开，false 关闭
 */
public static void setPerformanceMonitorAble(String monitorName, boolean isAble);

/**
 * 停止所有的性能监控项
 */
public static void abolishPerformanceMonitors();

启动监控

默认情况下，启动监控取首个Activity的首帧渲染结束作为启动结束点，应用也可以通过reportAppFullLaunch接口自定义启动结束点。除此之外，AppLaunch还提供添加自定义标签接口，以及自定义打点接口。

AppLaunch appLaunch = AppLaunchProxy.getAppLaunch();
appLaunch.reportAppFullLaunch();

自定义标签，为本次启动数据添加自定义标签，方便后续做下钻分析，如下所示：

AppLaunch appLaunch = AppLaunchProxy.getAppLaunch();
appLaunch.addTag("show_splash");

自定义打点，即在启动过程中，针对启动流程，监控一些耗时任务。

AppLaunch appLaunch = AppLaunchProxy.getAppLaunch();
appLaunch.spanStart("login", null); // 登陆任务开始
....
appLaunch.spanStart("verification_code", "login"); // 验证码任务开始
....
appLaunch.spanEnd("verification_code"); // 验证码结束
....
appLaunch.spanEnd("login"); // 登陆结束

AppLaunch接口的详细说明：

public interface AppLaunch {
    /**
     * 开始启动监控
     * @param context Context
     */
    void install(Context context);

    /**
     * 添加自定义标签
     * @param tag 自定义标签
     */
    void addTag(String tag);

    /**
     * Span开始打点
     * @param spanName 开始打点的span名称
     * @param parentSpanName 当前要打点的span的父span的名称
     */
    void spanStart(String spanName, String parentSpanName);

    /**
     * Span结束打点
     * @param spanName 结束打点的span名称
     */
    void spanEnd(String spanName);

    /**
     * 标记启动完成
     */
    void reportAppFullLaunch();
}

Android SDK接入指引

接入前准备​

Demo示例​

步骤一：注册产品，获取AppID及AppKey​

步骤二：集成SDK​

自动集成（推荐）​

手动集成（不推荐）​

步骤三：初始化SDK​

步骤三：验证数据上报​

前提条件​

崩溃监控​

ANR监控​

OOM监控​

错误监控​

启动监控​

卡顿监控​

内存监控​

API说明​

回调接口​

1. 设置Crash处理回调​

2. 设置Crash上报回调​

其他接口​

1. 更新设备ID​

2. 更新用户ID​

3. 更新设备型号​

4. 更新日志等级​

5. 上报自定义异常​

6. 上报Java catch异常​

7. 设置个例标签​

8. 设置业务下钻​

9. 设置Java内存泄漏嫌疑对象（性能监控）​

10. 测试接口​

11. 业务自定义日志接口​

自定义数据​

1. 添加/移除自定义数据（Crash监控）​

2. 设置/更新自定义文件上传路径（Crash监控）​

3. 进入/退出自定义场景（性能监控）​

4. 添加/移除自定义数据采集器（性能监控）​

动态开关​

启动监控​

接入前准备

Demo示例

步骤一：注册产品，获取AppID及AppKey

步骤二：集成SDK

自动集成（推荐）

手动集成（不推荐）

步骤三：初始化SDK

步骤三：验证数据上报

前提条件

崩溃监控

ANR监控

OOM监控

错误监控

启动监控

卡顿监控

内存监控

API说明

回调接口

1. 设置Crash处理回调

2. 设置Crash上报回调

其他接口

1. 更新设备ID

2. 更新用户ID

3. 更新设备型号

4. 更新日志等级

5. 上报自定义异常

6. 上报Java catch异常

7. 设置个例标签

8. 设置业务下钻

9. 设置Java内存泄漏嫌疑对象（性能监控）

10. 测试接口

11. 业务自定义日志接口

自定义数据

1. 添加/移除自定义数据（Crash监控）

2. 设置/更新自定义文件上传路径（Crash监控）

3. 进入/退出自定义场景（性能监控）

4. 添加/移除自定义数据采集器（性能监控）

动态开关

启动监控