HyperwalletUISDK 1.0.0-beta21

HyperwalletUISDK 1.0.0-beta21

×

由 Debojit Dhar，Peter Olamit，Blair Olynyk，Jaspreet Saini，Flavio Ferreira de Mattos，Gustavo Meyer，Maximilian Was Damji 维护。

HyperwalletUISDK 1.0.0-beta21

  • 由
  • Hyperwallet Systems Inc

Hyperwallet UI SDK

Platforms Build Status Coverage Status

CocoaPods Carthage compatible

注意：这是一个可用于您移动应用的测试版产品。如果您有兴趣使用此产品，请通知您的客户经理和/或项目经理以在集成过程中支持您。

欢迎使用 Hyperwallet 的 iOS UI SDK。此开箱即用的库将帮助您在 iOS 应用中创建转账方式，例如银行账户、PayPal 账户等。

请注意，此 SDK 适用于需要后端数据和 UI 功能的用户。如果您决定自己构建 UI，请参阅 Hyperwallet iOS Core SDK。

必备条件

  • Hyperwallet 商户账户
  • 设置您的服务器以在 Hyperwallet 平台上管理用户的身份验证过程。有关更多信息，请参阅 身份验证 部分。
  • iOS 13.0+
  • Xcode 10.2+
  • Swift 5.0

依赖关系

安装

使用Carthage或CocoaPods集成到HyperwalletSDK。目前，以下模块可用

  • TransferMethod - 列出、添加或删除转账方式
  • Transfer - 从用户账户或预付卡创建转账到用户的可用账户
  • Receipt - 列出用户/预付卡收据 添加其中一个或多个框架允许用户探索特定功能。如果需要所有功能，应添加所有框架

Carthage

在Cartfile中指定它

github "hyperwallet/hyperwallet-ios-ui-sdk" "1.0.0-beta18"

使用Linked Frameworks and Libraries选项添加所需的模块，以便在应用程序中可用。使用import <module-name>在文件中添加依赖项

CocoaPods

  • 安装特定的框架（根据需求安装一个或多个框架）
pod "HyperwalletUISDK/TransferMethod", "1.0.0-beta18"
pod "HyperwalletUISDK/Transfer", "1.0.0-beta18"
pod "HyperwalletUISDK/Receipt", "1.0.0-beta18"
  • 要安装所有可用模块（TransferMethod，Transfer，Receipt）
pod 'HyperwalletUISDK', '~> 1.0.0-beta18'

使用import HyperwalletUISDK在文件中添加依赖项。

初始化

安装SDK之后，您需要初始化一个实例来使用SDK的核心功能。同时，您需要提供一个HyperwalletAuthenticationTokenProvider对象来获取身份验证令牌。

设置UI样式

HyperwalletUISDK为所有模块（例如TransferMethod、Receipt）提供了默认主题。如果您导入了HyperwalletUISDK，为了应用默认主题，您需要调用ThemeManager.applyTheme()，这将把基本主题应用到ProcessingView和SpinnerView。如果您想要自定义UINavigationBar的主题，添加ThemeManager.applyToUINavigationBar()。例如

...
@UIApplicationMain
class AppDelegate: UIResponder, UIApplicationDelegate {
    var window: UIWindow?

    func application(_ application: UIApplication,
                     didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {

        // Optional - Define the HyperwalletUISDK on the `Theme` object. See the section `Customize the visual style`.

        // Set the default tint color
        window?.tintColor = .systemBlue
        // Avoid to display a black area during the view transaction in the UINavigationBar.
        window?.backgroundColor = Theme.UITableViewController.backgroundColor

        // Apply basic theme
        ThemeManager.applyTheme()
        return true
    }
}

您也可以根据需求自定义默认主题。请参阅[自定义视觉样式](#Customize the visual style)获取详细信息。

设置认证

在头部添加

import HyperwalletUISDK

使用HyperwalletAuthenticationTokenProvider实现实例初始化HyperwalletUISDK

HyperwalletUI.setup(_ :HyperwalletAuthenticationTokenProvider)

认证

您的服务器端应能够向Hyperwallet端点/rest/v3/users/{user-token}/authentication-token发送POST请求以检索身份验证令牌。然后，您需要提供一个类（一个身份验证提供者），实现HyperwalletAuthenticationTokenProvider接口以从您的服务器检索身份验证令牌。

使用Swift Foundation中的URLRequest的示例实现

public struct AuthenticationTokenProviders: HyperwalletAuthenticationTokenProvider {
    private let url = URL(string: "http://your/server/to/retrieve/authenticationToken")!

    public func retrieveAuthenticationToken(
        completionHandler: @escaping HyperwalletAuthenticationTokenProvider.CompletionHandler) {

        var request = URLRequest(url: url)
        request.httpMethod = "POST"
        request.addValue("application/json", forHTTPHeaderField: "Content-Type")

        let defaultSession = URLSession(configuration: .default)
        let task = defaultSession.dataTask(with: request) {(data, response, error) in
            DispatchQueue.main.async {
                guard let data = data,
                    let clientToken = String(data: data, encoding: .utf8),
                    let response = response as? HTTPURLResponse else {
                        completionHandler(nil, HyperwalletAuthenticationErrorType.unexpected(error?.localizedDescription ??
                        "authentication token cannot be retrieved"))
                        return
                }

                switch response.statusCode {
                    case 200 ..< 300:
                        completionHandler(clientToken, nil)

                    default:
                        completionHandler(nil, HyperwalletAuthenticationErrorType
                            .unexpected("authentication token cannot be retrieved"))
                }
            }
        }
        task.resume()
    }
}

用法

完成身份验证后，UI SDK中的函数可投入使用。

用户的转账方式（银行账户、信用卡、PayPal账户、预付卡、纸质支票）

在头部添加

import HyperwalletSDK
import HyperwalletUISDK

列出用户的转账方式

用户可以停用或添加新的转账方式。

let coordinator = HyperwalletUI.shared.listTransferMethodCoordinator(parentController: self)
coordinator.navigate()

根据国家和货币选择可用的转账方式类型

let coordinator = HyperwalletUI.shared.selectTransferMethodTypeCoordinator(parentController: self)
coordinator.navigate()

此外，添加以下方法以关闭显示的视图并根据创建的转账方式执行任何操作。

override public func didFlowComplete(with response: Any) {
    if let transferMethod = response as? HyperwalletTransferMethod {
    navigationController?.popViewController(animated: false)
    }
}

创建转账方式

表单字段基于国家、货币、用户个人资料类型和转账方式类型。应将这些值传递给此方法以创建新的转账方式。

let coordinator = HyperwalletUI.shared.addTransferMethodCoordinator(
    "US", // The 2 letter ISO 3166-1 country code.
    "USD", // The 3 letter ISO 4217-1 currency code.
    "INDIVIDUAL", // The profile type. Possible values - INDIVIDUAL, BUSINESS.
    "BANK_ACCOUNT", // The transfer method type. Possible values - BANK_ACCOUNT, BANK_CARD, PAYPAL_ACCOUNT
    parentController: self)
coordinator.navigate()

此外，在成功创建转账方式后，添加以下方法以关闭显示的视图并根据创建的转账方式执行任何操作。

override public func didFlowComplete(with response: Any) {
    if let transferMethod = response as? HyperwalletTransferMethod {
    navigationController?.popViewController(animated: false)
    }
}

更新转账方式

let coordinator = HyperwalletUI.shared.updateTransferMethodCoordinator(
    "your-transfer-method-token", // The transfer method token
    parentController: self)
coordinator.navigate()

列出用户收据

let coordinator = HyperwalletUI.shared.listUserReceiptCoordinator(parentController: self)
coordinator.navigate()

列出预付卡的收据

let coordinator = HyperwalletUI.shared.listPrepaidCardReceiptCoordinator(parentController: self, prepaidCardToken: "your-prepaid-card-token")
coordinator.navigate()

列出所有可用来源的收据

let coordinator = HyperwalletUI.shared.listAllAvailableSourcesReceiptCoordinator(parentController: self)
coordinator.navigate()

从用户账户中发起新转账

为了在转账模块中添加新的转账方式，需要在应用程序中将TransferMethod模块添加为依赖项。如果未添加TransferMethod模块，则用户无法在转账流程中添加新的转账方式。

let clientTransferId = UUID().uuidString.lowercased()
let coordinator = HyperwalletUI.shared
            .createTransferFromUserCoordinator(clientTransferId: clientTransferId, parentController: self)
coordinator.navigate()

还需要添加以下方法，以便在成功创建转账后关闭显示的视图并根据创建的转账执行任何操作。

override public func didFlowComplete(with response: Any) {
    if let statusTransition = response as? HyperwalletStatusTransition, let transition = statusTransition.transition {
        if transition == HyperwalletStatusTransition.Status.scheduled {
            navigationController?.popViewController(animated: false)
        }
    }
}

从预付卡中发起新转账

let clientTransferId = UUID().uuidString.lowercased()
let coordinator = HyperwalletUI.shared
            .createTransferFromPrepaidCardCoordinator(clientTransferId: clientTransferId,
                                                      sourceToken: "your-prepaid-card-token",
                                                      parentController: self)
coordinator.navigate()

还需要添加以下方法，以便在成功创建转账后关闭显示的视图并根据创建的转账执行任何操作。

override public func didFlowComplete(with response: Any) {
    if let statusTransition = response as? HyperwalletStatusTransition, let transition = statusTransition.transition {
        if transition == HyperwalletStatusTransition.Status.scheduled {
            navigationController?.popViewController(animated: false)
        }
    }
}

显示所有可用来源以满足新的转账需求。用户可以从中选择转账来源并从该来源发起新的转账

let clientTransferId = UUID().uuidString.lowercased()
let coordinator = HyperwalletUI.shared
            .createTransferFromAllAvailableSourcesCoordinator(clientTransferId: clientTransferId,
                                                              parentController: self)
coordinator.navigate()

还需要添加以下方法，以便在成功创建转账后关闭显示的视图并根据创建的转账执行任何操作。

override public func didFlowComplete(with response: Any) {
    if let statusTransition = response as? HyperwalletStatusTransition, let transition = statusTransition.transition {
        if transition == HyperwalletStatusTransition.Status.scheduled {
            navigationController?.popViewController(animated: false)
        }
    }
}

NotificationCenter Events

通知名称 描述
Notification.Name.transferMethodAdded 新转账方式（银行账户、银行卡、PayPal账户、预付卡、纸质支票）已创建时发布。
Notification.Name.transferMethodDeactivated 转账方式（银行账户、银行卡、PayPal账户、预付卡、纸质支票）已停用时发布。
Notification.Name.transferCreated 资金转账已创建时发布。
Notification.Name.transferScheduled 当资金转账已计划时发布。
Notification.Name.authenticationError 当 SDK 无法从客户端实现中获取新的身份验证令牌时发布。客户端可以选择在接收到此通知时关闭应用程序/登出/导航到其他屏幕。

当对象将自己添加为观察者时，它指定应接收哪些通知。因此，一个对象可能需要多次调用此方法，以便将自己注册为多个不同通知的观察者。

如何使用 Notification.Name.transferMethodAdded

override public func viewDidLoad() {
    super.viewDidLoad()
    ...
    NotificationCenter.default.addObserver(self,
                                        selector: #selector(didCreateNewTransferMethodNotification(notification:)),
                                        name: Notification.Name.transferMethodAdded, object: nil)
}

@objc func didCreateNewTransferMethodNotification(notification: Notification) {
    if let transferMethod = notification.userInfo![UserInfo.transferMethodAdded] as? HyperwalletTransferMethod {
        // A new transfer method has been created
    }
}

如何使用 Notification.Name.transferMethodDeactivated

override public func viewDidLoad() {
    super.viewDidLoad()
    ...
    NotificationCenter.default.addObserver(self,
                                        selector: #selector(didTransferMethodDeactivatedNotification(notification:)),
                                        name: Notification.Name.transferMethodDeactivated, object: nil)
}

@objc func didTransferMethodDeactivatedNotification(notification: Notification) {
    if let statusTransition = notification.userInfo![UserInfo.transferMethodDeactivated] as? HyperwalletStatusTransition {
        // A transfer method has been deactivated.
    }
}

如何使用 Notification.Name.transferCreated

override public func viewDidLoad() {
    super.viewDidLoad()
    ...
    NotificationCenter.default.addObserver(self,
                                        selector: #selector(didTransferCreatedNotification(notification:)),
                                        name: Notification.Name.transferCreated, object: nil)
}

@objc func didTransferCreatedNotification(notification: Notification) {
    if let transfer = notification.userInfo![UserInfo.transferCreated] as? HyperwalletTransfer {
        // A transfer has been created.
    }
}

如何使用 Notification.Name.transferScheduled

override public func viewDidLoad() {
    super.viewDidLoad()
    ...
    NotificationCenter.default.addObserver(self,
                                        selector: #selector(didTransferScheduledNotification(notification:)),
                                        name: Notification.Name.transferScheduled, object: nil)
}

@objc func didTransferScheduledNotification(notification: Notification) {
    if let statusTransition = notification.userInfo![UserInfo.transferScheduled] as? HyperwalletStatusTransition {
        // A transfer has been scheduled.
    }
}

如何使用 Notification.Name.authenticationError

override public func viewDidLoad() {
super.viewDidLoad()
...
NotificationCenter.default.addObserver(self,
selector: #selector(didAuthenticationErrorOccur(notification:)),
name: Notification.Name.authenticationError, object: nil)
}

@objc func didAuthenticationErrorOccur(notification: Notification) {
// Logout/ navigate to any other screen
}

自定义视觉样式

UI SDK 旨在使 UI 风格化过程尽可能简单。`Theme.swift` 对象负责 UI 自定义。

使用 `application(_:didFinishLaunchingWithOptions:)` 方法自定义 SDK 的用户界面。

可以在 Theme 中自定义以下属性

属性 默认值 描述
Theme.themeColor 0x00AFD0 主色调
Theme.tintColor UIColor.white 着色色
Theme.Label.color UIColor(rgb: 0x2C2E2F) 标签主要颜色
Theme.Label.errorColor 0xFF3B30 错误突出显示颜色
Theme.Label.subtitleColor UIColor(rgb: 0x3c3c43, alpha: 0.6) 副标题颜色
Theme.Label.textColor 0x8e8e93 文字颜色
Theme.Label.titleFont UIFont.preferredFont(forTextStyle: .body) 标题字体样式
Theme.Label.subtitleFont UIFont.preferredFont(forTextStyle: .subheadline) 副标题字体样式
Theme.Label.footnoteFont UIFont.preferredFont(forTextStyle: .footnote) 注脚字体样式
Theme.Label.textSelectionColor UIColor(rgb: 0x00AFD0).withAlphaComponent(0.14) 文字选择颜色
Theme.NavigationBar.barStyle UIBarStyle.default UINavigationBar 的栏样式。
Theme.NavigationBar.isTranslucent false 设置不透明背景颜色
Theme.NavigationBar.shadowColor UIColor.clear NavigationBar 阴影颜色
Theme.NavigationBar.largeTitleColor UIColor.white UINavigationBar 大标题颜色
Theme.NavigationBar.titleColor UIColor.white UINavigationBar 标题颜色
Theme.NavigationBar.backButtonColor UIColor.white UINavigationBar 返回按钮颜色
Theme.NavigationBar.largeTitleFont UIFont.preferredFont(forTextStyle: .largeTitle) UINavigationBar 大标题字体
Theme.NavigationBar.titleFont UIFont.preferredFont(forTextStyle: .body) UINavigationBar 标题字体
Theme.Button.color UIColor(rgb: 0xFFFFFF) 按钮主要颜色
Theme.Button.linkColor Theme.themeColor 按钮链接颜色
Theme.Button.font Theme.Label.bodyFont 按钮字体
Theme.Button.linkFont Theme.Label.titleFont 链接按钮字体
Theme.Button.backgroundColor Theme.themeColor 按钮背景颜色
Theme.Text.font UIFont.preferredFont(forTextStyle: .body) 文字字体样式
Theme.Text.labelFont Theme.Label.titleFont 文字标签字体样式
Theme.Text.color Theme.Label.color 文字主要颜色
Theme.Text.labelColor Theme.Label.color 文字标签主要颜色
Theme.Text.disabledColor Theme.Label.textColor 文本禁用颜色
Theme.Cell.smallHeight 61 常见的 UITableViewCell 高度。
Theme.Cell.height 80 常见的 UITableViewCell 高度。
Theme.Cell.largeHeight 88 列表传输方法项和选择传输方法类型项的 UITableViewCell 高度。
Theme.Cell.headerHeight 37 选择传输方法类型项的头部高度。
Theme.Cell.dividerHeight 8 分隔符的 UITableViewCell 高度。
Theme.Cell.separatorColor UIColor(rgb: 0x3c3c43, alpha: 0.29) UITableViewCell 的分隔符颜色。
Theme.Cell.tintColor UIColor.white UITableViewCell 的调色色。
Theme.Icon.size 30 图标字体大小
Theme.Icon.frame CGSize(width: 30, height: 30) 图标框架
Theme.Icon.primaryColor Theme.themeColor 图标主色
Theme.Icon.creditColor Amount.creditColor 图标贷记颜色
Theme.Icon.debitColor Amount.debitColor 图标借记颜色
Theme.Amount.creditColor UIColor(rgb: 0x299976) 贷记颜色
Theme.Amount.debitColor Theme.Label.color 借记颜色
Theme.ViewController.backgroundColor UIColor.white UIViewController 的背景颜色。
Theme.SpinnerView.activityIndicatorViewStyle UIActivityIndicatorView.Style.whiteLarge UIActivityIndicatorView 的样式。
Theme.SpinnerView.activityIndicatorViewColor Theme.themeColor UIActivityIndicatorView 的颜色。
Theme.SpinnerView.backgroundColor UIColor.clear 背景颜色
Theme.ProcessingView.backgroundColor UIColor.black.withAlphaComponent(0.85) 背景颜色。
Theme.ProcessingView.stateLabelColor UIColor.white 状态标签颜色。

示例：在 AppDelegate 类中定义亮色主题代码

@UIApplicationMain
class AppDelegate: UIResponder, UIApplicationDelegate {
    var window: UIWindow?

    func application(_ application: UIApplication,
                     didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {

        // Override point for customization after application launch.

        ThemeManager.applyWhiteTheme()
        // Set the default tint color
        window?.tintColor = .systemBlue
        // Avoid to display a black area during the view transaction in the UINavigationBar.
        window?.backgroundColor = Theme.UITableViewController.backgroundColor

        return true
    }
}

示例：自定义标签颜色

...
/// Labels
Theme.Label.color = UIColor(red: 252 / 255, green: 67 / 255, blue: 77 / 255, alpha: 1)
Theme.Label.subTitleColor = UIColor(red: 19 / 255, green: 165 / 255, blue: 185 / 255, alpha: 1)
Theme.Label.textColor = UIColor(red: 0 / 255, green: 45 / 255, blue: 67 / 255, alpha: 1)
Theme.Label.errorColor = .red

注意：如果您不使用 ThemeManager.applyToUINavigationBar()，那么对 Theme.NavigationBar.xxx 的任何更改都不会反映出来。

错误处理

在 Hyperwallet UI SDK 中，我们将 HyperwalletException 分为三大类，分别是输入错误（业务错误）、网络错误和意外错误。

意外错误

一旦发生意外错误，界面中会显示只包含 OK 按钮的 AlertView。

网络错误

网络错误通常是由于连接问题，例如网络连接质量差、从服务器端的请求超时等原因造成的。一旦发生网络错误，UI界面中会显示一个包含“取消”和“重试”按钮的AlertView。

业务错误

当Hyperwallet平台发现无效信息或与数据相关的某些业务限制已被提交并需要用户采取一些行动时，会发生业务错误。

认证错误

认证错误发生在Hyperwallet SDK无法从客户端实现中获取认证令牌时。

许可

Hyperwallet iOS SDK是开源的，可在MIT许可下使用