iOS Ready UX SDK

Introduction

Here you can find instructions on how to integrate and use Planky Connect for iOS.

To get started quickly with Planky Connect for iOS, clone the GitHub repository and run the example. You will need to sign-up for the free API keys through our Developer Console.

Requirements

Xcode 10 or greater
iOS 12.0 or greater
Planky Client Id

Quickstart Demo App

Clone and run the demo project from our GitHub repository.

Installation

Planky Connect is a framework distributed using CocoaPods dependency manager. If you are not familiar with this concept, please follow detailed instructions here.

To integrate, add FriendlyScoreConnect to your Podfile

pod 'FriendlyScoreConnect', '~> 1.0.10'

Then run following command in your project main directory:

pod install

CocoaPods will install and embed all sources and dependencies into your app.

App Delegate

Start with importing FriendlyScoreCore and FriendlyScoreConnect framework in your App Delegate:

1
2

import FriendlyScoreCore
import FriendlyScoreConnect

Then configure Connect in application:didFinishLaunchingWithOptions:

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    // Override point for customisation after application launch.
    FriendlyScore.configureConnect()
    return true
}

In order to handle redirection properly, add line below to application(_:open:options:) function:

func application(_ app: UIApplication, open url: URL, options: [UIApplicationOpenURLOptionsKey: Any] = [:]) -> Bool {
  FriendlyScore.handleQueryParameters(for: url)
  return true
}

Adding URL Types

Go to the Redirects section of the Planky developer console and provide your Bundle Identifier.

You will also need your Client Id for the specific environment (SANDBOX, PRODUCTION).

Navigate to your app target, create new URL Types object and add your bundle identifier to Identifier and URL Schemes field, as below:

UI

Start by importing FriendlyScoreCore:

import FriendlyScoreCore

You can select which environment you want to use the Planky SDK and select the Client Id for that environment

Environment	Description
sandbox	Use this environment to test your integration
production	Use this environment when deploying the live application

Create the ClientId object

let myClientId = ClientId(stringLiteral: "YOUR_CLIENT_ID")

Create the Credentials object using userReference, which is any alphanumeric string that identifies the customer in your systems.

let myCredentials = Credentials(clientId: myClientId, userReference: "YOUR_USER_REFERENCE", environment: .sandbox)

Now, using the myCredentials object, you can present the Planky SDK anywhere in your code. Usually this can be done after the user's demand, e.g. tapping a button:

//somewhere in view controller
let button = UIButton(frame: CGRect(x: 0, y: 0, width: 130, height: 45))
button.setTitle("Launch FriendyScore!", for: .normal)
button.addTarget(self, action: #selector(buttonTapHandler), for: .touchUpInside)
 
self.view.addSubview(button)

Customization

Theme

PlankyConnect can be presented with a light (default) or dark theme, which are predefined list of colors and icons.

To use custom colors for the categories, you must override the color keys in your application. Custom theme examples is included in the custom_theme.json. The color keys and descriptions are in the Colors section.

/*
    Optional - Built-in themes = .light, .dark, .custom(themePath: String). Default theme is .light
*/
let connectTheme: ConnectTheme = .light

Other

/*
    Optional - Set a flag whether to display only the back button on the screen with the list of banks. Default is true
*/
let showOnlyBackButtonIcon: Bool = true
 
 
/*
    Optional - The label to show on the back button on the view with the list of banks to direct users back to your app. Default label is "Back". Ad
*/
let backButtonLabel: String = "Back"

Initiate Planky View with the options above

1
2
3

@objc func buttonTapHandler(button:UIButton) {
    FriendlyScore.show(with: credentials, theme: .light, showOnlyBackButtonIcon: showOnlyBackButtonIcon, backButtonLabel: backButtonLabel)
}

Colors

Colors across views

Color Key	Description
connectBackgroundColor	Background color for all views in the SDK
connectDividerColor	Divider color for all view in the SDK
connectCancelButtonColor	Background color for Cancel, Disconnect Buttons
connectNextButtonColor	Background color for Next, Confirm Button
connectButtonTextColor	Text color for Buttons
connectBankDetailMarkerColor	Color for the marker on the detail view for a connected bank
connectNavigationButtonBackgroundColor	Background color for navigation button in the toolbar
connectNavigationBackButtonItems	Color of the back button for the navigation button
connectToolbarIconsColor	Color for the search icon in the toolbar
connectToolbarTextColor	Color for the search field cursor
connectToolbarSearchTextColor	Color for the search text query
connectToolbarSearchCursorColor	Color for the search field cursor

Colors for View: List of Banks

Color Key	Description
connectBankItemBackgroundColor	Background color for bank item in the list of banks
connectBankItemTextColor	Text color for bank item in the list of banks
connectBankItemDisabledTextColor	Text color for bank item if its disabled or not available in the list of banks
connectBankItemBorderColor	Border color for the bank item in the list of banks
connectedBankItemConnectedStatusColor	Color of the connected status icon for the bank item in the list of banks
connectBankItemUnavailableStatusColor	Color of the unavailable status icon for the bank item in the list of banks

Colors for View: Filter

Color Key	Description
connectFilterHeaderDisabledColor	Color for the filter header background color
connectFilterPageTitleColor	Color for the filter header text color
connectFilterPageSubTitleColor	Color for the filter item text color

Events

If you need to know when the user returns from the Planky Flow you must handle events

FriendlyScore.eventsHandler = { event in
    switch event {
    case .userClosedView:
      print("SDK view closed by user.")
    case .userCompletedFlow:
      print("Planky user completed flow.")
    }
}

Events Definition

State	Definitions
userClosedView	Present if the customer Closed the Planky Flow.
userCompletedFlow	Present if the customer Completed the Planky flow.

Errors

If you need to know when the user returns from the Planky Flow you must handle errors

FriendlyScore.errorHandler = { error in
    switch error {
    case .userReferenceAuth:
      print("There was an authentication error for the supplied `userReference`")
    case .server: //unabled to get config
      print("There was a critical error on the server. SDK view closed automatically")
    case .serviceDenied: //wrong client id, access endpoint unpaid
      print("The service you are trying to connect is denied. Reason: \(error.description). SDK view closed automatically")
    }
}

Error Definition

Error	Definitions
userReferenceAuthError	Present if there was an authentication error for the supplied userReference.
serviceDenied	Present if service was denied. Please check the description for more information.
incompleteConfiguration	Present if the configuration on the server is incomplete. Please check the description for more information.
serverError	Present if there was a critical error on the server.

Was this article helpful?

Friendly Score UK Ltd.

42 Brook Street, Mayfair

London W1K 5DB

Call us on +44 20 3709 6726

Company registered in England

Company number 09168668, ICO ZA111687

VAT registration number 206 9758 80

Authorised and Regulated by the Financial Conduct Authority. (FRN: 821100, 781963)