Finerio Connect iOS Widget
介绍
Finerio Connect 2.0 API 的 iOS 小部件通过简化实现并提升用户体验,减少了用户询问其在线银行凭证过程中的摩擦。
安装
所需条件
- iOS 11.0+
- Swift 5.0
先决条件
- 您必须拥有一个有效的
FinerioConnect
账户。
使用 Cocoapods
编辑你的 Podfile
并指定依赖项
pod 'FinerioAccountWidget'
然后运行 pod install --repo-update
。更多关于 Cocoapods
的信息 在这里。
用法
在你的应用程序中添加以下代码
import FinerioAccountWidget
要使用提供完整嵌入式账户聚合过程的解决方案,请使用以下初始化表单。确保为 presentingViewController
参数提供一个具有 NavigationController
的 ViewController
。
let finerioConnectWidget = FinerioConnectWidget.shared
finerioConnectWidget.start(
widgetId: "pparKeszQYwBF64A8WsWab5VDnVdE8QDnVCp2pgVubJRxyNU46",
customerName: "René Sandoval",
presentingViewController: self)
要使用通过单独视图实现的自定义导航,请使用以下初始化方法
let finerioConnectWidget = FinerioConnectWidget.shared
finerioConnectWidget.start(
widgetId: "pparKeszQYwBF64A8WsWab5VDnVdE8QDnVCp2pgVubJRxyNU46",
customerName: "René Sandoval")
FinerioConnectWidget 属性
let finerioConnectWidget = FinerioConnectWidget.shared
// (Required) Enum to pre-select an environment to work with. Values: [.production, .sandbox]
finerioConnectWidget.environment = .production
// (Optional) Flag to enable or disable the Zendesk help integration chat. DefaultValue: true
finerioConnectWidget.showChat = true
// (Optional) Flag to enable or disable the presentation of an Onboarding flow. DefaultValue: true
finerioConnectWidget.showOnboarding = false
// (Optional) Property to set a custom instance of Onboarding class to display in the Onboarding flow. DefaultValue: nil
finerioConnectWidget.onboarding = Onboarding()
// (Optional) The font name of a given custom font to use in the workflow. DefaultValue: ""
finerioConnectWidget.font = "Ubuntu"
// (Optional) The country code to use in order to fetch banks of that country by default. DefaultValue: ""
finerioConnectWidget.countryCode = "MX"
// (Optional) Flag to enable or disable the Countries dropdown menu from the UI. DefaultValue: true.
finerioConnectWidget.showCountryOptions = false
// (Optional) Flag to enable or disable the BankType selector from the UI. DefaultValue: true.
finerioConnectWidget.showBankTypeOptions = true
// (Optional) Enum to pre-select the BankType from the UI. Values: [.personal, .business, .fiscal] DefaultValue: .personal
finerioConnectWidget.bankType = .personal
// (Optional) Enum to pre-select a theme for the UI. Values: [.automatic, .light, .dark] DefaultValue: .light
finerioConnectWidget.theme = .automatic
// (Optional) Property to set a custom instance of Texts class to display within the worflow. DefaultValue: nil
finerioConnectWidget.texts = Texts(companyName: "Super Bank Company")
// (Optional) Property to set a custom instance of Animations class to display in wait or loading scenarios. DefaultValue: nil
finerioConnectWidget.animations = Animations()
// (Optional) Property to set a custom instance of Palette class to display your custom colors in the components. DefaultValue: nil
finerioConnectWidget.palette = Palette()
按视图分离
FCBankSelectionView
此视图显示所选银行类型的银行列表以及国家,无论是通过精选的界面控件还是通过在 FinerioConnectWidget
初始化中配置的内部参数设置内部参数。
let bankSelectionView = FCBankSelectionView()
bankSelectionView.delegate = self
view.addSubview(bankSelectionView)
bankSelectionView.translatesAutoresizingMaskIntoConstraints = false
NSLayoutConstraint.activate([
bankSelectionView.topAnchor.constraint(equalTo: view.topAnchor),
bankSelectionView.leadingAnchor.constraint(equalTo: view.leadingAnchor),
bankSelectionView.trailingAnchor.constraint(equalTo: view.trailingAnchor),
bankSelectionView.bottomAnchor.constraint(equalTo: view.bottomAnchor)
])
委托方法
FCBankSelectionViewDelegate
didSelectBank
方法在用户从可用列表中选择银行时调用。在参数中,nextFlowView
参数返回一个配置实例,包含建议流程中将展示的下个视图所需的数据。
func bankSelectionView(didSelect bank: Bank, nextFlowView: FCCredentialsFormView) {
let vc = UIViewController()
vc.view.addSubview(nextFlowView)
nextFlowView.translatesAutoresizingMaskIntoConstraints = false
NSLayoutConstraint.activate([
nextFlowView.topAnchor.constraint(equalTo: vc.view.topAnchor),
nextFlowView.leadingAnchor.constraint(equalTo: vc.view.leadingAnchor),
nextFlowView.trailingAnchor.constraint(equalTo: vc.view.trailingAnchor),
nextFlowView.bottomAnchor.constraint(equalTo: vc.view.bottomAnchor),
])
self.present(vc, animated: true)
}
onFailure
方法在从服务器中选择银行发生错误时调用。
func bankSelectionView(onFailure: ServiceStatus, message: String) {
// Your implementation
}
FCCredentialsFormView
此屏幕显示一个表单,包含根据传递给配置参数的银行所需字段。
let credentialsFormView = FCCredentialsFormView()
credentialsFormView.delegate = self
view.addSubview(credentialsFormView)
credentialsFormView.translatesAutoresizingMaskIntoConstraints = false
NSLayoutConstraint.activate([
credentialsFormView.topAnchor.constraint(equalTo: view.topAnchor),
credentialsFormView.leadingAnchor.constraint(equalTo: view.leadingAnchor),
credentialsFormView.trailingAnchor.constraint(equalTo: view.trailingAnchor),
credentialsFormView.bottomAnchor.constraint(equalTo: view.bottomAnchor)
])
方法
setBank
方法允许您从特定的银行注入数据,以使用该银行所需字段自定义表单。
let bank = Bank(id: "1", name: "BBVA Bancomer", code: "BBVA", status: "Active")
credentialsFormView.setBank(bank)
委托方法
FCCredentialsFormViewDelegate
当检测到所选银行的凭证已经被先前注册并且处于活动状态时,会触发 onActive
代理,因此不需要再次注册它们。
在参数中,nextFlowView
参数返回一个配置的实例,其中包含将在建议流程中展示的下一个视图所需的数据。
func credentialsFormView(onActive: ServiceStatus, bank: Bank, nextFlowView: FCAccountStatusView) {
// Your implementation
let vc = UIViewController()
vc.view.addSubview(nextFlowView)
nextFlowView.translatesAutoresizingMaskIntoConstraints = false
NSLayoutConstraint.activate([
nextFlowView.topAnchor.constraint(equalTo: vc.view.topAnchor),
nextFlowView.leadingAnchor.constraint(equalTo: vc.view.leadingAnchor),
nextFlowView.trailingAnchor.constraint(equalTo: vc.view.trailingAnchor),
nextFlowView.bottomAnchor.constraint(equalTo: vc.view.bottomAnchor),
])
self.present(vc, animated: true)
}
只要指示的银行凭证已成功创建并且其远程流程已完成,就会立即触发 onSuccess
代理。
在参数中,nextFlowView
参数返回一个配置的实例,其中包含将在建议流程中展示的下一个视图所需的数据。
func credentialsFormView(onSuccess: ServiceStatus, bank: Bank, credentialId: String, nextFlowView: FCAccountCreationView) {
// Your implementation
let vc = UIViewController()
vc.view.addSubview(nextFlowView)
nextFlowView.translatesAutoresizingMaskIntoConstraints = false
NSLayoutConstraint.activate([
nextFlowView.topAnchor.constraint(equalTo: vc.view.topAnchor),
nextFlowView.leadingAnchor.constraint(equalTo: vc.view.leadingAnchor),
nextFlowView.trailingAnchor.constraint(equalTo: vc.view.trailingAnchor),
nextFlowView.bottomAnchor.constraint(equalTo: vc.view.bottomAnchor),
])
self.present(vc, animated: true)
}
当根据所选银行获得表单字段时,在服务器端发生错误,会触发 onFailure
代理。
func credentialsFormView(onFailure: ServiceStatus, bank: Bank) {
// Your implementation
}
在选择银行的凭证创建过程中发生错误时,会触发 onError
代理。
func credentialsFormView(onError: ServiceStatus, message: String) {
// Your implementation
}
FCAccountCreationView
呈现一个等待活动屏幕,该屏幕更新其界面以显示在过程中创建的账户名称。
let accountCreationView = FCAccountCreationView()
accountCreationView.delegate = self
view.addSubview(accountCreationView)
accountCreationView.translatesAutoresizingMaskIntoConstraints = false
NSLayoutConstraint.activate([
accountCreationView.topAnchor.constraint(equalTo: view.topAnchor),
accountCreationView.leadingAnchor.constraint(equalTo: view.leadingAnchor),
accountCreationView.trailingAnchor.constraint(equalTo: view.trailingAnchor),
accountCreationView.bottomAnchor.constraint(equalTo: view.bottomAnchor)
])
Methods
setBank
方法允许通过接口注入必要的显示账户创建过程的数据。
let bank = Bank(id: "1", name: "BBVA Bancomer", code: "BBVA", status: "Active")
accountCreationView.setBank(bank, credentialId: "d009c665-7681-49b7-a234-fb8c0036a6e4")
代理方法
FCAccountCreationViewDelegate
一旦账户创建成功完成,就会立即触发 onSuccess
方法。
在参数中,在 nextFlowView
参数中返回一个配置的实例,其中包含将在建议流程中展示的下一个视图所需的数据。
func accountCreationView(onSuccess: ServiceStatus, bank: Bank, nextFlowView: FCAccountStatusView) {
// Your implementation
let vc = UIViewController()
vc.view.addSubview(nextFlowView)
nextFlowView.translatesAutoresizingMaskIntoConstraints = false
NSLayoutConstraint.activate([
nextFlowView.topAnchor.constraint(equalTo: vc.view.topAnchor),
nextFlowView.leadingAnchor.constraint(equalTo: vc.view.leadingAnchor),
nextFlowView.trailingAnchor.constraint(equalTo: vc.view.trailingAnchor),
nextFlowView.bottomAnchor.constraint(equalTo: vc.view.bottomAnchor),
])
self.present(vc, animated: true)
}
在账户创建过程中出现问题时会执行 onFailure
方法,返回相关的错误消息。
在参数中,nextFlowView
参数返回一个配置的实例,其中包含将在建议流程中展示的下一个视图所需的数据。在这种情况下,将显示一个预定义的错误屏幕。
func accountCreationView(onFailure: ServiceStatus, message: String, bank: Bank, nextFlowView: FCAccountStatusView) {
// Your implementation
let vc = UIViewController()
vc.view.addSubview(nextFlowView)
nextFlowView.translatesAutoresizingMaskIntoConstraints = false
NSLayoutConstraint.activate([
nextFlowView.topAnchor.constraint(equalTo: vc.view.topAnchor),
nextFlowView.leadingAnchor.constraint(equalTo: vc.view.leadingAnchor),
nextFlowView.trailingAnchor.constraint(equalTo: vc.view.trailingAnchor),
nextFlowView.bottomAnchor.constraint(equalTo: vc.view.bottomAnchor),
])
self.present(vc, animated: true)
}
accountCreated
方法是可选的,并且每当账户创建完成时执行。
func accountCreationView(accountCreated: CredentialAccount) {
// Your implementation
}
FCAccountStatusView
该类根据账户创建过程中的结果展示成功或失败界面。
let accountStatusView = FCAccountStatusView()
view.addSubview(accountStatusView)
accountStatusView.translatesAutoresizingMaskIntoConstraints = false
NSLayoutConstraint.activate([
accountStatusView.topAnchor.constraint(equalTo: view.topAnchor),
accountStatusView.leadingAnchor.constraint(equalTo: view.leadingAnchor),
accountStatusView.trailingAnchor.constraint(equalTo: view.trailingAnchor),
accountStatusView.bottomAnchor.constraint(equalTo: view.bottomAnchor)
])
方法
setBank
方法允许你注入所需用于自定义账户状态界面的银行数据。
let bank = Bank(id: "1", name: "BBVA Bancomer", code: "BBVA", status: "Active")
accountStatusView.setBank(bank)
setStatus
方法允许指示账户创建过程中是否成功或失败,以便相应地显示完成或错误界面。
accountStatusView.setStatus(.success)
accountStatusView.setStatus(.failure)
代理方法
didSelectContinueButton
代理方法允许你在继续事件的情况下实现小部件终止流程,例如,如果你希望允许用户添加新的凭证。
func accountStatusView(didSelectContinueButton: UIButton) {
// Your implementation
}
didSelectExitButton
代理方法允许你在终止事件的情况下实现小部件的终止流程,例如,如果你希望你的用户不登录账户聚合流程并继续在你自己的应用中浏览。
func accountStatusView(didSelectExitButton: UIButton) {
// Your implementation
}
高级集成
日志记录和调试
在某些情况下,查看 FinerioConnectWidget
内部发生的情况可能会很有用。如果是这样,你可以启用日志记录以进行调试目的。
finerioConnectWidget.logLevel = .info
UI/UX 自定义
默认颜色
我们的品牌调色板在工具过程中作为默认调色板使用。
// LIGHT THEME
private static let cetaceanBlue = UIColor(hex: "#00113D")!
private static let americanBlue = UIColor(hex: "#333F65")!
private static let eucalyptus = UIColor(hex: "#3FD8AF")!
private static let antiFlashWhite = UIColor(hex: "#F1F2F5")!
private static let manatee = UIColor(hex: "#989DB3")!
private static let lightPeriwinkle = UIColor(hex: "#CACDD9")!
private static let brightGray = UIColor(hex: "#EEEEF0")!
private static let darkBlueGray = UIColor(hex: "#656E8D")!
private static let lightSalmonPink = UIColor(hex: "#F89A9A")!
// DARK THEME
private static let white = UIColor(hex: "#FFFFFF")!
private static let caribeanGreen = UIColor(hex: "#07CEA4")!
private static let arsenic = UIColor(hex: "#373946")!
private static let darkGunMetal = UIColor(hex: "#24252D")!
private static let eerieBlack = UIColor(hex: "#1B1A21")!
根据视图中的所有个性化需求,颜色按常见组件和少量属性分组。
亮暗模式主题
我们为iOS 暗模式
功能准备了默认主题。此外,您还可以使用自己的品牌颜色自定义一些组件的属性以用于亮暗模式。
FinerioConnectWidget.shared.palette = Palette(
// Tint color for the icon rounded by a circle.
circleIconTint: FCColor(light: .red, dark: .blue),
// Background color for the circle that contains an icon.
circleIconBackground: FCColor(light: .red, dark: .blue),
// Background color for the buttons that performs a next or continue flow action.
buttonActiveBackground: FCColor(light: .red, dark: .blue),
// Tint color for the title of buttons that performs a next or continue flow action.
buttonActiveText: FCColor(light: .red, dark: .blue),
// Background color for the buttons that performs an exit or stops the flow action.
buttonPassiveBackground: FCColor(light: .red, dark: .blue),
// Tint color for the title of buttons that performs an exit or stops the flow action.
buttonPassiveText: FCColor(light: .red, dark: .blue),
// Background color used in all the views
backgroundView: FCColor(light: .red, dark: .blue),
// Tint color commonly used for the paragraph texts or normal texts.
regularSizedText: FCColor(light: .red, dark: .blue),
// Tint color used in phrases or titles to distinguish from others descriptions.
mediumSizedText: FCColor(light: .red, dark: .blue),
// Tint color used in linked texts that redirects to a web site or a view within the flow.
linkedText: FCColor(light: .red, dark: .blue),
// Background color used in the text fields.
fieldsBackground: FCColor(light: .red, dark: .blue),
// Border tint color used in the text fields.
fieldsBorder: FCColor(light: .red, dark: .blue),
// Tint color used in the right icons of the text fields.
fieldsRightIcon: FCColor(light: .red, dark: .blue),
// Background color for segmented controls
segmentedControlBackground: FCColor(light: .red, dark: .blue),
// Background color for the active part of segmented controls
segmentedControlActiveItem: FCColor(light: .red, dark: .blue),
// Tint color for the text in the dropdown menu
dropDownMenuTint: FCColor(light: .red, dark: .blue),
// Tint color for the on status of the toggle switch
toggleSwitchOn: FCColor(light: .red, dark: .blue),
// Border color of the banner component
bannerBorder: FCColor(light: .red, dark: .blue),
// Tint color for the success icon shown after a correct synchronization process
successIconTint: FCColor(light: .red, dark: .blue),
// Tint color for the failure icon shown after a failed synchronization process
failureIconTint: FCColor(light: .red, dark: .blue),
// Background color for the status bar
statusBarBackground: FCColor(light: .red, dark: .blue),
// Tint color for the phrases or paragraphs with a thin text
liteText: FCColor(light: .red, dark: .blue),
// Tint color used in the cell separators of tables
cellSeparator: FCColor(light: .red, dark: .blue),
// Tint color used in the icons of disclosure indicators within the cells of tables
cellDisclosureIndicator: FCColor(light: .red, dark: .blue),
// Tint color used in the placeholders of the text fields
fieldsPlaceholder: FCColor(light: .red, dark: .blue),
// Tint color used in the icon of the close button of the dialog alerts
dialogCloseButton: FCColor(light: .red, dark: .blue),
// Tint color used in the current dot of the page control of onboarding components
pageDotActive: FCColor(light: .red, dark: .blue),
// Tint color used in the unselected dots of the page control of onboarding components
pageDotInactive: FCColor(light: .red, dark: .blue)
)
对于每个属性,都需要通过FCColor
对象定义Light
主题的UIColor
,可选地定义Dark
主题的UIColor
。
SDK
内部将根据上下文规范处理是否呈现Dark Mode
或Light Mode
的颜色。
FCColor(light: .red)
FCColor(light: .red, dark: .blue)
FCColor(light: UIColor(hex: "#FFFFFF"), dark: UIColor(hex: "#000000"))
默认主题
您可以为整个帐户集成流程分配一个默认主题,提供了三种不同的变体:`.light
`、`.dark
` 和 `.automatic
`。如果未指定,它将默认取 `.light
` 的值。`.automatic
` 变体会考虑操作系统的设置来显示一个主题或另一个。
FinerioConnectWidget.shared.theme = .dark
标题、副标题和字体
您可以对SDK的字符串文本进行自定义,以适应您的应用。
FinerioConnectWidget.shared.texts = Texts(
// Your company name
companyName: "your_text",
// The title to be displayed on the BanksListView
banksHeaderTitle: "your_text",
// A subtitle to be displayed on the BanksListView
banksHeaderSubtitle: "your_text",
// The text that brings context in the select country section of BanksListView
selectCountryLabel: "your_text",
// The name to refer to a personal bank type
personalBankType: "your_text",
// The name to refer to a business bank type
businessBankType: "your_text",
// The name to refer to a fiscal bank type
fiscalBankType: "your_text",
// The message to present when there's no banks to show
titleWithoutBanks: "your_text",
// The title to be displayed on the CredentialsView
credentialsHeaderTitle: "your_text",
// A subtitle to be displayed on the CredentialsView
credentialsHeaderSubtitle: "your_text",
// The full plain text to show in a linked text
plainTyCText: "your_text",
// The part of text to show with underline in a linked text and that will perform an event.
linkedTyCText: "your_text",
// The title to show in the Help button on CredentialsView
helpWithCredentialsButton: "your_text",
// The disclaimer text to show on the CredentialsView
credentialsDisclaimerText: "your_text",
// The title to be displayed on the SyncAccountsView
syncHeaderTitle: "your_text",
// A subtitle to be displayed on the SyncAccountsView
syncHeaderSubtitle: "your_text",
// The text that describes the status of the SyncAccountsView
encryptingData: "your_text",
// The title to be displayed on the StatusAccountView in case of successfuly process i.e. Congratulations!
bondingHeaderTitleSuccess: "your_text",
// The title to be displayed on the StatusAccountView in case of failure process i.e Ops! something goes wrong.
bondingHeaderTitleFailure: "your_text",
// A subtitle to be displayed on the StatusAccountView in case of successfuly process i.e communication error
bondingHeaderSubtitleSuccess: "your_text",
// A subtitle to be displayed on the StatusAccountView in case of failure process i.e. account saved
bondingHeaderSubtitleFailure: "your_text",
// A description to be displayed on the StatusAccountView in case of successfuly process i.e added with success detail
bondingDescriptionSuccess: "your_text",
// A description to be displayed on the StatusAccountView in case of failure process i.e. error connection detail
bondingDescriptionFailure: "your_text",
// A title for the button to retry the workflow
failureContinueTitleButton: "your_text",
// A title for the button to stops the workflow or cancels the process.
failureExitTitleButton: "your_text",
// A title for the button to continue the workflow
successContinueTitleButton: "your_text",
// A title for the button to stops the workflow or cancels the process.
successExitTitleButton: "your_text",
// A title for the button to continue the workflow
onboardingMainContinueButton: "your_text",
// A title for the button to stops the workflow or cancels the process.
onboardingMainExitButton: "your_text",
// A title for the button to continue the workflow of pages
onboardingStepContinueButton: "your_text",
// A title for the button to continue the workflow of pages
onboardingStepNextButton: "your_text",
// A title for the button to stops the workflow or cancels the process.
onboardingStepExitButton: "your_text"
)
要自定义字体,导入您首选的字体文件,并以传统方式设置它们。最后,在属性中添加字体的名称。
FinerioConnectWidget.shared.font = "Ubuntu"
默认值
当初始化您的FinerioConnectWidget
实例时,您可以根据需要指定一些默认值来预加载FCBankSelectionView
。
FinerioConnectWidget.shared.countryCode = "MX"
FinerioConnectWidget.shared.showCountryOptions = false
FinerioConnectWidget.shared.showBankTypeOptions = true
FinerioConnectWidget.shared.bankType = .personal
动画
该SDK默认使用Lottie
提供动画。您只需更改为方便的文件或URL。
FinerioConnectWidget.shared.animations = Animations(
loadingAnimation: "https://assets3.lottiefiles.com/packages/lf20_d4dil7mw.json",
accountCreationAnimation: "accountAnimation")
注册流程
SDK提供了一个默认的注册流程,该流程可以在组件的聚合过程中启用或禁用。这些视图可以通过提供的样式Palette
进行自定义。此注册流程仅在组件的聚合过程中调用一次。
FinerioConnectWidget.shared.showOnboarding = true
定制页面
注册流程提供了一种类来注入您的自定义图像和数据,以在您的自定义注册过程中显示。要注入此数据,您需要启用showOnboarding
标志,并设置Onboarding
实例,如下所示
FinerioConnectWidget.shared.showOnboarding = true
FinerioConnectWidget.shared.onboarding = Onboarding(
main: Onboarding.Main(icon: UIImage(systemName: "gamecontroller")!,
title: "Main page title",
description: "Description for main page",
actionText: TextWithLink(fullPlainText: "Link to show pages")),
pages: [Onboarding.OnboardingPage(image: UIImage(systemName: "dpad.up.filled")!,
icon: UIImage(systemName: "dpad.up.filled")!,
title: "Bullet Title One",
detail: TextWithLink(fullPlainText: "Description for page one")),
Onboarding.OnboardingPage(image: UIImage(systemName: "dpad.right.filled")!,
icon: UIImage(systemName: "dpad.right.filled")!,
title: "Bullet Title Two",
detail: TextWithLink(fullPlainText: "Description for page two")),
Onboarding.OnboardingPage(image: UIImage(systemName: "dpad.down.filled")!,
icon: UIImage(systemName: "dpad.down.filled")!,
title: "Bullet Title Three",
detail: TextWithLink(fullPlainText: "Description for page three")),
Onboarding.OnboardingPage(image: UIImage(systemName: "dpad.left.filled")!,
icon: UIImage(systemName: "dpad.left.filled")!,
title: "Bullet Title Four",
detail: TextWithLink(fullPlainText: "Description for page four"))
])
重置注册流程
为了处理注册流程的重置,我们提供了一些属性,可以与某些逻辑一起使用,以执行自定义重置流程。
// To know if a user has saw the onboarding flow once.
finerioConnectWidget.hasShownOnboarding = true
// To show the onboarding tutorial
finerioConnectWidget.showOnboarding = true
举个例子,如果您有应用程序的某个控制版本或发布版本,您可以为每次更新或部署新版本配置逻辑来重置注册流程。
if currentVersion > oldVersion {
// this will reset the onboarding
finerioConnectWidget.hasShownOnboarding = false
// You can inject your new features in pages of the Onboarding
finerioConnectWidget.onboarding = Onboarding()
}