最新版本的 SDK 使用模块格式稳定性构建。以前的版本可在我们的 git 仓库中找到。对于 Carthage，请查看 Carthage 章节

Usabilla SDK 在 CocoaPods 上可用。您可以通过以下方式安装 CocoaPods

$ gem install cocoapods

use_frameworks!

target 'YourProjectTarget' do

pod 'Usabilla', '~> 6.13.6'

End

pod 'Usabilla', :podspec => 'https://raw.githubusercontent.com/usabilla/usabilla-u4a-ios-swift-sdk/Xcode-x.y.z/Usabilla.podspec'

将 Xcode-x.y.z 替换为所需的版本，例如 Xcode-12.5.1。可用版本 Xcode-14.0。

binary "https://raw.githubusercontent.com/usabilla/usabilla-u4a-ios-swift-sdk/master/Usabilla.json"

binary "https://raw.githubusercontent.com/usabilla/usabilla-u4a-ios-swift-sdk/Xcode-x.y.z/Usabilla.json"

将 Xcode-x.y.z 替换为所需的版本，例如 Xcode-12.5.1。可用版本 Xcode-14.0。

注意：Carthage - 0.38.0 鼓励使用 XCFrameworks，而用于 carthage 的 Usabilla SDK 从 6.9.0 版本开始支持 XCFrameworks

您可以从 releases 下载最新版本的仓库，并解压 UsabillaXCFramework.zip。然后将 Usabilla.xcframework 添加到您应用的嵌入式框架。

这样做时，您在向 App Store 提交应用时可能会遇到问题。这是由于 App Store 本身存在一个 bug。

您可以通过在应用的 target 的 Build Phases 中的 Embed Frameworks 阶段之后创建一个新的 Run Script Phase，并复制此处提供的脚本来解决此问题。

我们建议在 AppDelegate 中初始化 SDK。但这并非强制性的，初始化也可以在其他地方执行，不会有任何问题。

Usabilla.initialize(appID: "appID")

Usabilla.initialize(appID: "appID") {
    // Your callback code here
}

为了在开发过程中从 SDK 获得更多见解，您可以启用日志记录，方法是

Usabilla.debugEnabled = true

当用户与表单底部区域的徽标交互时，它会在移动浏览器中打开 url "http://www.usabilla.com"，您可以使用以下方式禁用该用户交互

Usabilla.setFooterLogoClickable = false

Usabilla 应用 SDK 的第 4 版引入了新的活动功能。本指南介绍了活动功能以及使用该功能所需的所有步骤。

在 Usabilla 应用平台中，活动被定义为针对特定用户群体的积极调查。

能够在您的移动应用中运行活动非常棒，因为它允许您从目标用户那里收集更具体的见解。更好的是，创建新的和管理现有活动可以在无需发布新版本的应用的情况下完成。一切都可以从 Usabilla Web 界面进行管理。

您可以运行任意数量的活动，并将其目标设置为在满足一组特定的目标选项时触发。对于现有的 Usabilla 客户来说，活动向用户展示的方式配置将非常熟悉。您可以像使用被动反馈表单一样配置它以满足您的需求。

运行移动活动最重要的方面是“事件”。事件是在 SDK 中配置的自定义触发器。当预定义的事件发生时，它将允许您触发活动。一个很好的事件示例是用户在您的应用中成功购买。

应用 ID 是用于将活动与移动应用关联的标识符。通过使用特定的应用 ID 加载 SDK，它将获取连接到给定应用 ID 的所有活动。

通过将活动与多个应用 ID（例如，iOS 生产应用、iOS Beta 应用）关联，可以将活动定向到多个应用。

活动由事件触发。事件用于在您的应用中发生某些事情时与 SDK 通信。因此，SDK 将根据 Usabilla Web 界面的配置对事件做出反应。要向 SDK 发送事件，请使用

Usabilla.sendEvent(event: String)

您还可以使用自定义变量来细分您的用户群。自定义变量可用于指定用户的某些特征，并将活动仅定向到特定的子集。

Usabilla SDK 允许您确保活动不会在不适当的时刻触发。例如，当您的应用用户正处于一个敏感的过程中，不应被打扰时。这可以通过设置 Usabilla 的布尔属性 canDisplayCampaigns 来满足您的需求。

Usabilla.canDisplayCampaigns = false

将其设置为 true 将允许 SDK 在任何活动触发时显示它。将其设置为 false 将阻止所有活动显示。

即使 canDisplayCampaigns 设置为 false，SDK 仍会继续接收所有事件。如果活动碰巧触发，它既不会显示也不会延迟：该事件实例将丢失。

如果当 canDisplayCampaigns 属性设置为 false 时，您的一个或多个活动触发，并且稍后更改为 true，则 SDK 将不会显示该活动。原因是稍后的这个时刻可能与向用户显示活动无关。

可以获取有关用户留下的反馈的信息，并且如果您实现以下内容，您也会收到用户在未提交表单就离开的通知

func campaignDidClose(withFeedbackResult result: FeedbackResult, isRedirectToAppStoreEnabled: Bool) {}

与被动反馈方法不同，活动方法仅返回一个 FeedbackResult，并且仅调用一次。

注意：从 6.13.0 版本开始，我们引入了活动重新激活功能。在活动创建期间或创建后，可以添加/修改具有重新激活持续时间（以天为单位）的活动 - 例如，如果活动设置为 7 天后重新激活，即如果再次满足活动的所有先前条件（如语言、百分比、重复/触发），则活动可以在 7 天后再次显示。

在开发和测试期间，重置活动状态并允许它们再次显示可能很有用。
您可以通过调用 Usabilla.resetCampaignData(completion: nil) 来做到这一点。
您可以包含一个闭包，该闭包将在 SDK 完成重置活动数据时执行。
此方法会将您的数据与 Usabilla 服务器同步，因此它将获取所有新活动并删除已停用的活动。

您可以在 Usabilla 应用活动编辑器中创建新活动后立即开始收集活动结果。默认情况下，新活动标记为非活动状态。在 Usabilla 应用活动概览页面上，您可以随时激活或停用现有活动，以反映您的特定需求。

此外，您可以随时更新活动的内容（例如，问题）。请记住，您对现有活动进行的更改可能会影响您收集的数据的完整性（更改前后的不同响应）。

此外，您还可以更改活动的目标选项。请记住，更新活动的目标选项将重置用户设备上先前进行的任何进度。

聚合活动结果可从活动概览下载。您可以在此处以 CSV 格式下载每个活动的结果。

活动结果将包含您的用户提供的答案。来自活动的响应按页面收集并发送到 Usabilla 页面。这意味着，即使用户决定中途放弃活动，您仍然可以收集有价值的见解。当用户继续到下一页时，上一页的结果将提交给 Usabilla。除了显示活动问题的答案的活动结果外，您还可以查看设备元数据和自定义变量。

至于活动结果。请注意，编辑现有活动的表单将影响聚合活动结果

被动反馈是不由事件触发的反馈表单。它们主要是，但不一定，由用户启动。

SDK 使用您从 Usabilla 获取的表单 ID（在创建新表单后）来获取并在您的应用内显示表单。

class SomeViewController: UIViewController, UsabillaDelegate {

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

    //Called when your form successfully load
    func formDidLoad(form: UINavigationController) {
        present(form, animated: true, completion: nil)
    }

    //Called when your forms can not be loaded. Returns a default form
    func formDidFailLoading(error: UBError) {
        //...
    }

}

对于 SWIFTUI 实现，请按照以下步骤操作：UIViewControllerRepresentable 实例用于在您的 SwiftUI 界面中创建和管理 UIViewController 对象。

import SwiftUI
import UIKit
import Usabilla

struct UsabillaFormView: UIViewControllerRepresentable {
    func makeUIViewController(context: Context) -> UsabillaFormViewController {
        let vc = UsabillaFormViewController()
        return vc
    }
    func updateUIViewController(_ uiViewController: UsabillaFormViewController, context: Context) {
    }
    typealias UIViewControllerType = UsabillaFormViewController
}

class UsabillaFormViewController: UIViewController, UsabillaDelegate {

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

    //Called when your form successfully load
    func formDidLoad(form: UINavigationController) {
        present(form, animated: true, completion: nil)
    }

    //Called when your forms can not be loaded. Returns a default form
    func formDidFailLoading(error: UBError) {
        //...
    }

}

 //Called from SWIFTUI view to load the form
struct ContentView: View {
    @State private var showingUsabillaForm:Bool = false

    var body: some View {
        Button(action: {
            self.showingUsabillaForm = !self.showingUsabillaForm
        })
        if(showingUsabillaForm) {
            UsabillaFormView()
        }
    }
}

如果您知道在用户离线时需要显示反馈表单，您可以预加载并缓存它，使其在任何给定时刻都可用。
要预加载表单，请使用

UsabillaFeedbackForm.preloadFeedbackForms(withFormIDs: ["FORM_ID_1", "FORM_ID_2"])

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

UsabillaFeedbackForm.removeCachedForms()

在 iPad 上，被动反馈表单的演示样式默认设置为 formSheet。如果您想覆盖此行为并进行全屏显示，您可以使用

func formDidLoad(form: UINavigationController) {
    form.modalPresentationStyle = .fullScreen
    present(form, animated: true, completion: nil)
}

let image = Usabilla.takeScreenshot(self.view)

要将屏幕截图附加到表单，请在调用以下命令时将其作为参数传递

Usabilla.loadFeedbackForm("Form Id", screenshot: image)

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

您可以不使用 Usabilla.takeScreenshot() 方法拍摄屏幕截图，而是通过在调用 Usabilla.loadFeedbackForm() 时将其作为 image 参数传递来提供您想要的任何图像

这将允许您隐藏任何用户敏感信息，例如，自行拍摄屏幕截图，删除所有不需要的信息并提交审查后的版本。

可以获取有关用户留下的反馈的信息，并且如果您实现以下内容，您也会收到用户在未提交表单就离开的通知

func formDidClose(formID: String, withFeedbackResults results: [FeedbackResult], isRedirectToAppStoreEnabled: Bool) {
    //...
}

此委托方法为您提供了一个 FeedbackResult 数组，因为用户可能会多次提交表单，并且此方法将仅对发送的所有反馈调用一次。

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

rating 值在用户与之交互后立即设置，即使表单未提交也会报告。

仅当用户在提交之前取消表单时，才会设置 abandonedPageIndex。

func formDidClose(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
        }
    }

}

Usabilla.dismissAutomatically = false

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

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

SDK 具有屏蔽（在后端）来自输入文本的数据的选项，特别是 Text Input 和 Text Area。请注意，电子邮件输入字段不会被屏蔽。

Usabilla.setDataMasking()
Usabilla.setDataMasking(masks: [String])
Usabilla.setDataMasking(masks: [String], maskCharacter: Character)

masks 是用于屏蔽输入字段中数据的 RegEx 列表。它使用 SDK 提供的默认 RegEx。maskCharacter 是用于替换匹配的 RegEx 的字符。默认情况下，它使用“X”。

[a-zA-Z0-9\+\.\_\%\-\+]{1,256}\@[a-zA-Z0-9][a-zA-Z0-9\-]{0,64}(\.[a-zA-Z0-9][a-zA-Z0-9\-]{0,25})+

Usabilla.defaultDataMasks

您可以传递自定义变量，这些变量将附加到用户发送的反馈。自定义变量保存在字典对象中，该字典对象在 SDK 的公共接口中，称为 customVariables。

Usabilla.customVariables["key"] = "value"

由于 SDK 使用 JSONSerialisation 将自定义变量转换为 JSON，因此必须考虑其限制。自定义变量的 value 必须是 NSString 或 String 的实例。

尝试将无效对象设置为自定义变量将导致该对象未被设置，并在控制台中打印错误。

您始终可以通过调用 JSONSerialization.isValidJSONObject(object) 来检查对象是否被认为是有效的。

自定义变量作为额外的反馈数据添加到 SDK 发送的每个反馈项中，无论是来自被动反馈还是活动。自定义变量 key / name 不应为 空字符串，并且不应包含 . 或 $。 自定义变量可以用作目标选项，只要 value 是 String。

要决定是否提示用户进行评分，您可以读取在提交回调或活动提交回调中传递的有关用户活动的信息

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

let result = Usabilla.dismiss()

这将导致表单或活动被移除。不会调用任何委托方法，例如 formDidClose

可以强制活动或表单以特定方向呈现，而与设备方向或应用程序支持的方向无关。

Usabilla.orientation = .landscapeLeft

Usabilla.orientation = .all

也应该使用它来重置属性，以遵循应用程序设置的受支持方向。

为此，您必须提供五个 UIImage 的列表（或两个，取决于您想要实现的目标），这些图像将代替 Usabilla 的默认表情符号。数组的第一个元素应该是最低或最左边的项目，而第 5 个元素将是最高或最右边的项目。目前，SDK 不会执行任何检查以确保列表有效。

未选中时，图像将以 0.5 的 alpha 值显示，选中时，图像将以 1 的 alpha 值显示。

let a = UIImage(named: "1")!
let b = UIImage(named: "2")!
let c = UIImage(named: "3")!
let d = UIImage(named: "4")!
let e = UIImage(named: "5")!
Usabilla.theme.images.enabledEmoticons = [a, b, c, d, e]

let enabled = createEnabledArray()
let disabled = createDisabledArray()

Usabilla.theme.images.enabledEmoticons = enabled
Usabilla.theme.images.disabledEmoticons = disabled

您可以通过在 UsabillaTheme 中设置 star 和 starOutline 来更改星级评分中星星的外观。

请记住，为了在您的表单中显示星级评分，您必须首先在Usabilla Web 界面中启用它。

Usabilla.theme.images.star = UIImage(named: "starFilled")!
Usabilla.theme.images.starOutline = UIImage(named: "starOutline")!

可以通过设置 UsabillaTheme.fonts 结构的 regular 和 bold 属性来更改反馈表单的字体。如果未设置，SDK 将使用默认系统字体。

Usabilla.theme.fonts.regular = UIFont(name: "Helvetica-LightOblique", size: 20)
Usabilla.theme.fonts.bold = UIFont(name: "Helvetica-Bold", size: 20)

所有颜色都从 Usabilla 网站设置，而不是从 SDK 设置。您可以在我们的知识库中找到颜色名称和作用的详细说明。

唯一的例外是用于更改导航栏颜色的 header 颜色。
您可以在显示表单之前通过调用 Usabilla.theme.colors.header = UIColor.red 来设置标题颜色。

对于 Web 界面中所有不可自定义的文本，您可以使用应用程序内的 .string 本地化文件提供您自己的翻译。

如果您想提供自己的翻译，则需要在 .string 文件中使用自定义文本提供特定的键（如下所述）。

///Default usabilla english localization
"usa_form_continue_button" = "Next";
"usa_form_close_button" = "Close";
"usa_form_required_field_error" = "Please check this field";
"usa_screenshot_placeholder" = "Add screenshot";

// Accessibility labels
"usa_mood_select_a_rating_out_of" = "select a rating out of";
"usa_accessibility_field_required" = "This field is required";
"usa_choose_from_options" = "Choose from %d options";
"usa_delete_screenshot" = "delete screenshot";
"usa_edit_screenshot" = "change screenshot";
"usa_powered_by_usabilla" = "powered by usabilla";
"usa_tap_to_visit_usabilla" = "tap to visit usabilla.com";
"usa_accessibility_button_label_continue" = "Continue";

// Emoticons
"usa_mood_hate" = "Hate";
"usa_mood_dislike" = "Dislike";
"usa_mood_neutral" = "Neutral";
"usa_mood_like" = "Like";
"usa_mood_love" = "Love";

// Stars
"usa_mood_one_star" = "1 star";
"usa_mood_two_star" = "2 stars";
"usa_mood_three_star" = "3 stars";
"usa_mood_four_star" = "4 stars";
"usa_mood_five_star" = "5 stars";

// checkbox & radio button
"usa_multiple_options_possible" = "Multiple options possible";
"usa_one_option_possible" = "One option possible";
"usa_selected" = "selected";
"usa_unselected" = "unselected";

// Added in SDK Version 6.4.0
//camera button
"usa_camera_navbar_left_button" = "Cancel";

// Screenshot anotation
"usa_retake_button_title" = "Retake";
"usa_back_button_title" = "Back";
"usa_cancel_button_title" = "Cancel";
"usa_add_button_title" = "Add";
"usa_done_button_title" = "Done";
"usa_back_button_library_title" = "Library";
"usa_library_title" = "Library";
"usa_edit_title" = "Edit";
"usa_add_title" = "Add photo";
"usa_camera_error_title" = "No access to camera";
"usa_camera_error_description" = "Allowing access lets you take photos to add to your feedback.";
"usa_camera_settings_title" = "Allow access to camera";

"usa_library_error_title" = "No access to library";
"usa_library_error_description" = "Allowing access lets you select a photo to add to your feedback.";
"usa_library_settings_title" = "Allow access to library";

如果您想使用您的自定义 .string 文件，您可以通过调用以下命令来执行此操作

Usabilla.localizedStringFile = "your_localization_file_name"

如果用户尝试设置自定义屏幕截图，SDK 将请求访问图库和相机的权限。

NSCameraUsageDescription
NSPhotoLibraryUsageDescription

如果用户只想设置库或相机权限，则将仅显示相机视图或照片库视图。如果未提供这两种权限，则最终用户只能注释或查看通过加载表单传递的图像，并且相机和照片库将不会显示。

注意：如果您尚未在表单的“高级设置”面板中启用“显示屏幕截图”选项，则“添加照片”面板将不会显示。

要将 SDK 集成到您的 Obj-C 应用程序中，请遵循 Apple 关于如何在同一项目中使用 Swift 和 Objective-C 的官方指南。

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

#import "ViewController.h"

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

@interface ViewController ()

@end


@implementation ViewController

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

@end

import Usabilla

extension ViewController : UsabillaDelegate {

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

    func formDidLoad(form: UINavigationController) {
        present(form, animated:  true)
    }

    func formDidFailLoading(error: UBError) {
        //...
    }

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

SDK 当前不是线程安全的。这要求宿主应用确保在同一线程上处理对 SDK 的所有调用。否则可能会导致意外行为。

收集的信息不会用于识别用户，不包含 PII，也不会与外部方共享。对于 iOS 开发人员，收集的数据属于 Apple 隐私数据类型的“诊断”类别

将 SDK 添加到您的项目不会发送任何信息；仅在以下情况下发送信息

{
  "appVersion": "1.0.0",
  "appName": "AppName",
  "device": "iphone1.2",
  "freeMemory": "831172",
  "freeSpace": "582800",
  "orientation": "Portrait",
  "osVersion": "12.1.0",
  "reachability": "WiFi",
  "rooted": false,
  "screenSize": "1440x2392",
  "sdkVersion": "7.2.0",
  "system": "ios",
  "totalMemory": "1530604",
  "totalSpace": "793488",
  "id": "34e3e3123",
  "timestamp": "2021-04-04T12:34:23Z",
  "originClass": "com.usabilla.Usabilla",
  "action": {
    "duration": "102",
    "errorCode": "0",
    "errorMessage": "",
    "name": "function or property invoked on our public interface"
    ...
    function parameters are also collected here
    ...
  }
}

如果您不希望我们收集此诊断数据，您可以将公共字段（默认为 true）设置为如下

Usabilla.submitTelemetryData = false

当活动或表单关闭时，数据将提交到服务器。如果需要在应用中提供响应，则宿主应用可以实现可选的委托方法

 func feedbackResultSubmitted(userResponse: Data)

此委托方法为您提供一个 Data 对象，该对象包含问题/答案。数据是 Dictionary<String:Any>。该字典以随机顺序保存所有问题，其中键是问题的名称，值是问题的答案。如果问题未回答，则值为 null

	func feedbackResultSubmitted(userResponse: Data) {
        if let jsonString = String(data: userResponse, encoding: String.Encoding.ascii) {
            //// use the data
        }
    
    }

从 SDK v6.12.2 版本开始，我们引入了一个新功能 标准事件。

注意：现在使用标准事件，您可以在您的应用程序（嵌入了 GetFeedback Digital/Usabilla SDK 的宿主应用程序）中显示活动，而无需添加任何额外的代码行。您只需在 GetFeedback 中使用您的 用户帐户 创建标准活动（带有默认/系统事件的活动）。

注意：SDK 不会监听任何默认/系统事件，除非它已初始化，并且建议仅初始化一次。为了使此功能正常工作，必须尽早使用 Usabilla.initialize 初始化 SDK，最好在 AppDelegate 方法中初始化

func application(_ application: UIApplication, willFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey : Any]? = nil)

一旦 SDK 被初始化并从后台转换，此时 SDK 会自行更新并从服务器获取新的/更新的数据。SDK 将定期自行更新，一旦应用程序进入前台，每 12 小时更新一次。如果应用程序在后台，SDK 不会执行任何活动，也不会监听任何事件。

对于默认事件，SDK 仅监听系统事件，并且基于这些事件，SDK 将显示活动。如果触发了多个活动，则只会显示最旧的活动，而其他活动将被忽略，并有机会在稍后时间触发。

对于符合 EXIT 或 CRASH 事件条件的活动，将添加到队列中，并有机会在下次启动时显示，以及任何其他触发的默认事件。

Usabilla 应用 - iOS SDK

要求

安装

SPM

CocoaPods

Carthage

手动

初始化

DebugMode

FooterLogoClickable

活动

应用 ID

目标选项

活动切换

活动提交回调

重新激活活动

重置所有活动

管理现有活动

活动结果

被动反馈

加载表单

预加载表单

iPad 显示

添加屏幕截图

反馈提交回调

FeedbackResult

处理手动关闭

屏蔽私人身份信息

自定义变量

App Store 评分

以编程方式移除表单或活动

强制特定界面方向

UI 自定义

自定义表情符号评分

仅提供选定版本

同时提供选定和未选定版本

自定义星级评分

自定义字体

自定义颜色

本地化

字符串文件内容

权限（可选）

与 Obj-C 应用集成

ThreadSafe

遥测数据收集

在应用中获取用户反馈

标准事件