Keep crash evidence after your app restarts
Recover native crash details and preceding breadcrumbs on the next launch so you can investigate an abnormal app exit.
An app crash should not erase the evidence you need to investigate it. Ansight preserves bounded native crash details in app-private storage and recovers them on the next process launch, with breadcrumbs that provide context from before the exit.
Crash capture is enabled by default in the core runtime options for .NET, Android, iOS, React Native, Flutter, and Cordova/Capacitor.
Crash capture is separate from ordinary timeline events. An exception event records something that happened while the process was running. A crash report connects a confirmed abnormal process exit with the previous process session and makes that evidence available after the app restarts.
Delivery Flow
- At startup, the native SDK creates a stable
processSessionIdand installs its platform crash hooks. - Lifecycle changes, screen views, and app events contribute bounded breadcrumbs.
- A native crash hook writes a minimal candidate to an app-private outbox without replacing the platform’s normal termination path.
- On the next launch, the SDK reconciles the previous process state and creates a durable report.
- When host handoff is enabled, pending reports are delivered over the next eligible host session. .NET offline capture can also attach a report to the matching offline session.
- Reports are removed after all required delivery destinations acknowledge them, or when retention/count limits expire.
The host saves recovered reports as crash-report session artifacts before
acknowledging them. A repeated handoff uses the same artifact identity. If the
original capture is unavailable, the delivering session retains the report with
its original process identifier.
The process-session identifier is intended for correlation across live sessions, offline sessions, and recovered crash evidence. It is not a user identifier.
Defaults and Bounds
| Option | Default | Validated range or behavior |
|---|---|---|
| Crash capture enabled | true | Disable explicitly when crash persistence is not appropriate. |
| Host handoff | true | Delivers recovered reports during a later host connection. |
| Offline-capture attachment | true | Used by supported offline-capture integrations. |
| Pending reports | 8 | Clamped to 1-32. |
| Retention | 7 days | Clamped to 1-30 days. |
| Breadcrumbs | 64 | Clamped to 0-256. |
| Trace bytes | 1 MiB | Clamped to 16 KiB-4 MiB. |
Configuration APIs
| SDK | Enable or configure | Disable |
|---|---|---|
| .NET | WithCrashCapture(CrashCaptureOptions) | WithoutCrashCapture() |
| Android | withCrashCapture(AnsightCrashCaptureOptions) | withoutCrashCapture() |
| iOS | withCrashCapture(AnsightCrashCaptureOptions) | withoutCrashCapture() |
| React Native | crashCapture or withCrashCapture(...) | crashCapture: false or withoutCrashCapture() |
| Flutter | AnsightCrashCaptureOptions or withCrashCapture(...) | withoutCrashCapture() |
| Cordova/Capacitor | crashCapture or withCrashCapture(...) | crashCapture: false or withoutCrashCapture() |
Set HostHandoffEnabled in .NET or hostHandoffEnabled in the other SDKs to control delivery to the host. Disabling host handoff does not itself disable local crash persistence. Set the top-level crash-capture option to disabled when the app must not create reports.
Framework Error Candidates
React Native, Flutter, and Cordova/Capacitor can add JavaScript or Dart error context to the native outbox with recordCrashCandidate(...). React Native’s installErrorHandlers(...), Flutter’s instrumentation error hooks, and Capacitor’s error-capture integration do this automatically for the framework errors they observe.
Non-fatal framework candidates are context for an independently confirmed native exit; they are not promoted to crash reports merely because an exception or rejected promise was recorded. Use ordinary exception events when an error should appear immediately in the current session timeline.
Privacy and Security
Crash reports can contain exception messages, stack traces, runtime names, breadcrumbs, screen names, and app-supplied metadata. Treat them as sensitive diagnostic data.
- Do not place access tokens, passwords, personal data, or full request bodies in exception messages, breadcrumbs, or candidate metadata.
- Keep breadcrumb and trace limits bounded.
- Disable crash capture, host handoff, or offline attachment when the app’s data-handling policy requires it.
- Clear app data to remove the app-private outbox from a test installation.
- Test recovery with a deliberate development-only crash; a normal debugger termination may not exercise the platform crash path.
Crash capture does not grant remote-tool access and does not weaken the configured tool guard.