ECat Android SDK使用文档#

ECat Android SDK使用文档
- 一、接入步骤
- 二、API说明
  - 2.1 ECat类
  - 2.2 ECatLog类

一、接入步骤#

1.1 SDK文件说明#

ecat.jar：Java层异常捕获和异常管理上传SDK
NDK：包含arm64-v8a/armeabi-v7a/x86/x86_64架构的so，其中：
- libECat.so：Native层异常捕获SDK

1.2 Android Studio SDK集成#

将SDK文件复制到app工程的libs目录下
在app的build.gradle中增加以下配置：

android {
	//Native配置
	sourceSets {
        main.jniLibs.srcDirs = ['libs']
    }
}
dependencies {
    //jar包配置
	implementation files('libs/ecat.jar')
}

注意：

导入NDK的架构必须与app工程包含的架构一致。

例如，app本身或第三方so库只包含“arm64-v8a”和“armeabi-v7a”架构，应删除libs下其他架构的ECat NDK，否则可能会发生“java.lang.UnsatisfiedLinkError”异常。

1.3 参数配置#

1.3.1 AndroidManifest.xml配置#

<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" /> 
<!--若启用内存泄漏检测，需要增加如下配置/-->
<application
    android:extractNativeLibs="true">
</application>

1.3.2 proguard混淆配置#

如果app使用了proguard混淆，需要在proguard-rules.pro中配置如下的混淆规则，避免ECat接口被混淆。

-keep class com.xx.ecat.** { *; }
-keep class sun.misc.** { *; }
-dontwarn sun.misc.**

1.4 初始化#

1.4.1 初始化配置类#

为方便配置信息管理，ECat增加了配置类，强烈建议在初始化前配置相关参数。配置示例：

import com.xx.ecat.api.CrashHandleCallback;
import com.xx.ecat.api.ECat;
import com.xx.ecat.api.UserConfig;

/********/

UserConfig userConfig = new UserConfig();
userConfig.setEnableDebugMode(true); //是否启用调试模式（默认：false，正式发布的版本请设置为fasle）
userConfig.setAppVersion("v2.0"); //应用版本
userConfig.setAppChannel("Channel"); //渠道
userConfig.setUserId("uid1000"); //用户id
userConfig.setEnableAllMonitor(true); //设置是否在初始化时开启所有崩溃检测(默认：true)
userConfig.setLagThreshold(5000); //卡顿阈值（单位：ms，有效值：2000-10000，默认：5000）

/**
 * 设置崩溃回调函数
 * 由于崩溃回调会阻塞崩溃线程，因此若在回调中执行异步逻辑，可能会执行失败。
 * @param callback
 * 崩溃回调的参数（json字符串），参数说明：
 * 示例：{"type":"NativeCrash","crashUuid":"7A9A5EB7-8705-4C68-BAAA-3C1DA35E3409"}
 * type：崩溃类型，取值范围：
 *     "NativeCrash"：Native崩溃
 *     "JavaCrash"：Java崩溃
 *     "ANR"：应用无响应
 * crashUuid：崩溃id，与对应异常数据的id相同
 *
 * @return 回调是否成功
 */
userConfig.setCrashHandleCallback(new CrashHandleCallback() {
    @Override
    public boolean onCrash(String crashInfo) {
        Log.e(TAG, "用户设置的崩溃时回调被调用 Function onCrash is called");
        Log.d(TAG, crashInfo);
        return true;
    }
});

1.4.2 调用初始化函数#

在项目Application类onCreate()中调用初始化函数

ECat.initCrashReport(getApplicationContext(), "平台分配的AppId", userConfig);

1.4.3 网络权限设置#

特别注意：为合规性要求，ECat初始化后默认不会上传数据！调用权限设置接口后才会上传数据

如果INTERNET权限需要用户授权，则在授权后调用（仅调用一次，下次打开应用后无需调用）
如果不需要用户授权，则在初始化后直接调用：

ECat.setPermission(getApplicationContext(), "INTERNET", true);

1.5 接入测试#

在初始化后，手动制造一个崩溃，运行app。

ECat.testNativeCrash();

在配置类中设置setEnableDebugMode(true)后，可在logcat中查看崩溃日志

也可在ECat平台->控制台->异常列表中查看数据。

1.6 符号文件上传#

如果项目有C/C++代码或者使用了Proguard混淆Java代码，建议上传符号文件。

有关符号文件的说明见《符号文件上传工具使用文档》

二、API说明#

2.1 ECat类#

该类提供ECat API接口

	/**
     * 设置是否允许使用ECat
     * @param b
     */
    public static void setEnableCrashlytics(boolean b);

    /**
     * 初始化ECat
     * @param context   上下文
     * @param appId     注册时申请的APPID
     * @param userConfig 用户自定义的配置
     */
    public static void initCrashReport(Context context, String appId, UserConfig userConfig);

    /**
     * 获取当前ECat SDK的版本
     */
    public static String getSdkVersion();

    /**
     * 测试Java层崩溃
     */
    public static void testJavaCrash();

    /**
     * 测试 NDK 层崩溃
     */
    public static void testNativeCrash();

    /**
     * 手动抛出异常信息
     * @param thread
     * @param crashType
     * @param crashName
     * @param msg
     * @param stacktrace
     */
    public static void postException(Thread thread, int crashType, String crashName, String msg, String stacktrace);

    /**
     * 用户捕获到异常时的手动抛出
     * @param th
     */
    public static void postCaughtException(Throwable th);

    /**
     * 上传捕获到的异常
     * @param throwable
     * @param thread 异常线程
     */
    public static void postCaughtException(Throwable throwable, Thread thread);

    /**
     * 自定义标签，用于标明App的某个“场景”。以最后设置的标签为准，标签id需大于0
     * @param tagId
     */
    public static void setUserSceneTag(int tagId);

    /**
     * 自定义Map参数，在发生异常时会随着异常信息一起上报并在页面展示。
     * @param userKey
     * @param userValue
     */
    public static void putUserData(String userKey, String userValue);

	//删除key
	public static void removeUserData(String key)

    /**
     * 设置当前用户 ID
     * @param str
     */
    public static void setUserId(String str);

    /**
     * 获取ECat内部的设备ID
     */
    public static String getDeviceId();

    /**
     * 设置卡顿阈值
     * @param threshold
     */
    public static void setLagThreshold(int threshold);

	/**
     * 开启所有异常检测
     */
	public static void startAllMonitor();

	/**
     * 关闭所有异常检测
     */
	public static void stopAllMonitor();
        
	/**
     * 停止检测卡顿
     * @param duration 停止持续时间（单位：秒），duration > 0时，经过duration时间后卡顿检测再次开启，否则不再开启
     */
	public static void stopLagMonitor(int duration);
    
	/**
     * 开启卡顿检测
     *
     */
    public static void startLagMonitor()
        
    /**
     * 设置app版本
     * @param str
     */
    public static void setAppVersion(String str);

    /**
     * 设置app渠道
     * @param str
     */
    public static void setAppChannel(String str);
        
    /**
     * 在用户同意权限申请后，设置对应权限状态。如不需要用户同意，可在初始化Crashlytics后设置
     * @param permission 目前支持 "READ_LOGS" / "INTERNET"
     * @param b 是否获取到permission
     */
    public static void setPermission(String permission, boolean b);

	/**
     * 设置崩溃回调函数
     * 由于崩溃回调会阻塞崩溃线程，因此若在回调中执行异步逻辑，可能会执行失败。
     * @param callback
     * 崩溃回调的参数（json字符串），参数说明：
     * 示例：{"type":"NativeCrash","crashUuid":"7A9A5EB7-8705-4C68-BAAA-3C1DA35E3409"}
     * type：崩溃类型，取值范围：
     *     "NativeCrash"：Native崩溃
     *     "JavaCrash"：Java崩溃
     *     "ANR"：应用无响应
     * crashUuid：崩溃id，与对应异常数据的id相同
     *
     * 返回值，true代表回调成功
     */
    public static void setCrashCallback(CrashHandleCallback callback)
        
	/**
     * 获取应用上次退出信息
     * @return 上次退出信息(json格式)，示例：{"type":"","crashUuid":"","crashTime":0,"finishCrashCallback":false}
     * 字段说明：
     * type：退出类型。取值范围：
     *      ""：无崩溃
     *      "NativeCrash"：Native崩溃
     *      "JavaCrash"：Java崩溃
     *      "ANR"：应用无响应
     * crashUuid：崩溃id。若上次退出类型为崩溃，则为该崩溃数据的id
     * crashTime：崩溃时间(单位：毫秒)。若上次退出类型为崩溃，则为该崩溃的时间
     * finishCrashCallback：是否完成崩溃回调。若上次崩溃后，执行了回调函数并且回调函数返回值为true，则为true，否则为false
     */
    public static String getLastExitInfo()

2.2 ECatLog类#

ECat提供了自定义Log的接口，使用方式与android.util.Log一致。用户传入TAG和日志内容。该日志将在Logcat输出，并在发生异常时上报。

	public static void v(String str1, String str2); //Verbose日志
    public static void d(String str1, String str2);	//Debug日志
    public static void i(String str1, String str2);	//Info日志
    public static void w(String str1, String str2);	//Warning日志
    public static void e(String str1, String str2); //Error日志

    /**
     * 指定在内存中存储的log的最大值，超过i的log将被输出到文件，超过i的历史文件将被删除
     * @param byteSize 单位(字节)
     */
    public static void setCache(int byteSize);

注意：

使用ECatLog接口时，为了减少磁盘IO次数，我们会先将日志缓存在内存中。当缓存大于一定阈值（默认10K），会将它持久化至文件。您可以通过setCache(int byteSize)接口设置缓存大小，范围为0-30K。例： ECatLog.setCache(12 * 1024) //将Cache设置为12K