<h1 align="center">告密者</h1> <a href="https://opensource.org/licenses/Apache-2.0"><img alt="许可证" src="https://yellow-cdn.veclightyear.com/835a84d5/6d32836e-0f8c-41dc-8c13-283d378beb2a.svg"/></a> <a href="https://android-arsenal.com/api?level=21"><img alt="API" src="https://yellow-cdn.veclightyear.com/835a84d5/a8e16654-4fdc-46a6-8692-75f38f22dc3c.svg?style=flat"/></a> <a href="https://github.com/skydoves/snitcher/actions/workflows/android.yml"><img alt="构建状态" src="https://github.com/skydoves/snitcher/actions/workflows/android.yml/badge.svg"/></a> <a href="https://github.com/skydoves"><img alt="个人资料" src="https://yellow-cdn.veclightyear.com/835a84d5/a44cdb8e-783b-49c6-8cb8-e43093ab44c3.svg"/></a> 🦉 告密者捕获全局崩溃，方便重定向到异常追踪界面，实现快速恢复。 <img src="https://yellow-cdn.veclightyear.com/835a84d5/3eb28f03-5f65-48bb-9e4f-af37f600e152.png" width="330"/> <img src="https://yellow-cdn.veclightyear.com/835a84d5/59528157-e7e2-4ad3-8b6d-332dd786641a.png" width="330"/> ## 什么是Snitcher？ Snitcher提供多种优势，例如在开发过程中帮助调试崩溃，方便QA团队分享异常，通过恢复界面而非突然关闭来改善用户体验，以及根据您的具体需求实现全局异常追踪和自定义启动行为。您可以完全自由地根据构建类型和偏好来定制崩溃追踪界面，向Firebase的Crashlytics报告并显示异常界面，包括启动指定Activity、向BroadcastReceiver发送消息或执行任何其他所需操作等选项。 ## 文档如需了解 Snitcher 的全面详细信息，请参阅**[此处提供的完整文档](https://skydoves.github.io/snitcher/)**。 ## 下载 [![Maven Central](https://yellow-cdn.veclightyear.com/835a84d5/1a8943a5-416e-4733-9986-572ba0f79cac.svg?label=Maven%20Central)](https://search.maven.org/search?q=g:%22com.github.skydoves%22%20AND%20a:%22snitcher%22) ### Gradle 将以下依赖添加到你的**模块**的`build.gradle`文件中： ```gradle dependencies { implementation "com.github.skydoves:snitcher:1.0.3" } ``` ## 使用方法安装Snitcher非常简单；它会钩住全局异常，用信息丰富的异常追踪界面替代应用程序的关闭。您可以使用以下示例轻松安装Snitcher：

class App : Application() {

    override fun onCreate() {
        super.onCreate()

        Snitcher.install(application = this)
    }
}

建议在您的Application类或初始化解决方案中安装Snitcher，例如App Startup。

追踪全局异常

您可以通过提供exceptionHandlerlambda参数来追踪全局异常。如果您打算收集异常并将其报告给其他平台，如Firebase Crashlyrics，这将非常有用。

Snitcher.install(
    application = this,
    exceptionHandler = { exception: SnitcherException ->
        Firebase.crashlytics.log(exception.stackTrace) // 或 exception.message
    }
)

exceptionHandler提供了SnitcherException，包含异常消息、堆栈跟踪、包名和线程信息。此外，您可以使用SnitcherException.throwable扩展来获取原始的Throwable实例。

Snitcher.install(
    application = this,
    exceptionHandler = { exception: SnitcherException ->
        val message: String = exception.message
        val stackTrace: String = exception.stackTrace
        val throwable: Throwable = exception.throwable
        val threadName: String = exception.threadName

        // 执行其他操作
    }
)

自定义异常追踪界面

Snitcher提供了现成的异常追踪界面（如使用ExceptionTraceScreen Composable构建的ExceptionTraceActivity），让您可以根据自己的喜好广泛定制这些界面，甚至设计自己独特的追踪界面。

Snitcher.install(
    application = this,
    traceActivity = ExceptionTraceActivity::class
)

如果不指定traceActivity参数，默认值将为ExceptionTraceActivity。您可以通过修改traceActivity参数来自定义启动的活动。以下示例演示了如何构建自定义的追踪Activity：

class MyExceptionTraceActivity : ComponentActivity() {

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        setContent {
            val exception by Snitcher.exception.collectAsState()
            val launcher by Snitcher.launcher.collectAsState()

            SnitcherTheme {
                if (exception != null) {
                    if (BuildConfig.DEBUG) {
                        // 实现您自己的异常追踪界面
                        ExceptionTraceScreen(
                            launcher = launcher,
                            snitcherException = exception!!,
                        )
                    } else {
                        // 实现您自己的应用恢复界面
                        AppRestoreScreen(launcher = launcher)
                    }
                }
            }
        }
    }
}

如上例所示，Snitcher提供了对SnitcherException和启动器Activity包名的访问。这些信息可用于构建高度自定义的追踪界面，以满足您的特定需求。Snitcher通过StateFlow方便地提供这些信息，让您无需在启动追踪Activity时处理繁琐的intent。

val exception: SnitcherException? by Snitcher.exception.collectAsState()
val launcher: String by Snitcher.launcher.collectAsState()

注意：在应用崩溃后，您可以随时随地在各种组件中轻松观察到异常详情。

自定义启动器（恢复）Activity

此外，您可以自定义启动器（恢复活动），指定在追踪活动中恢复时应执行哪个Activity。如果不指定launcher活动，当用户按下"恢复"按钮时，将自动启动最近遇到崩溃的Activity。但如果您希望启动特定的Activity而不是最近的一个，可以通过提供launcher参数来实现：

Snitcher.install(
    application = this,
    launcher = MainActivity::class,
)

自定义Snitcher主题

如果您只想使用预构建的界面，但希望自定义这些组件，如颜色和字符串，可以通过向SnitcherTheme提供SnitcherColor的副本轻松实现：

SnitcherTheme(
    colors = SnitcherTheme.colors.copy(
        primary = Color.Blue,
        background = Color.White,
        textHighEmphasis = Color.Black
    )
) {
    if (exception != null) {
        ExceptionTraceScreen(
            launcher = launcher,
            snitcherException = exception!!,
        )
    }
}

如果您希望自定义预构建UI中的文本字符串，可以在strings.xml文件中覆盖以下字符串值：

<string name="snitcher_release_crash_screen_title">哎呀，要恢复到之前的界面吗？</string>
<string name="snitcher_release_crash_screen_description">应用程序意外崩溃。我们对此造成的不便深表歉意。您是否希望返回到离开时的位置？</string>
<string name="snitcher_release_crash_screen_restore">恢复</string>
<string name="snitcher_debug_crash_screen_restore">恢复应用</string>
<string name="snitcher_debug_crash_screen_debug_on_ide">在IDE中调试</string>
<string name="snitcher_debug_crash_screen_stacktrace">堆栈跟踪</string>

自定义构建类型

如果您打算启动不同的追踪活动并实现不同的行为或风格，可以根据特定的构建类型安装Snitcher，如下例所示：

Snitcher.install(
    application = this,
    traceActivity = if (BuildConfig.DEBUG) {
        MyExceptionTraceActivity::class
    } else {
        RestoreActivity::class
    },
    exceptionHandler = {
        if (!BuildConfig.DEBUG) {
            Firebase.crashlytics.log(exception.stackTrace)
        }
    }
)

或者，您可以创建一个单一的追踪Activity，并在活动内部管理不同的构建类型，如下例所示：

Snitcher.install(
    application = this,
    launcher = MyExceptionTraceActivity::class,
)

class MyExceptionTraceActivity : ComponentActivity() {

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        setContent {
            val exception by Snitcher.exception.collectAsState()
            val launcher by Snitcher.launcher.collectAsState()

            SnitcherTheme {
                if (exception != null) {
                    if (Snitcher.isDebuggable) {
                        ExceptionTraceScreen(
                            launcher = launcher,
                            snitcherException = exception!!,
                        )
                    } else {
                        AppRestoreScreen(launcher = launcher)
                    }
                }
            }
        }
    }
}

如上例所示，您可以创建自己的追踪或恢复Activity，并根据各种构建类型安装它们。

追踪策略

您可以通过在Snitcher安装时提供exceptionHandler lambda参数来全局追踪异常。但有时您可能不希望启动追踪Activity，而是执行其他操作，如报告崩溃或向BroadcastReceiver发送消息。在这种情况下，您可以修改追踪策略，如下例所示：

Snitcher.install(
    application = this,
    traceStrategy = TraceStrategy.REPLACE,
    exceptionHandler = {
        // 执行其他操作
    },
)

在这种情况下，只会执行exceptionHandler lambda函数，而不会触发任何追踪Activity的启动。如果不指定traceStrategy参数，默认行为设置为TraceStrategy.CO_WORK，这意味着当应用崩溃时，会执行exceptionHandler lambda并启动追踪活动。

觉得这个仓库有用吗？:heart:

通过加入这个仓库的__星标用户来支持它。:star: 同时，在GitHub上关注我__，了解我的下一个创作！🤩

许可证

由 skydoves（Jaewoong Eum）于2023年设计和开发

根据 Apache 许可证2.0版（"许可证"）授权；
除非遵守许可证，否则您不得使用此文件。
您可以在以下网址获取许可证副本：

http://www.apache.org/licenses/LICENSE-2.0

除非适用法律要求或书面同意，否则根据许可证分发的软件
是基于"按原样"分发的，没有任何明示或暗示的担保或条件。
有关许可证下特定语言的权限和限制，
请参阅许可证。