Android 异常上报

概述

本文档介绍 Flashcat Android RUM SDK 的异常捕获机制，包括 Java/Kotlin 崩溃、NDK 原生崩溃、ANR（应用无响应）报告、手动错误上报以及获取脱混淆的堆栈跟踪。

异常类型

Flashcat Android RUM 可以监控以下类型的异常：

Java/Kotlin 崩溃

SDK 自动捕获未处理的 Java/Kotlin 异常，包括：

运行时异常（如 NullPointerException、IndexOutOfBoundsException）

未捕获的异常

应用崩溃

NDK 崩溃（Native Crash）

若您的应用使用了原生代码（C/C++），SDK 支持捕获 NDK 崩溃并将其纳入异常追踪。

ANR（应用无响应）

SDK 可以检测并报告 ANR 问题，帮助您发现主线程阻塞导致的用户体验问题。

自定义错误

除了自动捕获的异常外，您还可以使用 RUM SDK 手动上报自定义异常，用于跟踪业务逻辑错误等特定问题。

配置崩溃报告

基础配置

确保您已按照 SDK 接入指南完成基础 SDK 集成。崩溃报告功能默认启用，SDK 会自动捕获应用中的未处理异常。

添加 NDK 崩溃报告

若您的应用包含原生代码（C/C++），需要添加 NDK 崩溃报告模块来捕获原生崩溃。

步骤 1：添加依赖

在您的应用模块的 build.gradle 文件中添加 NDK 崩溃报告依赖：

步骤 2：启用 NDK 崩溃报告

在 SDK 初始化后启用 NDK 崩溃报告：

添加 ANR 报告

ANR（Application Not Responding）是指应用主线程被阻塞超过一定时间，导致应用无法响应用户输入的情况。

启用 ANR 检测

在 RUM 配置中启用 ANR 检测：

提示

ANR 检测会监控主线程的响应性。当检测到主线程阻塞超过阈值时，SDK 会自动记录 ANR 事件。

手动错误上报

通过 addError API，您可以手动上报已处理的异常、自定义错误或其他未被自动捕获的错误。

上报错误示例

错误来源类型

RumErrorSource 可选值：

值	描述
`RumErrorSource.NETWORK`	网络错误
`RumErrorSource.SOURCE`	源码错误
`RumErrorSource.CONSOLE`	控制台错误
`RumErrorSource.LOGGER`	日志错误
`RumErrorSource.AGENT`	Agent 错误
`RumErrorSource.WEBVIEW`	WebView 错误
`RumErrorSource.CUSTOM`	自定义错误

上报网络错误示例

获取脱混淆的堆栈跟踪

如果您的应用启用了代码混淆（ProGuard/R8），上报的崩溃堆栈将被混淆。通过上传 mapping 文件，可以将混淆后的堆栈还原为原始的类名、方法名和行号。

配置 Gradle 插件

步骤 1：添加插件依赖

在项目根目录的 build.gradle 文件中添加 Flashcat Gradle 插件：

步骤 2：应用插件

在应用模块的 build.gradle 文件中应用插件：

步骤 3：配置插件

在 build.gradle 文件中配置 Flashcat 插件：

上传 Mapping 文件

配置完成后，插件会在构建过程中自动上传 mapping 文件。您也可以手动运行上传任务：

例如，对于 release 变体：

上传 NDK 符号文件

如果您使用了 NDK 崩溃报告，还需要上传 NDK 符号文件以获取可读的原生堆栈：

插件配置选项

属性名	描述
`versionName`	应用版本名称（默认取 `android` 块中声明的版本）
`serviceName`	服务名称（默认取应用包名）
`site`	数据上报站点
`checkProjectDependencies`	控制插件是否检查 Flashcat SDK 依赖。可选值：`none`（忽略）、`warn`（警告）、`fail`（失败，默认）

Mapping 文件大小限制

Mapping 文件大小限制为 500 MB。如果文件过大，可以使用以下选项减小文件大小：

提示

使用 mappingFilePackageAliases 时，Flashcat 异常追踪中的堆栈将使用别名替代原始包名。建议仅对第三方依赖使用此选项。

追踪后台事件

默认情况下，只有在视图处于活动状态时发生的崩溃才会被追踪。如果您希望追踪应用在后台时发生的崩溃，可以启用后台事件追踪：

警告

追踪后台事件可能会产生额外的会话，这可能会影响计费。如有疑问，请联系 Flashcat 支持团队。

限制与注意事项

崩溃检测限制

SDK 初始化时机：崩溃只有在 SDK 初始化之后才能被检测到。建议在 Application.onCreate() 中尽早初始化 SDK。

视图关联：崩溃必须与一个 RUM 视图关联。若在视图显示前或应用被置于后台后发生崩溃，该崩溃可能不会被报告。可通过 trackBackgroundEvents(true) 缓解这一问题。

采样率影响：只有被采样的会话中的崩溃才会被保留。如果会话采样率不是 100%，部分崩溃可能不会被报告。

符号化限制

确保 mapping 文件在每次发布新版本时都正确上传。

不同构建变体（如 debug/release）需要分别上传对应的 mapping 文件。

NDK 符号文件需要包含调试信息才能正确符号化。

测试验证

验证 Java/Kotlin 崩溃

在应用中添加测试代码触发崩溃：

运行应用并触发崩溃

重启应用，等待 SDK 上传崩溃报告

在 Flashcat 控制台的异常追踪模块中查看崩溃报告

验证 NDK 崩溃

在原生代码中添加测试崩溃：

从 Java/Kotlin 代码调用该原生方法

重启应用，等待 SDK 上传崩溃报告

确认堆栈是否已被正确符号化（显示函数名、文件名和行号）

验证 ANR

在主线程执行耗时操作：

触发该操作后尝试与应用交互

检查 Flashcat 控制台是否收到 ANR 报告

错误数据结构

每条错误数据包含以下属性：

属性	类型	描述
`error.source`	string	错误来源（如 `source`、`network`、`custom`）
`error.type`	string	错误类型或错误码（如 `NullPointerException`）
`error.message`	string	错误消息
`error.stack`	string	错误堆栈跟踪
`error.is_crash`	boolean	是否为崩溃
`context`	Object	自定义上下文信息，通过 `addError` 的 `attributes` 传入

最佳实践

尽早初始化 SDK：在 Application.onCreate() 中初始化 SDK，确保能捕获尽可能多的崩溃。

启用后台事件追踪：如果您的应用有大量后台操作，建议启用 trackBackgroundEvents。

正确上传符号文件：

为每个发布版本上传对应的 mapping 文件

如果使用 NDK，同时上传 NDK 符号文件

在 CI/CD 流程中集成符号文件上传

丰富错误上下文：在手动上报错误时，附加业务相关的上下文信息（如用户 ID、操作类型）。

过滤无关错误：使用 setErrorEventMapper 过滤第三方 SDK 或无关的错误，减少噪音。

下一步

查看异常

Android SDK 高级配置

Android

Android 异常上报#

概述#

异常类型#

Java/Kotlin 崩溃#

NDK 崩溃（Native Crash）#

ANR（应用无响应）#

自定义错误#

配置崩溃报告#

基础配置#

添加 NDK 崩溃报告#

步骤 1：添加依赖#

步骤 2：启用 NDK 崩溃报告#

添加 ANR 报告#

启用 ANR 检测#

手动错误上报#

上报错误示例#

错误来源类型#

上报网络错误示例#

获取脱混淆的堆栈跟踪#

配置 Gradle 插件#

步骤 1：添加插件依赖#

步骤 2：应用插件#

步骤 3：配置插件#

上传 Mapping 文件#

上传 NDK 符号文件#

插件配置选项#

Mapping 文件大小限制#

追踪后台事件#

限制与注意事项#

崩溃检测限制#

符号化限制#

测试验证#

验证 Java/Kotlin 崩溃#

验证 NDK 崩溃#

验证 ANR#

错误数据结构#

最佳实践#

下一步#

Android 异常上报

概述

异常类型

Java/Kotlin 崩溃

NDK 崩溃（Native Crash）

ANR（应用无响应）

自定义错误

配置崩溃报告

基础配置

添加 NDK 崩溃报告

步骤 1：添加依赖

步骤 2：启用 NDK 崩溃报告

添加 ANR 报告

启用 ANR 检测

手动错误上报

上报错误示例

错误来源类型

上报网络错误示例

获取脱混淆的堆栈跟踪

配置 Gradle 插件

步骤 1：添加插件依赖

步骤 2：应用插件

步骤 3：配置插件

上传 Mapping 文件

上传 NDK 符号文件

插件配置选项

Mapping 文件大小限制

追踪后台事件

限制与注意事项

崩溃检测限制

符号化限制

测试验证

验证 Java/Kotlin 崩溃

验证 NDK 崩溃

验证 ANR

错误数据结构

最佳实践

下一步