MopinionSDKWeb 0.7.2

MopinionSDKWeb 0.7.2

×

由 Mopinion，Mopinion 维护。

MopinionSDKWeb 0.7.2

  • 由
  • Floris Snuif，Anwar Jebali 和 Kees van Welsenis

Mopinion 移动 Web SDK iOS

Mopinion 移动 SDK 可以用来根据事件收集 iOS apps 的反馈。要在您的应用中使用 Mopinion 移动 Web 反馈表单，您可以将 SDK 作为 Framework 添加到 Xcode 项目中。

其他 Mopinion SDK 也可用

内容

版本 0.5.2 的发行说明

0.5.2 的更改

  • 使用 Xcode 14.1 重建，在 iOS 16 上测试。
  • 删除了 32 位支持。
  • CocoaPods 最低 iOS 版本提升至 11。
  • 删除了未使用的设置。
  • 将额外/元数据插入 Web 表单中的功能提前。
  • 下载的部署被缓存，至少 30 分钟后才重新加载。

注释

  • 本readme已包含在github发布版本0.5.2-swiftpm中，该版本已重新打包供Swift Package Manager使用。此版本不适用于cocoapods。
  • 对于cocoapods，请仅使用纯0.5.2发布版。

安装

Mopinion Mobile SDK框架可以通过Swift Package Manager或流行的依赖管理器Cocoapods进行安装。

在Xcode 14中通过Swift Package Manager安装

  1. 如果您不想再在项目中使用CocoaPods，请然后在终端中，执行以下命令：
    pod deintegrate

  2. 打开您的项目文件<你的项目名称>.xcodeproj。

  3. 在Xcode 14中，从菜单中选择文件 -> 添加包…。
    将出现Swift Package Collections面板。

  4. 在面板的搜索字段中输入https://github.com/mopinion/mopinion-sdk-ios-web并按回车。

  5. 在Dependency Rule下拉按钮中，选择Exact Version并在版本字段中输入0.5.2-swiftpm。

  6. 点击按钮添加包。将出现一个包产品选择面板。

  7. 选择MopinionSDK并点击按钮添加包。


在基于ARM的Macs上安装CocoaPods原生版本

从macOS Monterey 12.1开始，cocoapods 1.11.2的安装可以无障碍完成。

sudo gem install cocoapods

使用CocoaPods安装SDK

对于Xcode 14，在项目的根目录下创建一个Podfile。

platform :ios, '11.0'
use_frameworks!
target '<YOUR TARGET>' do
	pod 'MopinionSDKWeb', '>= 0.5.2'
end

安装所需的pods。

$ pod install

之后，您应该使用新创建的 <your-project-name>.xcworkspace 文件在 Xcode 中打开。


实现 SDK

在您的应用代码中，例如 AppDelegate.swift 文件中，添加以下内容：

import MopinionSDK
...
// debug mode
MopinionSDK.load(<MOPINION DEPLOYMENT KEY>, true)
// live
MopinionSDK.load(<MOPINION DEPLOYMENT KEY>)

将 <MOPINION DEPLOYMENT KEY> 替换为您特定的部署密钥。您可以使用网络浏览器从您的 Mopinion 账户在侧菜单中复制此密钥：数据收集，部署 部分，通过带有符号 <> 的按钮。

在一个 UIViewController，例如 ViewController.swift，添加以下内容：

import MopinionSDK
...
MopinionSDK.event(self, "_button")

`"_button"` 是默认的被动形式事件。您也可以创建自定义事件并在 Mopinion 部署界面中使用它们。
在 Mopinion 系统中，您可以在用户执行事件时启用或禁用反馈表单。事件可以是按钮的触摸、交易结束时、主动的等。


附加数据

从版本 0.3.1 开始，您还可以从应用发送附加数据到表单。这可以通过向 data() 方法添加一个键和一个值来实现。如果您想在弹出表单中包含该数据，请在调用 event() 方法之前添加数据。

MopinionSDK.data(_ key: String, _ value: String)

示例

import MopinionSDK
...
MopinionSDK.load("abcd1234")
...
MopinionSDK.data("first name", "Steve")
MopinionSDK.data("last name", "Jobs")
...
MopinionSDK.event(self, "_button")

注意：在元数据集中，键是唯一的。如果您重用一个键，该键的先前值将被覆盖。

清除附加数据

从版本 0.3.4 开始，您可以使用 data(key,value) 方法删除先前提供的所有或单个键值对。要删除单个键值对，请使用此方法

MopinionSDK.removeData(forKey: String)

示例

MopinionSDK.removeData(forKey: "first name")

要删除所有提供的附加数据，请使用此方法而不带参数

MopinionSDK.removeData()

示例

MopinionSDK.removeData()

评估表单是否会打开

SDK的event()方法会自主检查部署条件并打开表单，或者不打开。

从SDK版本0.4.6开始，您可以使用evaluate()和相关方法为您的应用程序提供更多控制，以主动打开表单或在没有表单未打开时进行操作。

它也可以用于被动事件，但此类表单始终允许打开。

流程概述

  1. 调用evaluate()方法，并传递实现MopinionOnEvaluateDelegate协议的委托对象。
  2. 在您的委托的回调方法mopinionOnEvaluateHandler()中，检查响应参数并检索任何存在的formKey。
  3. 可选地，将formKey传递给openFormAlways()方法以直接打开您的表单，忽略部署中的任何条件。

evaluate()方法

评估是否为指定事件打开表单。如果没有错误，委托对象将收到带有响应的mopinionOnEvaluateHandler()调用。

public func evaluate( _ event: String, onEvaluateDelegate: MopinionOnEvaluateDelegate )

参数

  • event：在部署中定义的事件名称。例如，“_button”。
  • onEvaluateDelegate：实现MopinionOnEvaluateDelegate协议的对象，用于处理mopinionOnEvaluateHandler()回调方法。

mopinionOnEvaluateHandler()方法

方法，其中应用程序接收评估调用响应。由MopinionOnEvaluateDelegate协议定义。注意，在系统错误的情况下，这可能根本不会被调用。

func mopinionOnEvaluateHandler(hasResult: Bool, event: String, formKey: String?, response: [String : Any]?)

参数

  • hasResult：如果为true，则按formKey识别的表单将打开。如果为false，则表单不会打开，且formKey可能为null，因为在事件中没有找到与表单关联的表单。
  • event：传递给评估调用的原始事件名称，以在部署中进行检查。
  • formKey：与事件相关联的第一个反馈表单的标识键。即使部署中多个表单与事件名称匹配，也只选择一个formKey。
  • response：可选的字典对象，用于提供成功/失败和表单的额外响应详细信息。预留供未来扩展使用。

openFormAlways() 方法

无论部署中设置了哪些主动条件，都会打开由formkey指定的表单。

public func openFormAlways(_ parentView: UIViewController,_ formKey: String)

参数

  • parentView：您可作为SDK父视图控制器的UIViewController对象。
  • formKey：由mopinionOnEvaluateHandler()调用提供的反馈表单的key。

使用 evaluate() 的示例

伪代码片段突出了上述过程中的一些关键点，如何在实现 MopinionOnEvaluateDelegate 协议时进行整合。

...
import MopinionSDK
...
// assuming that in your AppDelegate, you already did MopinionSDK.load(<MOPINION DEPLOYMENT KEY>)
...
class ViewController: UIViewController, MopinionOnEvaluateDelegate {
...
    func doSomething() {
        // check if a form would open                       
        MopinionSDK.evaluate("_myproactiveevent", onEvaluateDelegate: self)
        // the actual result will be in the mopinionOnEvaluateHandler call
	}
...
	// callback handler for protocol MopinionOnEvaluateDelegate
    func mopinionOnEvaluateHandler(hasResult: Bool, event: String, formKey: String?, response: [String : Any]?) {
        if(hasResult) {
            // at least one form was found and all optional parameters are non-null
            // because conditions can change every time, use the form key to open it directly
          	MopinionSDK.openFormAlways(self, formKey!)
        }else{
            if let _ = formKey {
				// Found form wouldn't open for event
				 // we'll open it anyway using the formKey             
				MopinionSDK.openFormAlways(self, formKey!)
            }else{
				// no form found for event
				...
            }
        }
    }
...

使用回调模式

默认情况下，SDK独立管理反馈表单，不再进一步涉及您的应用。SDK版本 0.5.0 引入了回调来通知您的代码某些操作（MopinionCallbackEvent）。

提供回调处理程序以接收包含数据或可能的错误信息的响应。

流程概述

  1. 调用 event() 方法，并传递实现 MopinionCallbackEventDelegate.onMopinionEvent 协议的回调方法。
  2. 在您的回调方法 onMopinionEvent() 中，检查 mopinionEvent 的类型，并可选择在 response 上调用 didSucceed() 或 hasErrors() 检查错误。
  3. 可选的，在 response 对象上调用 hasData() 以检查是否存在数据。
  4. 根据mopinionEvent的类型，使用response上的方法hasData(ResponseDataKey)检查是否包含由ResponseDataKey指定的数据。
  5. 要获取数据，根据需要检索的数据类型，在response上调用getString(ResponseDataKey)或getJSONObject(ResponseDataKey)。

您还可以提供可选的错误回调处理程序到event()，以接收包含错误信息的响应。在这种情况下，主处理程序仅接收不带错误的响应。


事件方法的回调变体

触发你在部署中定义的事件，以打开表单并接收MopinionCallbackEvent回调。如果不指定failHandler，回调处理程序也将接收错误响应。

func event(parentView: event: onCallbackEvent:  onCallbackEventError:)
func event(parentView: event: onCallbackEventDelegate:)
func event(parentView: event: onCallbackEventDelegate:  onCallbackEventErrorDelegate:)

参数

  • parentView：作为应用程序父视图使用的UIViewController。
  • event：在部署中为表单定义的事件名称。例如，“_button”。
  • onCallbackEvent：一个实现了onMopinionEvent()回调的闭包。
  • onCallbackEventError：一个实现了onMopinionEventError()回调的闭包，用于MopinionCallbackEvent中出现的错误。
  • onCallbackEventDelegate：实现了MopinionCallbackEventDelegate协议的对象，用于处理onMopinionEvent()回调。
  • onCallbackEventErrorDelegate：实现了MopinionCallbackEventErrorDelegate协议的对象，用于处理因错误引发的onMopinionEventError()回调。

回调方法onMopinionEvent()和onMopinionEventError()

在您的代码中实现这些方法以接收MopinionCallbackEvent。它们具有相同的参数，以传递一个响应，该响应包含可选的附加信息。提供的信息取决于MopinionCallbackEvent的类型和其来源。

func onMopinionEvent(mopinionEvent: MopinionCallbackEvent, response: MopinionResponse)
func onMopinionEventError(mopinionEvent: MopinionCallbackEvent, response: MopinionResponse)

参数

  • mopinionEvent：从SDK接收的响应事件类型。目前是以下之一

    • FORM_OPEN：当表单显示时
    • FORM_SENT：当用户提交表单时
    • FORM_CLOSED：当表单关闭时

  • response：包含有关MopinionEvent附加信息的MopinionResponse对象。响应永远不会是nil，但可以使用其hasData()方法检查它是否包含任何附加数据，或使用hasErrors()检查错误。


MopinionResponse对象

此对象中的数据收集依赖于MopinionCallbackEvent的类型及其来源。数据是一个键值集合。数据和错误都可以不存在。响应对象包含了检查和检索它们的方法。

使用response.get()和response.hasData()获取数据

首先使用hasData(key)进行检查，因为get<>(key)方法可能返回null。传递一个标准的ResponseDataKey到这些方法，以获取您感兴趣的数据。

ResponseDataKey 读取它的方法 描述
DATA_JSONOBJECT .getJSONObject() 包含所有可用的'原始'JSONObject的字典
FORM_KEY .getString() 表单的内部唯一标识符
FORM_NAME .getString() 表单的名称。与表单的标题不同。

MopinionCallbackEvents和响应中提供的数据

这是某个MopinionCallbackEvent可能存在的数据

MopinionCallbackEvent ResponseDataKeys 备注
FORM_OPEN DATA_JSONOBJECT
  FORM_KEY
  FORM_NAME
FORM_SENT DATA_JSONOBJECT
  FORM_KEY
  FORM_NAME
FORM_CLOSED DATA_JSONOBJECT 当前只有自动关闭的表单提供数据
  FORM_KEY 仅当自动关闭时
  FORM_NAME 仅当自动关闭时

MopinionCallbackEvents的发生顺序是

1. FORM_OPEN
2. FORM_SENT (only if the user submits a form)
3. FORM_CLOSED

读取response错误

调用response.hasErrors()，接着调用response.getError()以获取错误对象。getError()方法可能返回nil。


回调处理程序示例：在发送后运行代码

伪代码，以展示如何使用event()回调和关闭相关的对象实现发送后运行代码。您必须等待发送后表单关闭，然后才能运行影响您UI的任何代码。

...
import MopinionSDK
...
// assuming that in your AppDelegate, you already did MopinionSDK.load(<MOPINION DEPLOYMENT KEY>)
...
class YourViewController: UIViewController, MopinionOnEvaluateDelegate {
...
    var wasFormSent: Bool = false	// track state outside closure
...
    func demonstrateMopinionCallback() {
        self.wasFormSent = false
    
        // open the form associated with the event "_myfeedbackbutton" from the deployment and receive callbacks in the closures        
        MopinionSDK.event(self, "_myfeedbackbutton", onCallbackEvent: {  (mopinionEvent, response) -> (Void) in
            print("callback in success closure")
            if(mopinionEvent == .FORM_SENT) {
                let formKey = response.getString(.FORM_KEY)!
                print("The form with formKey=\(formKey) has been sent, but is still displayed")
                self.wasFormSent = true
            } else if(mopinionEvent == .FORM_CLOSED) {
                if(self.wasFormSent) {
                    let formKey = response.getString(.FORM_KEY) ?? ""
                    print("The form \(formKey) has beent sent and closed, now you can run some code.")
                }
            }

        }, onCallbackEventError: { (mopinionEvent, response) -> (Void) in
            let myError = response.getError();
            print("there was an error during callback: \(String(describing: myError))")
        } )
	}
...
}
...

编辑触发器

在Mopinion部署编辑器中，您可以定义与您应用中使用的SDK事件名协同工作的事件名和触发器。登录您的Mopinion账户，转到数据收集，部署，以使用此功能。

Deployment Editor

自定义定义的事件可以与规则/条件结合使用。

  • 触发器：被动或主动。被动表单始终在事件触发时显示。主动表单只显示一次，您可以设置表单显示的刷新持续时间。
  • 提交：允许打开一个主动表单，直到至少提交一次。这会影响触发规则，允许打开一次以上的表单。自SDK版本0.4.3开始支持此功能。
  • 百分比（主动触发）：应看到表单的用户百分比。
  • 日期：仅在特定日期，日期范围之后或之前显示表单。
  • 时间：仅在特定时间，时间范围之后或之前显示表单。
  • 目标：仅针对特定操作系统（iOS或Android）以及可选版本列表显示表单。