Usabilla for Apps - iOS SDK

Usabilla for Apps允许您以非常容易和灵活的方式收集用户的反馈。

请参阅我们的Wiki，了解如何安装和自定义SDK的完整和深入指南。

v3.6.1版本的最新更改

修复了以下问题

• 修复了有时会损坏发送到我们服务器的截屏的编码问题
• 修复了在iOS 10上特定表单可能发生的崩溃

要求

• iOS 9.0+
• Xcode 8.0+
• Swift 3.1+

对于较旧版本的iOS，您可以使用SDK的v2.3.0版本。

安装

手动

或者，您可以下载存储库的最新版本，并将UsabillaFeedbackForm.framework添加到您的应用程序的嵌入式框架中。

如何入门

在Web上

• 在其Usabilla Live for Apps部分创建一个新表单。
• 复制您刚刚创建的表单的表单ID，并将其用于在SDK中打开它。

在SDK中

初始化

在您的AppDelegate中，在文件顶部添加以下行以导入SDK。

import UsabillaFeedbackForm

将以下行添加到didFinishLaunchingWithOptions

UsabillaFeedbackForm.load()

load方法在这里是为了初始化缓存特性，它将提交之前未提交的任何反馈。

使用表单

该SDK使用您从前 Usabilla 获取的表单ID，以获取并在您的应用内显示您的表单。

SDK的基本实现方式如下。

class ViewController: UIViewController, UsabillaFeedbackFormDelegate {

    override func viewDidLoad() {
        super.viewDidLoad()
        UsabillaFeedbackForm.delegate = self
        UsabillaFeedbackForm.loadFeedbackForm("Form ID")
    }

    //Called when your form succesfully load
    func formLoadedCorrectly(_ form: UINavigationController, active: Bool) {
        present(form, animated: true, completion: nil)
    }
    //Called when your forms can not be loaded. Returns a default form
    func formFailedLoading(_ backupForm: UINavigationController) {
        present(backupForm, animated: true, completion: nil)
    }

}

用法

添加截图

您可以将截图附加到反馈表单中。

您可以通过调用 let image = UsabillaFeedbackForm.takeScreenshot(self.view) 来在任何时候拍照。

要附加截图到表单，调用 UsabillaFeedbackForm.loadFeedbackForm("表单ID", screenshot: image) 时将其作为参数传递。

如果您不想当前视图的截图，请将 nil 作为 screenshot 参数传递。

自定义截图 & 敏感信息

您可以使用通过调用 UsabillaFeedbackForm.loadFeedbackForm() 时将任何图像作为 image 参数传递的方法来代替使用 UsabillaFeedbackForm.takeScreenshot() 方法。

这允许您通过例如自行拍照、删除所有不想要的信息并提交审查后的版本等方式隐藏任何用户敏感或私人的信息。

添加自定义变量

您可以传递自定义变量，这些变量将与用户发送的反馈一起附加。自定义变量保存在字典中。

初始化控制器后，您可以使用以下方式轻松设置自定义变量：

var customVariables: [String : Any] = [:]
customVariables["user"] = "Mario"
customVariables["age"] = 10

您可以在提前创建或者在运行时创建，就像示例中那样，其内容将在Usabilla web界面中报告和显示。

为了确保变量在web界面中适当地显示，建议保持字典对象相对简单，并且不要将一个对象嵌套到另一个对象中。

当调用 UsabillaFeedbackForm.loadFeedbackForm("Form ID", screenshot: nil, customVariables: customVariables) 时，将自定义变量作为参数添加。

预加载表单

如果您知道在用户离线时需要显示反馈表单，您可以将其预先加载并在SDK中缓存以在任何时候提供。
使用以下方法来预加载表单：

UsabillaFeedbackForm.preloadForms(withIds: ["myId", "myOtherId"])

这将获取表单的最新版本并在SDK中缓存它。
当您请求该表单时，如果没有网络连接，SDK将使用缓存的版本，并且用户将能够提交他们的反馈。

在离线期间提交的反馈将在连接恢复时发送。

如果您愿意，可以使用以下方法来清空缓存：

UsabillaFeedbackForm.removeCachedForms()

自定义表单

您可以自定义表单中所有元素的颜色。对于更深入的自定义指南，请参阅 Wiki页面

App Store评分

原始实现已经从3.5.0版本中删除，以遵循Apple的新评分指南。
从3.5.0版本开始，我们提供对使用 Apple自己的评分API 的支持。

您可以通过读取包含在 自动提交回调 中的用户活动信息来决定是否提示用户评分。

在Usabilla web界面中，您可以定义是否特定反馈表单应提示用户评分。

提交回调

自 v3.3.0 版本开始，可以通过实现 `UsabillaFeedbackFormDelegate` 中的 `.formDidClose 方法来获取用户提交的反馈信息。

如果用户在提交表单之前未提交，也会通知到您。

这个方法会为您提供包含 FeedbackResult 的数组。

struct FeedbackResult {
    let rating: Int?
    let abandonedPageIndex: Int?
    var sent: Bool
}

这是因为用户可能多次提交表单，而此方法只为送出的所有反馈调用一次。

一旦用户与之交互，评分 值就会被设置，即使表单没有提交，也会报告出来。

只有用户在提交前取消表单时，废弃的页码 才会被设置。

以下是一个示例实现

func formDidClose(_ form: UINavigationController, formID: String, with feedbackResults: [FeedbackResult], isRedirectToAppStoreEnabled: Bool){
     guard let feedback = feedbackResults.first else {
         return
     }

     if feedback.sent == false {
         let abandonedPageIndex = feedback.abandonedPageIndex
         print("Hey why did you left the form here \(abandonedPageIndex)")
         return
     }

     if let rating = feedback.rating {
         if rating >= 4 && isRedirectToAppStoreEnabled {
             // Prompt the user for rating and review
         }
     }
 }

处理手动关闭

自 v3.3.0 版本起，可以自定义关闭表单的方式

将自动关闭 UsabillaFeedbackForm 的属性设置为 false

UsabillaFeedbackForm.dismissAutomatically = false

并实现 formWillClose 委托方法

func formWillClose(_ form: UINavigationController, formID: String, with feedbackResults: [FeedbackResult], isRedirectToAppStoreEnabled: Bool) {
    // handle your custom dismiss e.g: dismiss(animated: true, completion: nil)
}

警告：这样做后，表单将不会自动关闭，并且您将负责其正确行为。此外，`formDidClose` 委托方法也不会被调用。

与 Obj-C 应用集成

要在您的 Obj-C 应用中集成 SDK，请遵循 Apple 官方指南了解如何在 同一项目中使用 Swift 和 Objective-C

解决此问题的一个快速方法是创建一个 Swift 文件，在该文件中处理您的应用程序。在创建新的文件并设置桥接头之后，您可以在 Swift 类中扩展现有的视图控制器，以便无缝将 SDK 集成到您的应用程序中。

在这个示例中，您可以看到一个 Obj-C 中的 ViewController

#import "ViewController.h"

//Remember to import the auto generated Swift header, otherwise you won't see you Swift extension
#import "objctest-Swift.h"


@interface ViewController ()

@end

@implementation ViewController


- (IBAction)buttonPressed:(id)sender {
      [self  showForm];

}


@end

及其 Swift 扩展，实现了 SDK

import UsabillaFeedbackForm

extension ViewController : UsabillaFeedbackFormDelegate {

    open override func viewDidLoad() {
        super.viewDidLoad()
        UsabillaFeedbackForm.delegate = self
    }


    public func formLoadedCorrectly(_ form: UINavigationController, active: Bool) {
        present(form, animated:  true)
    }

    public func formFailedLoading(_ backupForm: UINavigationController) {

    }

    @objc public func showForm(){
        UsabillaFeedbackForm.loadFeedbackForm("Form ID")
    }
}