{"id":13611619,"url":"https://github.com/skydoves/snitcher","last_synced_at":"2025-07-24T16:39:37.161Z","repository":{"id":189441742,"uuid":"680687316","full_name":"skydoves/snitcher","owner":"skydoves","description":"🦉 Snitcher captures global crashes, enabling easy redirection to the exception tracing screen for swift recovery.","archived":false,"fork":false,"pushed_at":"2023-10-02T03:13:37.000Z","size":1120,"stargazers_count":226,"open_issues_count":0,"forks_count":6,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-03-24T09:45:10.050Z","etag":null,"topics":["android","compose","exceptions","exceptions-handling","jetpack-compose","kotlin","library","skydoves","throwable"],"latest_commit_sha":null,"homepage":"https://skydoves.github.io/snitcher/","language":"Kotlin","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/skydoves.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null},"funding":{"github":"skydoves"}},"created_at":"2023-08-20T04:18:25.000Z","updated_at":"2025-02-22T09:10:23.000Z","dependencies_parsed_at":"2023-08-20T05:44:44.364Z","dependency_job_id":null,"html_url":"https://github.com/skydoves/snitcher","commit_stats":null,"previous_names":["skydoves/snitcher"],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/skydoves%2Fsnitcher","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/skydoves%2Fsnitcher/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/skydoves%2Fsnitcher/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/skydoves%2Fsnitcher/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/skydoves","download_url":"https://codeload.github.com/skydoves/snitcher/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248670282,"owners_count":21142895,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["android","compose","exceptions","exceptions-handling","jetpack-compose","kotlin","library","skydoves","throwable"],"created_at":"2024-08-01T19:01:59.043Z","updated_at":"2025-04-13T05:30:44.712Z","avatar_url":"https://github.com/skydoves.png","language":"Kotlin","readme":"\u003ch1 align=\"center\"\u003eSnitcher\u003c/h1\u003e\u003c/br\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://opensource.org/licenses/Apache-2.0\"\u003e\u003cimg alt=\"License\" src=\"https://img.shields.io/badge/License-Apache%202.0-blue.svg\"/\u003e\u003c/a\u003e\n  \u003ca href=\"https://android-arsenal.com/api?level=21\"\u003e\u003cimg alt=\"API\" src=\"https://img.shields.io/badge/API-21%2B-brightgreen.svg?style=flat\"/\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/skydoves/snitcher/actions/workflows/android.yml\"\u003e\u003cimg alt=\"Build Status\" \n  src=\"https://github.com/skydoves/snitcher/actions/workflows/android.yml/badge.svg\"/\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/skydoves\"\u003e\u003cimg alt=\"Profile\" src=\"https://skydoves.github.io/badges/skydoves.svg\"/\u003e\u003c/a\u003e\n\u003c/p\u003e\u003cbr\u003e\n\n\u003cp align=\"center\"\u003e\n🦉 Snitcher captures global crashes, enabling easy redirection to the exception tracing screen for swift recovery.\n\u003c/p\u003e\u003cbr\u003e\n\n\u003cp align=\"center\"\u003e\n\u003cimg src=\"art/demo_release.png\" width=\"330\"/\u003e\n\u003cimg src=\"art/demo_debug.png\" width=\"330\"/\u003e\n\u003c/p\u003e\n\n## What is Snitcher?\n\nSnitcher offers versatile advantages such as aiding in debugging crashes during development, facilitating easy sharing of exceptions by your QA team, enhancing user experiences with recovery screens instead of abrupt closures, and enabling global exception tracing and customized launch behaviors tailored to your specific needs. You have the complete freedom to customize the crash tracing screens according to your build types and preferences, reporting to the Firebase's Crashlytics with displaying the exception screen, including options like launching a designated Activity, sending messages to your BroadcastReceiver, or any other desired actions.\n\n## Documentation\n\nFor comprehensive details about Snitcher, please refer to the **[complete documentation available here](https://skydoves.github.io/snitcher/)**.\n\n## Download\n\n[![Maven Central](https://img.shields.io/maven-central/v/com.github.skydoves/snitcher.svg?label=Maven%20Central)](https://search.maven.org/search?q=g:%22com.github.skydoves%22%20AND%20a:%22snitcher%22)\n\n### Gradle\n\nAdd the dependency below to your **module**'s `build.gradle` file:\n\n```gradle\ndependencies {\n    implementation \"com.github.skydoves:snitcher:1.0.3\"\n}\n```\n\n## Usage\n\nInstalling Snitcher is a breeze; it hooks into global exceptions, replacing application closure with informative exception tracing screens. You can seamlessly install Snitcher using the following example:\n\n```kotlin\nclass App : Application() {\n\n  override fun onCreate() {\n    super.onCreate()\n\n    Snitcher.install(application = this)\n  }\n}\n```\n\nIt's recommended to install Snitcher on your **Application** class or your on initialization solution, such as [App Startup](https://developer.android.com/topic/libraries/app-startup).\n\n### Tracing Global Exceptions\n\nYou can trace the global exceptions by providing `exceptionHandler` lambda parameter. This can be highly beneficial if you intend to gather and report exceptions to other platforms, such as [Firebase Crashlyrics](https://firebase.google.com/docs/crashlytics).\n\n```kotlin\nSnitcher.install(\n  application = this,\n  exceptionHandler = { exception: SnitcherException -\u003e\n    Firebase.crashlytics.log(exception.stackTrace) // or exception.message, \n  }\n)\n```\n\nThe `exceptionHandler` gives you `SnitcherException`, encompassing the exception message, stack traces, package name, and thread information. Additionally, it enables you to recover the original `Throwable` instance with the `SnitcherException.throwable` extension.\n\n```kotlin\nSnitcher.install(\n  application = this,\n  exceptionHandler = { exception: SnitcherException -\u003e\n    val message: String = exception.message\n    val stackTrace: String = exception.stackTrace\n    val throwable: Throwable = exception.throwable\n    val threadName: String = exception.threadName\n\n    // do somethings\n  }\n)\n```\n\n### Custom Exception Trace Screen\n\nSnitcher provides ready-to-use exception tracing screens (such as `ExceptionTraceActivity`, built with the `ExceptionTraceScreen` Composable), giving you the flexibility to extensively tailor these screens according to your preferences, and even design your own distinct tracing interfaces. \n\n```kotlin\nSnitcher.install(\n  application = this,\n  traceActivity = ExceptionTraceActivity::class\n)\n```\n\nIf you don't specify the `traceActivity` parameter, the default value will be `ExceptionTraceActivity`. You can tailor the launched activity by modifying the `traceActivity` parameter to match your preferred choice. The example below demonstrates the construction of a customized trace Activity:\n\n```kotlin\nclass MyExceptionTraceActivity : ComponentActivity() {\n\n  override fun onCreate(savedInstanceState: Bundle?) {\n    super.onCreate(savedInstanceState)\n\n    setContent {\n      val exception by Snitcher.exception.collectAsState()\n      val launcher by Snitcher.launcher.collectAsState()\n\n      SnitcherTheme {\n        if (exception != null) {\n          if (BuildConfig.DEBUG) {\n            // implement your own exception trace screen\n            ExceptionTraceScreen(\n              launcher = launcher,\n              snitcherException = exception!!,\n            )\n          } else {\n            // implement your own app restore screen\n            AppRestoreScreen(launcher = launcher)\n          }\n        }\n      }\n    }\n  }\n}\n```\n\nAs demonstrated in the example above, Snitcher provides access to the `SnitcherException` and the package name of the launcher Activity. This information can be utilized to construct highly customized trace screens that align with your specific needs. Snitcher conveniently provides this information through [StateFlow](https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/-state-flow/)s, allowing you to observe these values without the need for cumbersome intent handling when initiating the trace Activity.\n\n```kotlin\nval exception: SnitcherException? by Snitcher.exception.collectAsState()\nval launcher: String by Snitcher.launcher.collectAsState()\n```\n\n\u003e **Note**: Following any app crashes, you can readily observe the exception details across various components at any time and from any location.\n\n### Custom Launcher (Restore) Activity\n\nFurthermore, you can customize the launcher (restore activity), specifying which Activity should be executed upon restoration within the trace activity. If you don't specify a `launcher` activity, the most recent Activity that encountered a crash will automatically be launched when users press the 'restore' button. However, if you wish to launch a particular Activity instead of the most recent one, you can accomplish this by providing the launcher parameter:\n\n```kotlin\nSnitcher.install(\n  application = this,\n  launcher = MainActivity::class,\n)\n```\n\n### Custom Snitcher Theme\n\nIf you just want to use the pre-builts sreens, but want to customize those components, such as colors and strings, you can easily accomplish it by giving a copy of `SnitcherColor` to the `SnitcherTheme`:\n\n```kotlin\nSnitcherTheme(\n  colors = SnitcherTheme.colors.copy(\n    primary = Color.Blue,\n    background = Color.White,\n    textHighEmphasis = Color.Black\n  )\n) {\n  if (exception != null) {\n    ExceptionTraceScreen(\n      launcher = launcher,\n      snitcherException = exception!!,\n    )\n  }\n}\n```\n\nIf you wish to personalize the text strings within the pre-built UIs, you can override the following string values within your `strings.xml` file:\n\n```xml\n\u003cstring name=\"snitcher_release_crash_screen_title\"\u003eOops, Restore the previous screen?\u003c/string\u003e\n\u003cstring name=\"snitcher_release_crash_screen_description\"\u003eThe app crashed unexpectedly. We apologize for the inconvenience. Would you like to return to where you left off?\u003c/string\u003e\n\u003cstring name=\"snitcher_release_crash_screen_restore\"\u003eRestore\u003c/string\u003e\n\u003cstring name=\"snitcher_debug_crash_screen_restore\"\u003eRestore App\u003c/string\u003e\n\u003cstring name=\"snitcher_debug_crash_screen_debug_on_ide\"\u003eDebug on IDE\u003c/string\u003e\n\u003cstring name=\"snitcher_debug_crash_screen_stacktrace\"\u003eStacktrace\u003c/string\u003e\n```\n\n### Custom Build Types\n\nIf you intend to launch distinct trace activities and implement different behaviors or flavors, you can install Snitcher based on specific build types, as shown in the example below:\n\n```kotlin\nSnitcher.install(\n  application = this,\n  traceActivity = if (BuildConfig.DEBUG) {\n    MyExceptionTraceActivity::class\n  } else {\n    RestoreActivity::class\n  },\n  exceptionHandler = {\n    if (!BuildConfig.DEBUG) {\n      Firebase.crashlytics.log(exception.stackTrace)\n    }\n  }\n)\n```\n\nAlternatively, you can create a single trace Activity and manage the different build types within the activity itself, as demonstrated in the example below:\n\n```kotlin\nSnitcher.install(\n  application = this,\n  launcher = MyExceptionTraceActivity::class,\n)\n\nclass MyExceptionTraceActivity : ComponentActivity() {\n\n  override fun onCreate(savedInstanceState: Bundle?) {\n    super.onCreate(savedInstanceState)\n\n    setContent {\n      val exception by Snitcher.exception.collectAsState()\n      val launcher by Snitcher.launcher.collectAsState()\n\n      SnitcherTheme {\n        if (exception != null) {\n          if (Snitcher.isDebuggable) {\n            ExceptionTraceScreen(\n              launcher = launcher,\n              snitcherException = exception!!,\n            )\n          } else {\n            AppRestoreScreen(launcher = launcher)\n          }\n        }\n      }\n    }\n  }\n}\n```\n\nAs demonstrated in the above example, you have the flexibility to create your own trace or restore Activities and install them according to your various build types.\n\n### Trace Strategy\n\nYou can globally trace exceptions by providing the `exceptionHandler` lambda parameter during Snitcher installation. However, there might be instances where you don't wish to launch the trace Activity but rather perform other actions, such as reporting crashes or sending messages to a `BroadcastReceiver`. In such cases, you can modify the trace strategy as shown in the example below:\n\n```kotlin\nSnitcher.install(\n  application = this,\n  traceStrategy = TraceStrategy.REPLACE,\n  exceptionHandler = {\n    // do something\n  },\n)\n```\n\nIn this scenario, only the `exceptionHandler` lambda function will be executed without triggering the launch of any trace Activity. If the `traceStrategy` parameter is not specified, the default behavior is set to `TraceStrategy.CO_WORK`, which involves executing the `exceptionHandler` lambda and initiating the trace activity when an app crash occurs.\n\n## Find this repository useful? :heart:\n\nSupport it by joining __[stargazers](https://github.com/skydoves/cloudy/stargazers)__ for this repository. :star: \u003cbr\u003e\nAlso, __[follow me](https://github.com/skydoves)__ on GitHub for my next creations! 🤩\n\n# License\n\n```xml\nDesigned and developed by 2023 skydoves (Jaewoong Eum)\n\nLicensed under the Apache License, Version 2.0 (the \"License\");\nyou may not use this file except in compliance with the License.\nYou may obtain a copy of the License at\n\n   http://www.apache.org/licenses/LICENSE-2.0\n\nUnless required by applicable law or agreed to in writing, software\ndistributed under the License is distributed on an \"AS IS\" BASIS,\nWITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\nSee the License for the specific language governing permissions and\nlimitations under the License.\n```\n","funding_links":["https://github.com/sponsors/skydoves"],"categories":["Kotlin"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fskydoves%2Fsnitcher","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fskydoves%2Fsnitcher","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fskydoves%2Fsnitcher/lists"}