CrashHeal Flutter SDK

CrashHeal is a lightweight Flutter SDK for crash capture, normalization, local persistence, deduplication, and periodic upload to the CrashHeal backend.

Public API

await CrashHeal.init(
  apiKey: '...',
  endpoint: '...',
  environment: 'production',
);

await CrashHeal.captureException(error, stackTrace);

Automatic repo/branch/commit info

repoName, commitHash, and branchName are optional and CrashHeal resolves them automatically - no setup required in the integrating app:

  • Android: android/build.gradle.kts in this package shells out to git against the consuming app's checkout at build time and bakes the result into BuildConfig; CrashHeal.init() reads it via a MethodChannel.
  • iOS: ios/crash_heal.podspec's script_phase does the same at pod build time, writing the result into CrashHealGitInfo.swift; CrashHealPlugin.swift reads it via the same MethodChannel.

Both are real zero-config automation - just flutter pub add crash_heal and call CrashHeal.init().

If the native channel doesn't return a value (any platform without the plugin wired up, e.g. web/desktop/tests), CrashHeal falls back to --dart-define=CRASH_HEAL_REPO/CRASH_HEAL_COMMIT/CRASH_HEAL_BRANCH, which you can populate automatically from git using tool/build.sh (run from the repo, it cds into example/ for you):

tool/build.sh run                # flutter run, with git info injected
tool/build.sh build apk          # flutter build apk, with git info injected

On Android/iOS this dart-define layer is redundant (the native paths above already handle it) but still useful on web/desktop/tests, or to override what the native lookup found. If nothing resolves a value, repoName defaults to 'unknown' and commitHash/branchName stay null.

Launching from the IDE (Run/Debug button)

Android and iOS both get real values with no setup via the native paths above, so clicking Run/Debug in Android Studio/Xcode just works. To override what the native lookup found (or to supply values on web/desktop), pass --dart-define-from-file yourself, e.g. by generating a file with tool/gen_dart_define.sh and adding --dart-define-from-file=<path> to the run configuration's additional args.

Notes

  • Local persistence uses a file-backed store for simplicity and portability.
  • Global crash handlers are available via CrashHeal.installGlobalHandlers().
  • The SDK keeps pending crashes locally until the backend accepts them.

Libraries

crash_heal