FMPFeedbackForm 1.2.5

FMPFeedbackForm 1.2.5

×

由 Anton Barkov 维护。

FMPFeedbackForm 1.2.5

  • 由
  • MacPaw Inc.

FMPFeedbackForm

FMPFeedbackForm 是一个 Objective-C 框架，允许您将一个简单而有效的反馈表单添加到您的 macOS 项目中。

FMPFeedbackForm

特性

内置 ZenDesk 支持

如果您使用的是 ZenDesk，您只需使用 10 条左右的代码即可将表单设置好并运行。如果您想将表单适配以发送到任何其他服务，只需提供自己的特定数据发送对象实现，而无需太多麻烦。

系统配置报告

表单的UI包含一个复选框，允许用户将其文本文件附加到其支持请求中，其中包含关于用户计算机的匿名信息。此报告包括软件和硬件规格列表，应用程序的最近控制台日志和首选项（NSUserDefaults）。

可定制的UI

如果表单的默认外观不符合您的需求，您可以使用方便的界面轻松自定义任何文本、字段值或占位符。

本地化为12种语言

  • 🇨🇳中文
  • 🇳🇱荷兰语
  • 🇫🇷法语
  • 🇩🇪德语
  • 🇮🇹意大利语
  • 🇯🇵日语
  • 🇰🇷韩语
  • 🇵🇱波兰语
  • 🇧🇷葡萄牙语
  • 🇷🇺俄语
  • 🇪🇸西班牙语
  • 🇺🇦乌克兰语

要求

FMPFeedbackForm需要macOS 10.12或更高版本。

安装

CocoaPods

FMPFeedbackForm可以通过CocoaPods获取。要安装它，只需将以下行添加到您的Podfile中

pod 'FMPFeedbackForm'

Carthage

FMPFeedbackForm可以通过Carthage获取。要安装它，只需将以下行添加到您的Cartfile中

github "MacPaw/FMPFeedbackForm"

Swift包管理器

  • 将包添加到项目设置 -> Swift包

如果您想将FMPFeedbackForm作为其他包的依赖项使用，请在Package.swift中添加以下内容

dependencies: [
    ...
    .package(url: "https://github.com/MacPaw/FMPFeedbackForm", .upToNextMajor(from: "1.0.0"))
],
...
targets: [
    .target(
        name: ...
        dependencies: [
            ...,
            "FMPFeedbackForm"
        ]
    )
]

手动

克隆此仓库（或将它作为子模块添加）并将 FMPFeedbackForm.xcodedeproj 拖放到 Xcode 的项目中。然后进入目标的一般设置选项卡，并将 FMPFeedbackForm.framework 添加到“框架、库和嵌入式内容”列表中。

查看 FMPDemoApp 项目的示例，了解此方法的用法。

Add framework manually

用法

初始化 FMPFeedbackController

FMPFeedbackController 是 NSWindowController 的子类，用于处理表单的窗口展示。它还提供了一个实用的公共接口，包含了您自定义和处理表单工作所需的所有工具。

为了初始化控制器，您需要一个遵循 FMPFeedbackSender 协议的对象。该对象有自己的描述名称——这个对象应该能够发送表单收集的数据，并报告成功/失败。如果您使用 Zendesk，可以使用已经实现的 FMPZendeskFeedbackSender 类。使用您项目证书实例化该类型的对象，并将其传递给控制器初始化器。

// Hold a reference to the controller object somewhere, otherwise it'll get deallocated
var feedbackController: FMPFeedbackController?

// User wants to display the feedback form
@IBAction func provideFeedbackButtonClick(_ sender: Any) {
    // Instantiate an FMPFeedbackSender object
    let zendeskSender = FMPZendeskFeedbackSender(zendeskSubdomain: "subdomain", // (1)
                                                 authToken: "sometoken",        // (2)
                                                 productName: "My App")         // (3)
    
    // Create the controller
    feedbackController = FMPFeedbackController(feedbackSender: zendeskSender)
    // Present the form
    feedbackController?.showWindow(self)
}

就是这样，您已成功展示了一个基本表单，它将发送反馈到您在 Zendesk 上的项目！

为了清晰起见，让我们分解在 FMPZendeskFeedbackSender 初始化过程中传递的证书：

  1. 这是您 Zendesk 项目的子域——即 https://subdomain.zendesk.com 中的 subdomain。
  2. 在 Zendesk 管理面板中生成的 API 密钥。有关获取 API 键的更多信息，请参阅 Zendesk 支持API文档。
  3. 您的产品或应用名称，在支持工单的主题中用作前缀，例如 [My App] Bug Report。

如果您想将反馈发送到其他地方，您必须提供自己的 FMPFeedbackSender 对象实现。您可以查看 FMPZendeskFeedbackSender.m 文件以了解基本思路。

UI 定制

表单的外观由控制器的settings属性定义，该属性由一个FMPInterfaceSettings对象表示。它包含表单UI中使用的所有字符串，并且您还可以指定在表单左上角显示的图标。

有两种方法可以更改表单的设置。

  1. 将更新的设置对象传递给控制器的初始化器
    let settings = FMPInterfaceSettings.default
    settings.title = "My App feedback"
    settings.subtitle = "We'd love to know what you think of our product."
    settings.subjectOptions = ["Feedback", "Bug Report", "Support Request"]
    if let iconResource = NSImage(contentsOf: "path/to/icon.png") {
        settings.icon = iconResource
        settings.iconSize = NSSize(width: 64, height: 64) // default value
    }
    
    feedbackController = FMPFeedbackController(feedbackSender: sender, settings: settings)
  1. 或在初始化后更新控制器的设置
    feedbackController?.settings.title = "My App feedback"
    feedbackController?.settings.subtitle = "We'd love to know what you think of our product."
    feedbackController?.settings.subjectOptions = ["Feedback", "Bug Report", "Support Request"]
    if let iconResource = NSImage(contentsOf: "path/to/icon.png") {
        feedbackController?.settings.icon = iconResource
        feedbackController?.settings.iconSize = NSSize(width: 64, height: 64) // default value
    }

您可以指定用户的姓名和电子邮件地址，以简化表单的填写

    feedbackController?.settings.defaultName = "John Doe"
    feedbackController?.settings.defaultEmail = "[email protected]"

提交后的行为

您也可以更改在成功/失败反馈提交后表单的行为。
默认情况下，FMPFeedbackController通过显示本地化警报并在成功时关闭表单窗口，或者在出现错误时在表单窗口上方呈现错误表单，来优雅地处理这些事件。

Defaut behaviour

您可以通过将这些属性设置为false来关闭此功能

    feedbackController?.showsGenericSuccessAlert = false
    feedbackController?.showsGenericErrorSheet = false

您还可以通过设置一个onDidSendFeedback完成（如果没有被关闭，则在默认行为之后执行）来自定义处理这些事件。

    feedbackController?.onDidSendFeedback = { [weak self] error in
        guard let error = error else {
            // Error is nil, display your custom success message
            self?.showSuccessMessage()
            self?.feedbackController?.close()
            return
        }
        
        // Error is not nil, submission failed, display error
        self?.showErrorMessage(with: error)
    }

系统配置报告

FMPFeedbackForm几乎不需要您的任何输入即可收集系统配置报告数据，但为了收集更高质量的数据，您可能需要指定以下两项。

您的应用程序的控制台日志是通过Apple系统日志API收集的，它并不总是提供所需的所有数据，并且主要收集与您的应用程序相关的系统错误。如果您使用CocoaLumberjack或其他工具将日志写入单独的文本文件，您可以将它们指定给反馈控制器，并且其内容将包含在报告内。

    feedbackController?.logURLs = [URL(fileURLWithPath: "path/to/file.log"),
                                   URL(fileURLWithPath: "path/to/otherFile.txt")]

如果您使用与您的应用程序包ID不同的内容，您还想指定您自定义的NSUserDefaults域（或套件名称）。

    feedbackController?.userDefaultsDomain = "com.MyCompany.MyAppsNonDefaultDomain"

演示应用程序

上述描述的大部分逻辑都方便地在本仓库提供的演示应用中实现。请参考它以详细了解如何使用反馈表单。

Demo app

许可协议

FMPFeedbackForm 依据MIT许可证提供。

更多信息请参阅 LICENSE 文件。