macOS 应用的崩溃报告器

你的应用总有一天会崩溃。请做好自动收集崩溃数据的准备，因为并非每个用户都是技术专家，能够从内置的 Console 应用中发送 .crash 文件给你。

要求

macOS 10.12+
Xcode 10.2+
Swift 5+

对于可选的服务器端点脚本，你需要 PHP 7.x。

安装

Carthage

github "CleanCocoa/CrashReporter"

CocoaPods

pod 'CrashReporterMac'

SwiftPM

.package(url: "https://github.com/CleanCocoa/CrashReporter", from: "0.2.0")

手动

如果你想自定义 UI，请检出源码并将 CrashReporter/ 中的所有代码复制到你的项目中。

使用方法

服务器端点

你需要一个服务器端点来接收崩溃报告。

该框架不关心服务器如何处理

你可以从服务器通过电子邮件发送收到的崩溃报告，或者
你可以将崩溃报告作为带时间戳的文件存储在磁盘上，以供以后参考，或者
你可以将崩溃报告存储在数据库中。

崩溃报告器框架将执行 HTTP POST 请求

如果应用的 bundle 中找到了值，则 User-Agent 元数据设置为 "\(APP_NAME)-\(VERSION)"，例如 "Sherlock-2.0"。
userEmail 变量要么省略，要么设置为用户输入的电子邮件。
userProvidedDetails 变量要么省略，要么设置为用户输入的详细信息。
crashlog 变量设置为用户提交的 .crash 文件的内容。
服务器响应将被忽略。

只要你的 URL 可以从应用程序访问，你就可以自己编写端点。

或者你可以使用此仓库中提供的简单端点！它位于 php/index.php。此 PHP 服务器脚本将尝试以带时间戳的附件形式通过电子邮件将崩溃日志发送给你，例如 20190701204853 Sherlock-2.0.crash（其中时间戳表示 ISO 格式的日期 2019-07-01 20:48:52）。如果用户输入了她的电子邮件地址，她默认会收到一份抄送。你可以在 PHP 脚本的 frontmatter 中切换此设置。

要在本地机器上运行脚本进行快速测试，请运行

$ php -S 127.0.0.1:3333 php/index.php

然后在你的 Swift 代码中使用 URL(string: "http://127.0.0.1:3333/") 作为端点。

应用程序设置

请参阅 Example/ 中的代码，它是 Xcode 项目的一部分。

你可以在你的应用程序中直接使用该框架来检查崩溃报告

import CrashReporter

let crashReporterURL = URL(string: "http://127.0.0.1:3333/")!
let crashReporter = CrashReporter(
    crashReporterURL: crashReporterURL,
    privacyPolicyURL: URL(string: "https://example.com/privacy-policy")!)

// Run the check in the background and display 
// a crash reporter window if needed
crashReporter.check()

应用程序中的首选项面板

如果允许用户在崩溃报告器窗口中勾选“自动发送崩溃报告”，你应该在应用程序的首选项面板中添加类似的选项，以便可以撤消此设置。

请参考 DefaultsKeys.sendCrashLogsAutomaticallyKey。

如果想使用 Cocoa Bindings 在你的首选项面板或主菜单中配置“自动发送崩溃报告”复选框，你可以在你的类中创建一个简单的、符合 KVC 的包装器

// Assuming this is loaded from a Nib where you set an object of this type as the
// target for "Value" Cocoa Bindings.
class PreferenceController: NSViewController {
    let crashReporter: CrashReporter = // ... setup before ...
    
    // Cocoa bindings path is `self.sendCrashReportsAutomatically`
    @objc public dynamic var sendCrashReportsAutomatically: Bool {
        get {
            return crashReporter.sendCrashReportsAutomatically
        }
        set {
            crashReporter.sendCrashReportsAutomatically = newValue
        }
    }
}

API

CrashReporter.check() 是默认调用，它会在需要时显示当前应用程序的崩溃报告器窗口，并将崩溃报告上传到服务器。
CrashReporter.check(appName:collectEmailAddress:alwaysShowCrashReporterWindow:) 允许你控制报告器搜索 .crash 文件的应用程序名称。如果你不想收集用户的电子邮件地址以便与其联系，请将 collectEmailAddress 设置为 false。如果你总是想显示崩溃报告器窗口，而不是让用户选择何时看到该窗口，请将 alwaysShowCrashReporterWindow 设置为 true。
CrashReporter.sendCrashReportsAutomatically 公开了自动发送报告的用户设置。对首选项面板很有用。

如果你没有更改崩溃报告器设置的 UserDefaults 键，请在你的应用程序中使用各种 DefaultsKeys.standard 属性来查找值

emailAddressKey 是 "CRR_emailAddress"，用户的电子邮件地址存储在这里
sendCrashLogsAutomaticallyKey 是 "CRR_sendCrashLogsAutomatically" -- 使用它在你的首选项面板中切换自动发送崩溃报告
lastSeenCrashLogTimeSince1970Key 是 "CRR_lastSeenCrashLogTimeSince1970"
lastSeenCrashLogMD5Key 是 "CRR_lastSeenCrashLogMD5"

许可证

整个项目都按照 MIT 许可证分发。请参阅 LICENSE 文件以供参考。

快速概览