iOS

​

异常类型

​

应用崩溃

• 未捕获的 Swift/Objective-C 异常
• 致命信号（如 SIGSEGV、SIGABRT）
• Mach 异常

​

App Hangs（应用挂起）

​

Watchdog 终止

​

自定义错误

​

配置崩溃报告

​

添加 Crash Reporting 模块

​

Swift Package Manager

• FlashcatCore：核心 SDK
• FlashcatRUM：RUM 功能模块
• FlashcatCrashReporting：崩溃报告模块

​

初始化崩溃报告

import FlashcatCore
import FlashcatRUM
import FlashcatCrashReporting

@main
class AppDelegate: UIResponder, UIApplicationDelegate {
    func application(
        _ application: UIApplication,
        didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
    ) -> Bool {
        // 初始化 Flashcat SDK
        Flashcat.initialize(
            with: Flashcat.Configuration(
                clientToken: "<CLIENT_TOKEN>",
                env: "<ENV_NAME>"
            ),
            trackingConsent: .granted
        )

        // 启用崩溃报告
        CrashReporting.enable()

        // 启用 RUM
        RUM.enable(
            with: RUM.Configuration(
                applicationID: "<RUM_APPLICATION_ID>"
            )
        )

        return true
    }
}

​

配置 App Hangs 检测

​

启用 App Hangs 追踪

import FlashcatRUM

RUM.enable(
    with: RUM.Configuration(
        applicationID: "<RUM_APPLICATION_ID>",
        appHangThreshold: 0.25  // 250 毫秒
    )
)

​

App Hang 阈值说明

​

配置 Watchdog 终止追踪

​

启用 Watchdog 终止追踪

import FlashcatRUM

RUM.enable(
    with: RUM.Configuration(
        applicationID: "<RUM_APPLICATION_ID>",
        trackWatchdogTerminations: true
    )
)

​

Watchdog 终止检测条件

• 应用不是被用户强制退出
• 上次运行未发生崩溃或 fatal error
• 应用未进行升级
• 应用在前台且正在响应事件

​

手动错误上报

​

上报错误示例

import FlashcatRUM

// 上报带有上下文的错误
RUMMonitor.shared().addError(
    message: "网络请求失败",
    type: "NetworkError",
    source: .network,
    attributes: [
        "url": "https://api.example.com",
        "status_code": 500,
        "userId": "12345"
    ]
)

​

错误来源类型

​

上报异常对象示例

import FlashcatRUM

do {
    try riskyOperation()
} catch {
    RUMMonitor.shared().addError(
        error: error,
        source: .source,
        attributes: [
            "operation": "riskyOperation",
            "timestamp": Date().timeIntervalSince1970
        ]
    )
}

​

获取符号化的堆栈跟踪

​

什么是 dSYM 文件

​

使用命令行工具上传 dSYM

npm install -g @flashcat/flashcat-ci

export FLASHCAT_API_KEY="<API_KEY>"

flashcat-ci dsyms upload /path/to/dSYMs

​

在 CI/CD 中集成 dSYM 上传

​

Xcode Build Phase 脚本

#!/bin/bash

if [ "$CONFIGURATION" = "Release" ]; then
    export FLASHCAT_API_KEY="<API_KEY>"
    flashcat-ci dsyms upload "${DWARF_DSYM_FOLDER_PATH}"
fi

​

Fastlane 集成

lane :upload_dsyms do
  ENV["FLASHCAT_API_KEY"] = "<API_KEY>"

  sh("flashcat-ci dsyms upload #{lane_context[SharedValues::DSYM_OUTPUT_PATH]}")
end

​

Bitcode 应用的 dSYM

​

下载 Bitcode dSYM

​

dSYM 文件限制

• 每个 dSYM 文件大小限制为 2 GB
• 仅真实设备上的崩溃支持符号化，模拟器生成的崩溃不支持

​

追踪后台事件

import FlashcatRUM

RUM.enable(
    with: RUM.Configuration(
        applicationID: "<RUM_APPLICATION_ID>",
        trackBackgroundEvents: true
    )
)

​

限制与注意事项

​

崩溃检测限制

• SDK 初始化时机：崩溃只有在 SDK 和 CrashReporting.enable() 调用之后才能被检测到。建议尽早初始化。
• 调试器干扰：在 Xcode 调试器连接时，崩溃会被调试器捕获而非 SDK。测试崩溃报告时，请在不连接调试器的情况下运行应用。
• 崩溃报告上传时机：崩溃报告会在应用下次启动时上传，因此崩溃发生后需要重新启动应用才能看到报告。

​

符号化限制

• 仅真实设备上的崩溃支持符号化，模拟器生成的崩溃不支持。
• 每个发布版本都需要上传对应的 dSYM 文件。
• 如果使用 Bitcode，需要从 App Store Connect 下载并上传重新生成的 dSYM。

​

App Hang 检测限制

• App Hang 检测仅在应用处于前台时有效。
• 检测精度取决于阈值设置，过低的阈值可能产生大量误报。

​

测试验证

​

验证崩溃报告

1. 不连接调试器运行应用：从 Xcode 停止应用，然后从设备上直接启动。
2. 触发测试崩溃：

func triggerTestCrash() {
    fatalError("测试崩溃")
}

3. 重启应用：崩溃发生后，从设备上重新启动应用，等待 SDK 上传崩溃报告。
4. 查看报告：在 Flashcat 控制台的异常追踪模块中查看崩溃报告。

​

验证 App Hang

1. 在主线程执行耗时操作：

func blockMainThread() {
    Thread.sleep(forTimeInterval: 5)  // 阻塞主线程 5 秒
}

2. 触发该操作后尝试与应用交互。
3. 检查 Flashcat 控制台是否收到 App Hang 报告。

​

验证符号化

1. 确保已上传对应版本的 dSYM 文件。
2. 触发崩溃并查看报告。
3. 确认堆栈中显示的是函数名、文件名和行号，而非纯内存地址。

​

错误数据结构

​

最佳实践

1. 尽早初始化 SDK：在 application(_:didFinishLaunchingWithOptions:) 中尽早调用 Flashcat.initialize() 和 CrashReporting.enable()。
2. 正确上传 dSYM：
   • 为每个发布版本上传对应的 dSYM 文件
   • 在 CI/CD 流程中集成 dSYM 上传
   • 如果使用 Bitcode，及时从 App Store Connect 下载并上传 dSYM
3. 合理设置 App Hang 阈值：根据应用性能要求设置合适的阈值，避免过多误报。
4. 丰富错误上下文：在手动上报错误时，附加业务相关的上下文信息（如用户 ID、操作类型）。
5. 测试时断开调试器：验证崩溃报告功能时，确保不连接 Xcode 调试器。

​

下一步