MopinionSDK 1.1.3

MopinionSDK 1.1.3

×

由 Mopinion 和 Mopinion 维护。

MopinionSDK 1.1.3

  • 作者
  • Floris Snuif, Anwar Jebali 和 Kees van Welsenis

Mopinion 移动 SDK iOS

Mopinion 移动 SDK 可以用来基于事件收集 iOS 应用的反馈。要使用 Mopinion 移动反馈表单，您可以将 SDK 作为 Framework 包含在您的 Xcode 项目中。

这里还有一个可用于 Android 的 Mopinion 移动 SDK 在此处。

您可以通过从 Apple iOS App Store 下载我们的 Mopinion Forms 预览应用程序来查看您的移动表单将如何在您的应用程序中显示。

内容

0.6.1 版本的发行说明

0.6.1 版本中的改进

  • 修复了在 iOS 15 中，对于“web”类型的表单，额外/元数据截图可能消失的问题。

备注

  • 我们的SDK已在0.66.3版本的react-native和Xcode 13.1下进行测试。
  • 提示：如果在开发过程中您看不到表单设计更改，请移除并重新安装您的应用。这将清除设备缓存，通常需要几小时才能刷新。

安装

Mopinion移动SDK框架可以通过流行的依赖关系管理器Cocoapods进行安装。SDK部分使用React Native构建，需要一些框架才能运行。

在基于ARM的Mac上安装CocoaPods原生

对于macOS Monterey 12.1，cocoapods 1.11.2的安装是即插即用的。

sudo gem install cocoapods

如果您已在macOS Big Sur 11上应用以下补丁，请先移除它。

用于在基于ARM的Mac上安装较早版本的CocoaPods原生

具有ARM处理器的Macs需要较新的Ruby工具链才能通过网络使用CocoaPods。对于cocoapods 1.11.2和macOS Monterey除外，但对于macOS Big Sur，您可以尝试此过程。

为了防止LoadError - dlopen(/Library/Ruby/Gems/2.6.0/gems/ffi-1.14.2/lib/ffi_c.bundle, 0x0009)错误导致构建失败

  1. 安装Xcode 12.5（或更高版本）的命令行工具（即使您已安装完整的Xcode IDE版本）
  2. 安装macports
  3. 在终端中执行
sudo port install ruby27
sudo port select --set ruby ruby27
source .zprofile # or .profile, whereever you defined your $PATH
sudo gem update
sudo gem install ffi
sudo gem install cocoapods

在macOS Big Sur 11.4，Xcode 12.5，macports 2.7.1，ruby 2.7.3p183，cocoapods 1.10.1上进行了测试，能够正常工作

向家酿用户报告的本地cocoapods安装

对于家酿用户，过程略有不同，请参考github

  1. 更新至至少 macOS Big Sur 11.3.1
  2. 安装家酿
  3. 将ruby更新至至少 2.7.3
brew install rbenv
rbenv init
rbenv install 2.7.3
export RBENV_VERSION=2.7.3 # or however you set your ruby version
  1. 安装cocoapods
brew install cocoapods

使用Cocoapods和React Native (Node.js)安装

首先，使用Node.js安装React Native框架。

通过macports或homebrew安装Node.js/npm

然后在项目根目录创建一个package.json文件

{
  "name": "YourApp",
  "version": "0.0.1",
  "scripts": {
    "start": "react-native start"
  },
  "dependencies": {
    "@react-native-async-storage/async-storage": "^1.15.14",
    "create-react-class": "^15.7.0",
    "react": "17.0.2",
    "react-native": "0.66.3",
    "react-native-image-picker": "^3.8.1",
    "react-native-webview": "^11.15.0"
  }
}

接下来，执行：$ npm install

现在创建一个如下所示的Podfile文件（假设node_modules文件夹与Podfile在同一位置），使用Cocoapods安装所有内容

source 'https://github.com/CocoaPods/Specs.git'

platform :ios, '11.0'
require_relative './node_modules/react-native/scripts/react_native_pods'
require_relative './node_modules/@react-native-community/cli-platform-ios/native_modules'
use_frameworks!
target '<YOUR TARGET>' do
	pod 'MopinionSDK',  '>= 0.6.1'
  config = use_native_modules!

  use_react_native!(
	  # Your 'node_modules' directory is probably in the root of your project,
	  # but if not, adjust the `:path` accordingly
    :path => config[:reactNativePath],
    # to enable hermes on iOS, change `false` to `true` and then install pods
    :hermes_enabled => false
  )

  post_install do |installer|
    react_native_post_install(installer)
    __apply_Xcode_12_5_M1_post_install_workaround(installer)
  end

end

然后运行

$ pod install

完成这些后，您应该在Xcode中使用新创建的<YourApp>.xcworkspace文件。

注意：第一次Xcode可能无法构建xcworkspace。通常情况下，清理并重新构建/运行可以解决此错误。

字体

SDK包含一个字体，应该将其添加到项目的Info.plist文件中的字体列表。

在Xcode中，将此字体添加到应用的Info.plist的Fonts provided by application

  • Frameworks/MopinionSDK.framework/FontAwesome.ttf

向您的应用添加图片库使用权限

SDK允许用户从设备中选择图片作为截图上传。为了符合iOS App Store对用户隐私的要求，在Xcode中确保将Privacy - Photo Library Usage Description权限添加到应用的Info.plist

<key>NSPhotoLibraryUsageDescription</key>
<string>You can upload an image from your library for use as a screenshot</string>

实现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.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独立管理反馈表单，不再进一步涉及您的应用程序。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() 提供一个可选的错误回调处理程序，以单独接收包含错误信息的响应。在这种情况下，主要处理程序只接收无错误的响应。


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() 回调，用于处理产生错误的 MopinionCallbackEvents。
  • onCallbackEventDelegate：实现 MopinionCallbackEventDelegate 协议的对象，以处理 onMopinionEvent() 回调。
  • onCallbackEventErrorDelegate：实现 MopinionCallbackEventErrorDelegate 协议的对象，以处理产生错误的 onMopinionEventError() 回调。

onMopinionEvent() 和 onMopinionEventError() 回调方法

您可以在代码中实现这些方法以接收 MopinionCallbackEvents。它们具有相同的参数，用于传递带有可选额外信息的响应。提供的信息取决于 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() 所有可用数据的 'raw' JSONObject 的字典
FORM_KEY .getString() 表单的内部唯一标识符
FORM_NAME .getString() 表单的名称。与表单的标题不同。

MopinionCallbackEvents 和 response 中的提供数据

这是特定 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 仅当自动关闭时

MopinionCallbackEvent 发生顺序是

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）中显示表单