Crash Capture
Understand durable native crash capture, next-launch delivery, framework error candidates, retention, and privacy across the Ansight mobile SDKs.
Ansight crash capture records bounded native crash evidence in app-private storage and recovers it on the next process launch. It 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 Studio handoff is enabled, pending reports are delivered over the next eligible Studio session. .NET offline capture can also attach a report to the matching offline session.
- Reports are removed after successful handoff or retention expiry.
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. |
| Studio handoff | true | Delivers recovered reports during a later Studio 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() |
Disabling Studio 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, Studio 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.