Quovo Connect SDK for iOS

最新发布

v1.1.14

• 支持 Swift 5.3 编译器在 Xcode 12.0 上使用 xcframework

注意：此版本的 Quovo Connect SDK 只与 Swift 5.3 编译器（Xcode 12.0）兼容。

目录

• 安装
• 使用测试项目
• Quovo Connect SDK
  • 初始化 SDK
  • 可选地指定一个父 ViewController
  • 创建一个完成处理程序
    • 连接 v1 回调
    • 连接 v2 回调
  • 创建一个错误处理器
  • 启动 SDK
  • 关闭 SDK
  • 自定义
    • 自定义导航栏
    • 自定义超时
    • 自定义子域名
    • Connect v1 的选项
    • Connect v2 的选项
    • 预选择机构
    • 更新或解决现有连接上的问题

安装

您可以通过使用 Cocoapods 或手动安装框架来安装 Quovo Connect SDK。

使用 Cocoapods（推荐）

如果需要，安装并设置 Cocoapods：https://guides.cocoapods.org.cn/using/using-cocoapods

1. 将 connect-ios 添加到您的项目中，在您的 Podfile 中添加以下行：pod 'QuovoConnect'。
2. 运行 pod install
3. 打开 xcworkspace

使用 Carthage

如果需要，安装并设置 Carthage：https://github.com/Carthage/Carthage#quick-start

1. 将以下行添加到您的 Cartfile 中以将 connect-ios 添加到您的项目中：binary "https://raw.githubusercontent.com/quovo/connect-ios/master/QuovoConnectSDK.json"。
2. 运行 carthage update
3. 如果 Carthage 成功，您应该在 Carthage/Build/iOS 文件夹中看到框架
4. 将 QuovoConnectSDK.xcframework 拖动到您的项目中（确保选中“如果需要，复制项目”
5. 在'项目导航器'中突出显示您的项目。
6. 选择“构建阶段”标签
7. 在窗口的左上角单击+按钮，然后选择“新建运行脚本阶段”
8. 打开新的“运行脚本”扩展器。
9. 将以下行输入到脚本框中：/usr/local/bin/carthage copy-frameworks
10. 在“输入文件”下单击+按钮，并输入
    
    $(SRCROOT)/Carthage/Build/iOS/QuovoConnectSDK.xcframework
11. 点击“输出文件”下方的+按钮，并输入：$(BUILT_PRODUCTS_DIR)/$(FRAMEWORKS_FOLDER_PATH)/QuovoConnectSDK.xcframework
    （注意：请确保提交您的Cartfile.resolved文件）

可选：警告关于过时的依赖

1. 在窗口的左上角单击+按钮，然后选择“新建运行脚本阶段”
2. 打开新的“运行脚本”扩展器。
3. 将以下行输入到脚本框中：/usr/local/bin/carthage outdated --xcode-warnings

手动安装

1. 从https://github.com/quovo(connect-ios)下载或克隆框架
2. 打开您的项目“常规”设置页面。将QuovoConnectSDK.xcframework拖动到“已嵌入的二进制文件”部分。确保选中“如果需要则复制项”。
3. 在构建阶段窗口的左上角点击+按钮，并选择“新运行脚本阶段”（注意：应该位于“嵌入框架”阶段下方）
4. 打开新的“运行脚本”扩展器。
5. 将以下行输入到脚本框中
   /bin/sh $BUILT_PRODUCTS_DIR/$FRAMEWORKS_FOLDER_PATH/QuovoConnectSDK.xcframework/cleanForAppStore.sh
   此脚本需要绕过一个App Store提交错误

使用测试项目

包含在SDK中的测试项目使用配置plist文件来生成用户令牌。该文件已git忽略，但应该添加到您的测试项目副本中。文件应命名为"configuration.plist"，并包含名为"apiToken"的字符串字段和一个名为"userId"的数字字段。

Quovo Connect SDK

初始化Connect SDK

import QuovoConnectSDK
let quovoConnect = QuovoConnectSDK()

初始化SDK的好地方是在应用启动时或在视图控制器的启动方法中。

可选地指定一个父 ViewController 以该连接

quovoConnect.parentViewController = UIApplication.shared.keyWindow!.rootViewController

这允许你控制 QuovoSDK UI 将在哪个 ViewController 上呈现

为 Connect 创建一个完成处理程序

func complete(callback: String, response: NSDictionary) {
// ...
}

quovoConnect.completionHandler = complete

完成处理程序将使您的应用程序能够监听由 QuovoConnectSDK 触发的事件。处理程序有 2 个参数：一个“回调”方法名称和可选的“响应”有效负载。

Connect v1 回调

connect v1 支持以下“回调”字符串

• open
• load
• close
• add
• sync
• onAuthenticate

在“添加”、“同步”和“onAuthenticate”的情况下，将返回类型为 NSDictionary 的响应有效负载。

Connect v2 回调

connect v2 支持以下“回调”字符串

• open
• load
• close
• add
• sync
• onAuthenticate
• onAuthAccountSelected

在“添加”、“同步”、“onAuthenticate”和 onAuthAccountSelected 的情况下，将返回类型为 NSDictionary 的响应有效负载。

以下是一些示例：

"添加"事件触发

[
"connection": [
"id": 2135634,
"institution": 34,
"user": 1123,
],
"timeStamp": 1496879583157,
]

"同步"事件触发

[
"connection": [
"id": 2135634,
"institution": 34,
"user": 1123,
],
"sync": [
"authenticated": false,
"status": "questions",
],
"timeStamp": 1496879583157,
]

其余回调将返回空响应。有关这些事件的更多信息，请参阅：

(https://api.quovo.com/docs/connect/#custom-integrations)

为 Connect 创建一个错误处理程序

func error(errorType: String, errorCode: Int, errorMessage: String) {
// ...
}

quovoConnect.errorHandler = error

错误处理器将允许您的应用程序监听由 QuovoConnectSDK 触发的错误。处理器具有 3 个参数：一个“errorType”名称、一个“errorCode”标识号码和一个“errorMessage”错误描述字符串。该“errorType”字符串将为以下之一

• 通用
• http

在“http”的情况下，errorCode 字段将是 HTTP 状态码，例如 404。在“通用”的情况下，errorCode 字段可能是一个 iOS 特定代码，例如 CFNetworkError 或 Quovo 特定代码。CFNetworkError 列表请见（《https://developer.apple.com/documentation/cfnetwork/cfnetworkerrors》）Quovo 特定代码包括

• QUOVOERROR_CODE_MISSING_TOKEN: 1

启动 Connect SDK

启动 QuovoConnectSDK 将实例化一个 WebView 体验，允许用户同步和管理他们的账户。启动 WebView 所需的最小参数是 Iframe Token。此 token 必须通过 API 生成，并在第一次使用后过期。

quovoConnect.launch(token: "IFRAME TOKEN HERE")

此 WebView 体验还可以作为 View 创建，可以直接嵌入您的应用程序中。注意：此视图没有布局约束，所以您需要添加自己的。

let quovoView:UIView = quovoConnect.generateView(token: "IFRAME TOKEN HERE")

关闭 Connect SDK

可以通过使用 QuovoConnectSDK 类静态地关闭 QuovoConnectSDK。这允许从父 ViewController 以及推送通知或其他外部信息中关闭 SDK。

QuovoConnectSDK.close()

Connect 自定义

自定义 Connect 标题栏

您还可以自定义 QuovoConnect WebView 的标题栏。可以自定义的标题栏三个方面是透明度、颜色和文本。

isTranslucent 参数将优先于 backGroundColor 参数。

quovoConnect.customizeNavigationBarApperance(
isTranslucent: true,
//The paramater isTranslucent is a boolean that can make the navigation bar  transparent.
backGroundColor: UIColor.white, 
//The backGroundColor parameter allows you to choose the color of the navbar.
customTitle: "Quovo Connect")
//The customTitle parameter allows you to choose the text displayed in the navbar. Passing an empty string will result in no text being displayed.

自定义连接超时

默认情况下，Quovo Connect WebView在尝试连接30秒后超时。可以通过调用setTimeoutLength（它接受一个TimeInterval参数，即一个双精度值）来自定义超时长度（以秒为单位）。当出现超时时，错误将被发送到ErrorHandler，并且WebView将显示一个简单的页面，说明连接已超时。如果您不想显示超时页面，可以在ErrorHandler中捕获错误，在它出现之前或超时之前关闭SDK。

quovoConnect.setTimeoutLength(seconds:5)

自定义连接子域

默认情况下，Connect SDK将连接到原始的Quovo Connect。但是，有一种方法可以使用Connect v2。通过调用setSubdomain（它接受一个String），您可以设置一个自定义子域，在加载connect时使用。如果您想加载Connect v2，可以传递参数connect2。

quovoConnect.setSubdomain(subdomain:"connect2")

或者，您也可以在启动函数内部设置自定义子域。只需在令牌或选项后添加参数subdomain。

quovoConnect.launch(token: "IFRAME TOKEN HERE",subdomain:"connect2")

请注意，如果您既使用setSubdomain又使用launch设置子域，则启动子域将覆盖设置的子域。

Connect v1的选项

您可以选择传递一组参数来控制WebView体验的外观和功能。以下是一个例子

quovoConnect.launch(
token: "IFRAME TOKEN HERE",
options: [
"searchTest": 1,
"topInstitutions": "banks",
]
)

以下是可以传递给launch方法的可选参数列表

Connect v2 选项

您可以选择传递一组参数来控制WebView体验的外观和功能。以下是一个例子

quovoConnect.launch(
token: "IFRAME TOKEN HERE",
options: [
"searchTest": 1,
"topInstitutions": "banks",
]
)

以下是可以提供给 Connect2 launch 方法的可选参数列表

预选择一个机构

您可能希望引导用户为特定的机构添加账户。使用Connect，您可以预先为用户选择一个机构，完全跳过搜索页面。

将预想的Quovo机构ID作为值传递。

HashMap<String, Object> options = new HashMap<>();
// Connect will bypass the search page and open directly to the page to
// add a "Fidelity NetBenefits" Account (which has a Brokerage ID of 23).
options.put("openInstitution", 23);

quovoConnectSdk.launch(userToken, options);

更新或解决现有连接的问题

您可能希望用户更新或解决现有连接的问题。他们可能需要提供额外的MFA答案或更新最近更改的登录凭证。使用Connect，您只需传递一个账户ID，就可以引导用户修复这些问题，让他们的账户继续同步。状态为“登录”的连接将带到一个屏幕，用户可以在其中更新他们的凭证，而状态为“问题”的连接将带到一个屏幕，用户将被提示回答额外的MFA问题。

如果向launch同时传递了openConnection和openInstitution参数，则openConnection工作流将具有优先权。

quovoConnect.launch(
token: "IFRAME TOKEN HERE",
options: [
// Account 813981 has a status of "questions", so Connect will open to a
// page where the user can answer any outstanding MFA questions and resync
// the Account accordingly.
"openConnection": 813981,
]
)