# 接入指南

# 1.工具下载

在 SDK 下载页面点击下载 Android SDK
在 SDK 下载页面点击下载 NDK 动态库

# 2.导入依赖文件

# 步骤1

将下载后Android SDK压缩包中的Crasheye.jar文件拷贝到你的工程libs目录中,然后在 Android Studio 工程中展开libs文件夹,你就能看到刚才拷贝进去的Crasheye.jar文件,右键点击,选择Add As Library...,导入成功。

# 步骤2

  • 解压已下载完成的NDK动态库压缩文件进行解压。
  • 选择对应系统版本的文件
  • 在你工程的[jni]目录下创建[prebuild]文件夹,将[libCrasheyeNDK.so]文件拷贝到该文件夹下。

# 3.配置 AndroidManifest.xml 文件

AndroidManifest.xml 文件中添加 SDK 所需的配置 权限配置(必需) 渠道信息(可选)

<!--权限配置,必需>
<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_PHONE_STATE"/>
<uses-permission android:name="android.permission.READ_LOGS" />
<application ……>
    <activity ……/>
    <!--渠道信息,可选>
    <meta-data android:name="CRASHEYE_CHANNEL" android:value="Your_Channel"/>
</application>

# 4.初始化

# 步骤1

Android.mk文件中加入以下代码:

########################## 加载So文件 ##########################
include $(CLEAR_VARS)Android.mk
LOCAL_SRC_FILES := prebuild/libCrasheyeNDK.so
include $(PREBUILT_SHARED_LIBRARY)
########################## 加载So文件 ##########################

# 步骤2

在入口函数 Application.onCreate()或 MainActivity.onCreate()中添加如下代码

TIP

💡 需引入头文件 import com.xsj.crasheye.Crasheye

@override
public void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    Crasheye.initWithNativeHandle(this, "Your_AppKey");
}

TIP

👍 至此,Android NDK 异常捕获的接入工作就完成了。在你的 Android 设备上启动 APP,在 Crasheye 后台便能实时看到监控数据。

# 5.测试

请在真机上调试验证,在 Crasheye 后台便能实时看到监控数据。
启动您的 app 程序可以在 LogCat 中看到输出"init success!"和"ndk crash handler init success"等字样,如下图:

# 常用API

# Crasheye.setChannelID

设置渠道号

  • 你可以将渠道号信息配置在 AndroidManifest.xml 文件中,Crasheye 会自动读取你配置的信息并上报,参见配置 AndroidManifest.xml 文件。
  • 如果你不希望在 AndroidManifest.xml 中写入渠道信息,你也可以通过直接调用 API 的方式进行设置,代码示例如下:
@override
public void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    Crasheye.setChannelID("Your_Channel");
    Crasheye.init(this, "Your_AppKey");
}

# Crasheye.setAppVersion

设置 App 版本号

  • Crasheye 默认会读取 AndroidManifest.xml 中配置的 android:versionName 版本号信息,当然你也可以通过调用 API 自行设置:
@override
public void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    Crasheye.setAppVersion("Your_APP_Version");
    Crasheye.init(this, "Your_AppKey");
}

# Crasheye.setFlushOnlyOverWiFi

设置仅在 Wifi 环境下上报

  • 为了节省用户在非 wifi 环境下的网络流量,Crasheye 提供接口可使崩溃后的堆栈信息仅在手机链接 Wifi 的情况下才上报:
@override
public void onCreate(Bundle savedInstanceState) {
// true:仅在wifi下上报;false:所有网络均上报。 默认值为false
    super.onCreate(savedInstanceState);
    Crasheye.setFlushOnlyOverWiFi(true);
    Crasheye.init(this, "Your_AppKey");
}

# Crasheye.setUserIdentifier

设置用户标识

  • 为每一条上报记录设置用户标识,可以方便后期筛选和定位问题,比如开发人员想看到自己手机上报的崩溃信息,就可以采用这种方式:
Crasheye.setUserIdentifier(String userIdentifier);

# Crasheye.setLogging

设置收集 log 日志

  • 此接口主要是收集运行中的 logcat 日志,当发现异常时会把收集到的 log 信息保存起来,并一同上传至服务器;(接口最大支持收集 1000 行最新的 log 日志)
/**
* 设置获取log日志 获取行数和获取的关键字
* @param lines        获取的行数(最大收集1000行)
* @param filter        获取的关键字(可不传) 。例如:filter 是"Crasheye"就相当于LogCat过滤栏中输入“logcat -d Crasheye”
*/
Crasheye.setLogging(int lines, String filter);

# Crasheye.leaveBreadcrumb

添加面包屑(打点信息)

  • 您可以在您的代码中添加多个面包屑(打点信息)然后在 Crasheye 平台上查看面包屑(打点信息)的时间和顺序,这样您就可以监视到您的项目是否按照您的预设跑了!只需要在每个您想监视的地方调用如下 API 即可:
Crasheye.leaveBreadcrumb(String breadcrumb);

# Crasheye.addExtraData

添加自定义数据

  • 如果您觉得 Crasheye 默认捕获的数据还不足以满足您的要求的话,您可以添加自定义数据,只需要调用如下 API 即可:
Crasheye.addExtraData(String key, String value);

# Crasheye.sendScriptException

主动上报脚本信息接口

  • 此接口主要是给开发者主动调用,在捕获到的异常堆栈信息时,如:lua、js 等脚本异常,可以通过调用接口上报至服务端。(为了减少重复上报,相同的异常信息在 10 分钟内只能上报一次)
/**
* 脚本上报接口
* @param errorTile 错误脚本的标题
* @param stacktrace 堆栈信息
* @param language 脚本语言
*/
Crasheye.sendScriptException(String errorTitle, String stacktrace, String language);

# Crasheye.setNDKExceptionCallback

NDK 异常回调函数

  • 当发生 ndk 异常时,Crasheye 会回调执行用户指定的函数,收集一些需要的信息。
/**
* 设置NDK异常回调函数
* @param ndkExceiptn 需要实现 NDKExceptionCallback 接口
*/
Crasheye.setNDKExceptionCallback(NDKExceptionCallback ndkExceiptn);

# Crasheye.getCrasheyeUUID

获取设备 ID 信息

  • 此接口是用户获取当前手机的设备 ID 信息,通过此设备 ID 信息可以通过页面搜索,找到对应的机器异常信息。
Crasheye.getCrasheyeUUID();

# Crasheye.setIsBetaVersion

设置测试版本

/**
* 设置该版本是否为测试版本
* @param isBeta 是否为测试版本
*/
Crasheye.setIsBetaVersion(boolean isBeta)

# 符号文件上传

# 符号文件

为何需要上传符号文件?

如果在Android工程中用到了c/c++代码, 捕获上传的堆栈信息是难以理解的信息,需要配合Mapping.txt文件及工程中生成的符号文件进行解析,解析之后才能看懂。

符号文件在哪里?

Debug SO 文件(具有调试信息的 SO 文件)(符号文件),其位置如下:

  • 如果 IDE 为 Eclipse + NDK,默认情况下,Debug SO 文件位于:
    <项目文件夹>/obj/local/<架构>/

  • 如果 IDE 为 Android + NDK,默认情况下,Debug 编译的 Debug SO 文件位于:
    <项目文件夹>/build/intermediates/ndk/debug/obj/local/<架构>/

  • Release 编译的 Debug SO 文件位于:
    <项目文件夹>/build/intermediates/ndk/release/obj/local/<架构>/

# 工具上传

  1. 环境要求 Java SE Runtime Environment 7 (opens new window)或以上
  2. 下载 符号文件上传工具
  3. 运行符号文件工具,具体参数如下
参数 说明
-appkey 项目的 appkey
[-veresion] 应用版本(可选),默认从项目 AndroidManifest.xml 中读取
[-AndroidManifestPath] AndroidManifest.xml 路径(用于读取应用版本号,与-version 参数互斥)(可选)
[-disableUpload] 不上传符号文件
[-dumpsyms] dsym 分析程序 dump_syms 位置,默认指向当前工作目录
java -jar CrasheyeAndroidSymbol.jar -appkey=项目的AppKey [-version=应用版本号] [-AndroidManifestPath=AndroidManifest.xml路径] 符号文件路径
  1. 上传成功

# 网页上传

  1. 运行符号文件上传工具,生成zip包
java -jar CrasheyeAndroidSymbol.jar -disableUpload 符号文件路径
  1. 在Crasheye后台中进行上传(设置 - 符号文件 - 符号文件上传)
上次更新: 2023/9/13 14:06:01