Advanced Topics Crash Reporter

Crash Reporter

AIBudsCrashReporter captures crash reports locally so the host app can discover them on a later launch, present an internal diagnostic flow, upload them through its own backend, and delete them after handling.

The module does not define product consent, upload transport, retention, or support access. Those remain host-app responsibilities.

Crash report lifecycle across launches

Crash capture happens in the failing launch; report discovery and product-controlled handling happen after the app starts again.

1. Install Early — Install one reporter from the application lifecycle.
2. Capture Crash — Persist the crash report locally when the process fails.
3. Relaunch App — Discover the previous-launch crash after startup.
4. Enumerate Reports — Read newest-first report paths outside startup-critical work.
5. Handle with Consent — Inspect or upload through the app-owned protected workflow.
6. Delete After Handling — Remove only an enumerated path after acknowledgement or expiry.

Install Early, Handle on the Next Launch

Install CrashReporterSDK once from the application lifecycle before feature work. With the default path, reports are stored under the app Documents directory at .aibuds/crash_logs. A custom root path is available when the app has a deliberate storage policy.

The last-crash callback reports the newest available path when the previous launch crashed. The report-list callback signals that the local list changed. Neither callback uploads or deletes a report.

Swift

CrashReporterSDK.install(
    withLastCrashReportCallback: { path in
        guard let path else { return }
        // Enqueue consent-aware inspection or upload outside this callback.
    },
    reportListUpdateCallback: {
        // Refresh internal diagnostic state.
    }
)

Objective-C

[AIBudsCrashReporterSDK
    installWithLastCrashReportCallback:^(NSString *_Nullable path) {
        if (path == nil) {
            return;
        }
        // Enqueue consent-aware inspection or upload outside this callback.
    }
              reportListUpdateCallback:^{
                  // Refresh internal diagnostic state.
              }];

All-in-One includes the module but still requires an explicit installCrashReporter call.

Report Ownership

allCrashReportPaths() returns report paths sorted newest first. Read or upload a report asynchronously, verify that the operation succeeded, and then call deleteCrashReport only for a path obtained from that list.

Do not pass arbitrary filesystem paths to deletion. Keep retries idempotent and retain a report until the backend acknowledges it or the retention policy expires it.

User Information

setUserInfo(_:forKey:) accepts String, Int, UInt, Double, Bool, and Date; values can be removed by key. Add only low-cardinality diagnostic context that is safe to store inside a crash report.

Avoid access tokens, transcripts, audio, email addresses, full device identifiers, precise location, and other personal data. Remove session-scoped values when the session ends so stale context is not attached to a later crash.

Privacy and Operations

• Obtain any consent required for collection and upload.
• Encrypt uploads and authenticate the support backend.
• Restrict local and server-side access.
• Define maximum report age and disk usage.
• Symbolicate with matching build artifacts on trusted infrastructure.
• Separate crash-report transport failures from application startup.
• Never deliberately trigger a crash in a production validation flow.

Validation Checklist

• Installation occurs once and early.
• Previous-launch reports are processed off the startup-critical path.
• Upload acknowledgement precedes deletion.
• Only enumerated report paths are deleted.
• User info excludes secrets and sensitive content.
• Session-scoped metadata is removed when no longer valid.
• Retention, consent, symbolication, and backend access are documented.
• Release-build crash capture is tested with an approved non-production scenario.