iOS - Flashduty Docs

This document covers the error capture mechanisms of the iOS RUM SDK, helping you monitor and diagnose crashes and errors in iOS applications.

The SDK supports automatic capture of application crashes, App Hangs (application freezes), and Watchdog terminations, while also providing manual error reporting and dSYM symbolication features.

Error Types

iOS RUM can monitor the following types of errors:

Application Crashes

The SDK automatically captures unhandled exceptions and fatal signals, including:

Uncaught Swift/Objective-C exceptions
Fatal signals (e.g., SIGSEGV, SIGABRT)
Mach exceptions

App Hangs

When the main thread is blocked beyond a specified threshold, the SDK detects and reports App Hang events, helping you identify stuttering issues that affect user experience.

Watchdog Terminations

iOS’s Watchdog mechanism terminates applications that are unresponsive for extended periods. The SDK can detect these terminations and report them as crash events.

Custom Errors

In addition to automatically captured exceptions, you can use the RUM SDK to manually report custom errors for tracking business logic errors and other specific issues.

Configure Crash Reporting

Add Crash Reporting Module

To enable crash reporting, you need to add the FlashcatCrashReporting module.

Swift Package Manager

When adding package dependencies in Xcode, include the following modules:

FlashcatCore: Core SDK
FlashcatRUM: RUM functionality module
FlashcatCrashReporting: Crash reporting module

Initialize Crash Reporting

Enable crash reporting after SDK initialization:

AppDelegate.swift

import FlashcatCore
import FlashcatRUM
import FlashcatCrashReporting

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

        // Enable crash reporting
        CrashReporting.enable()

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

        return true
    }
}

It’s recommended to initialize the SDK and crash reporting as early as possible in application(_:didFinishLaunchingWithOptions:) to ensure crashes during app startup are captured.

Configure App Hangs Detection

App Hang refers to situations where the main thread is blocked, causing the application to become unresponsive to user input. The SDK can detect and report these issues.

Enable App Hangs Tracking

Set the appHangThreshold parameter in the RUM configuration:

import FlashcatRUM

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

App Hang Threshold Settings

Threshold	Description	Use Case
`0.25`	250 milliseconds, detects minor stuttering	Apps with extremely high smoothness requirements
`1.0`	1 second, detects noticeable stuttering	Recommended value for general apps
`nil`	Disable App Hang detection	Default setting

Configuration Recommendations:

Setting too low a threshold may generate excessive reports; adjust based on your app’s actual needs
If an App Hang causes the app to be terminated by Watchdog, the event will be marked as a crash type

Configure Watchdog Termination Tracking

iOS’s Watchdog mechanism terminates applications that are unresponsive for extended periods. The SDK can detect and report these terminations on the next app launch.

Enable Watchdog Termination Tracking

import FlashcatRUM

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

Watchdog Termination Detection Conditions

The SDK will classify the previous app termination as a Watchdog termination when all of the following conditions are met:

The app was not force-quit by the user
No crash or fatal error occurred during the last run
The app was not upgraded
The app was in the foreground and responding to events

Manual Error Reporting

Using the addError API, you can manually report handled exceptions, custom errors, or other errors not automatically captured.

Error Reporting Example

import FlashcatRUM

// Report an error with context
RUMMonitor.shared().addError(
    message: "Network request failed",
    type: "NetworkError",
    source: .network,
    attributes: [
        "url": "https://api.example.com",
        "status_code": 500,
        "userId": "12345"
    ]
)

Error Source Types

Source	Description
`.source`	Source error
`.network`	Network error
`.webview`	WebView error
`.console`	Console error
`.custom`	Custom error

Exception Object Reporting Example

import FlashcatRUM

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

Get Symbolicated Stack Traces

Crash report stacks are memory addresses by default. By uploading dSYM symbol files, you can convert these addresses to readable function names, file names, and line numbers.

What are dSYM Files

dSYM (Debug Symbol) files contain the application’s debug symbol information, used to map memory addresses in crash stacks to source code locations.

Upload dSYM Using Command Line Tool

Install flashcat-ci Tool

npm install -g @flashcat/flashcat-ci

Upload dSYM Files

export FLASHCAT_API_KEY="<API_KEY>"

flashcat-ci dsyms upload /path/to/dSYMs

Supported File Formats:

.dSYM directories
.dSYM.zip archives
.zip archives containing multiple dSYMs

Integrate dSYM Upload in CI/CD

Xcode Build Phase Script

Add a Run Script in your Xcode project’s Build Phases:

#!/bin/bash

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

Fastlane Integration

Add an upload step in your Fastfile:

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

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

dSYM for Bitcode Apps

If your app has Bitcode enabled, Apple will recompile the app during App Store processing, generating new dSYM files. You need to download these dSYMs from App Store Connect and upload them.

Download Bitcode dSYM

Visit App Store Connect and log in to your account.

Select Build Version

Go to your app → Activity → Select the build version for which you need to download dSYMs.

Download dSYM

Click the “Download dSYM” button, then upload using the flashcat-ci tool after download completes.

dSYM File Limitations

Each dSYM file size is limited to 2 GB
Only crashes from real devices support symbolication; crashes from simulators are not supported

Track Background Events

By default, only crashes that occur when a view is active are tracked. If you want to track crashes that occur when the app is in the background, enable background event tracking:

import FlashcatRUM

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

Tracking background events may generate additional sessions, which could affect billing. If you have questions, please contact the Flashcat support team.

Limitations and Considerations

Crash Detection Limitations

SDK Initialization Timing: Crashes can only be detected after SDK initialization and CrashReporting.enable() is called. It’s recommended to initialize as early as possible.
Debugger Interference: When the Xcode debugger is attached, crashes are captured by the debugger rather than the SDK. Test crash reporting by running the app without the debugger attached.
Crash Report Upload Timing: Crash reports are uploaded on the next app launch, so the app needs to be restarted after a crash to see the report.

Symbolication Limitations

Only crashes from real devices support symbolication; crashes from simulators are not supported.
Each release version requires uploading the corresponding dSYM files.
If using Bitcode, you need to download and upload the regenerated dSYMs from App Store Connect.

App Hang Detection Limitations

App Hang detection only works when the app is in the foreground.
Detection accuracy depends on threshold settings; too low a threshold may generate many false positives.

Testing and Verification

Verify Crash Reporting

Run app without debugger attached: Stop the app from Xcode, then launch directly from the device.
Trigger a test crash:

func triggerTestCrash() {
    fatalError("Test crash")
}

Restart the app: After the crash occurs, restart the app from the device and wait for the SDK to upload the crash report.
View the report: Check the crash report in the Flashcat console’s Error Tracking module.

Verify App Hang

Execute a time-consuming operation on the main thread:

func blockMainThread() {
    Thread.sleep(forTimeInterval: 5)  // Block main thread for 5 seconds
}

Trigger this operation and try to interact with the app.
Check if the Flashcat console received the App Hang report.

Verify Symbolication

Ensure the corresponding version’s dSYM files have been uploaded.
Trigger a crash and view the report.
Confirm the stack shows function names, file names, and line numbers rather than raw memory addresses.

Error Data Structure

Each error record contains the following attributes:

Attribute	Type	Description
`error.source`	string	Error source (e.g., `source`, `network`, `custom`)
`error.type`	string	Error type (e.g., `NSException`, `Signal`)
`error.message`	string	Error message
`error.stack`	string	Error stack trace
`error.is_crash`	boolean	Whether it’s a crash
`context`	Object	Custom context information passed via `addError`’s `attributes`

Best Practices

Initialize SDK Early: Call Flashcat.initialize() and CrashReporting.enable() as early as possible in application(_:didFinishLaunchingWithOptions:).
Properly Upload dSYM:
- Upload corresponding dSYM files for each release version
- Integrate dSYM upload into your CI/CD pipeline
- If using Bitcode, promptly download and upload dSYMs from App Store Connect
Set Appropriate App Hang Threshold: Set a suitable threshold based on your app’s performance requirements to avoid excessive false positives.
Enrich Error Context: When manually reporting errors, attach business-related context information (e.g., user ID, operation type).
Disconnect Debugger When Testing: When verifying crash reporting functionality, ensure the Xcode debugger is not attached.

Quick Start

Analytics

SDK Integration

Performance

Error Tracking

Explorer

Session Replay

Best Practices

Others

​Error Types

​Application Crashes

​App Hangs

​Watchdog Terminations

​Custom Errors

​Configure Crash Reporting

​Add Crash Reporting Module

​Swift Package Manager

​Initialize Crash Reporting

​Configure App Hangs Detection

​Enable App Hangs Tracking

​App Hang Threshold Settings

​Configure Watchdog Termination Tracking

​Enable Watchdog Termination Tracking

​Watchdog Termination Detection Conditions

​Manual Error Reporting

​Error Reporting Example

​Error Source Types

​Exception Object Reporting Example

​Get Symbolicated Stack Traces

​What are dSYM Files

​Upload dSYM Using Command Line Tool

​Integrate dSYM Upload in CI/CD

​Xcode Build Phase Script

​Fastlane Integration

​dSYM for Bitcode Apps

​Download Bitcode dSYM

​dSYM File Limitations

​Track Background Events

​Limitations and Considerations

​Crash Detection Limitations

​Symbolication Limitations

​App Hang Detection Limitations

​Testing and Verification

​Verify Crash Reporting

​Verify App Hang

​Verify Symbolication

​Error Data Structure

​Best Practices

​Next Steps

View Errors

iOS SDK Advanced Configuration

Error Types

Application Crashes

App Hangs

Watchdog Terminations

Custom Errors

Configure Crash Reporting

Add Crash Reporting Module

Swift Package Manager

Initialize Crash Reporting

Configure App Hangs Detection

Enable App Hangs Tracking

App Hang Threshold Settings

Configure Watchdog Termination Tracking

Enable Watchdog Termination Tracking

Watchdog Termination Detection Conditions

Manual Error Reporting

Error Reporting Example

Error Source Types

Exception Object Reporting Example

Get Symbolicated Stack Traces

What are dSYM Files

Upload dSYM Using Command Line Tool

Integrate dSYM Upload in CI/CD

Xcode Build Phase Script

Fastlane Integration

dSYM for Bitcode Apps

Download Bitcode dSYM

dSYM File Limitations

Track Background Events

Limitations and Considerations

Crash Detection Limitations

Symbolication Limitations

App Hang Detection Limitations

Testing and Verification

Verify Crash Reporting

Verify App Hang

Verify Symbolication

Error Data Structure

Best Practices

Next Steps