iOS

How to integrate

Lean's iOS SDK is available through Swift Package Manager. To integrate Lean’s Link SDK in XCode go to File > Swift Packages > Add Package Dependency and use the URL below:

https://www.github.com/leantechnologies/link-sdk-ios-distribution

Manual installation can also be achieved by adding the .xcframework available here to your project in Xcode.

You can then import the SDK into your swift files.

import LeanSDK

Usage with Swift UI

1. Initalizing

You will need to initalize the LeanSDK within your Swift UI application by calling Lean.manager.setup(appToken, sandbox), version this sets the application token and environment during runtime of your application.

// YourApp.Swift

import SwiftUI
import LeanSDK

@main
class LeanTestAppApp: App {

    required init() {
        Lean.manager.setup(
            appToken: String,
            sandbox: true,
            version: "latest"
        )
    }

    var body: some Scene {
        WindowGroup {
            ContentView()
        }
    }
}

2. Create the View state

You can present a Lean.manager.view anywhere in your application, however for best performance we recommend that it be placed inside a .fullScreenCover and set ignoresSafeArea() so that the view displays in full screen.

// ContentView.swift

import SwiftUI
import LeanSDK

struct ContentView: View {
    @State private var isPresented = false
    var linkPermissions = ArrayOf<LeanPermission>

    var body: some View {
        VStack {
            Button("Link", action: { handleLink() })
        }
    }
    .fullScreenCover(isPresented: $isPresented, content: {
        Lean.manager.view.ignoresSafeArea()
    })

    func handleLink() {
        Lean.manager
                .connect(customerId: String, permissions: linkPermissions, failRedirectUrl: String, successRedirectUrl: String, customization: LeanCustomization?, success: {
                    print("Entity Linked")
                    isPresented = false
                }, error: { (status) in
                    print(status.status)
                    print(status.message)
                    print(status.method)
                    isPresented = false
                })
        isPresented = true
    }
}

3. Call a method

You can now write and attach functions to any UI element using Lean.manager.[method] see Methods section below

4. Handle success and error closures

You can write your own completion blocks upon success and failure of the LinkSDK.

Errors will pass back a LeanStatus dictionary with the following:

{
    status: "ERROR",
    method: "LINK",
    message: "Some message"
}

Usage with View Controllers

1. Initalizing

Call Lean.manager.setup(appToken, sandbox, version) during ViewDidLoad - or before attempting to make a call to the SDK.

// ViewController.swift

import UIKit
import LeanSDK

class ViewController: UIViewController {

    override func ViewDidLoad() {
        super.viewDidLoad()
        Lean.manager.setup(appToken: String, sandbox: true, version: "latest")
    }
}

2. Call a method

You can now write and attach functions to any UI element using Lean.manager.[method] see Methods section below.

Ensure that you set the presentingViewController, to the View Controller that you want the SDK to present within.

// ViewController.swift

import UIKit
import LeanSDK

class ViewController: UIViewController {
    var connectPermissions = ArrayOf<LeanPermission>

    override func ViewDidLoad() {
        super.viewDidLoad()
        Lean.manager.setup(appToken: String, sandbox: true, version: "latest")
    }
}
    @IBAction func handleLink(_sender: Any) {
        Lean.manager.connect(
            presentingViewController: self,
            customerId: String,
            permissions: connectPermissions,
            bankId: nil,
          	failRedirectUrl: String,
          	successRedirectUrl: String,
            customization: LeanCustomization?,
            success: { status in
                print("Entity Linked")
            }, error: { (status) in
                print(status)
            }
        )
    }

3. Handle success and error closures

You can write your own completion blocks upon success and failure of the LinkSDK.

Errors will pass back a LeanStatus dictionary with the following:

{
    status: "ERROR",
    method: "LINK",
    message: "Some message"
}

Choosing a version

When calling Lean.manager.setup a version is required.

Version takes a String and can point to either a specific SDK version i.e. "latest" or an alias i.e. "latest".

Lean.manager.setup(
    appToken: String,
    sandbox: true,
    version: "latest"
    )

📘

We recommend passing in a specific version to ensure stability in the case that a change to the SDK breaks your application.

Available Versions

Specific Version semver

The current stable build is 1.25.0

latest alias

latest is an alias for the current release. It is subject to change at relatively short notice - but does allow for any bug fixes to be shipped over the air - meaning fixes can be applied without the need to resubmit your application to the app store.

next-release alias

next-release is a QA version of the SDK allowing you to test the next version that will become latest before we roll out the changes, this should only be used for development and QA purposes as it is subject to breakage without any warning.

Available Methods

.connect()

The connect method is used to enable a customer to use a single log in to create and Entity for use with the Data API.

Lean.manager.connect(
    customerId: String,
    permissions: ArrayOf<LeanPermission>,
  	failRedirectUrl: String,
  	successRedirectUrl: String,
    bankId: String?
    customization: LeanCustomization?,
    success: () -> (),
    error: (status) -> ()
)

Callback functions

The iOS SDK has a callback function which allows you to receive events on SDK close, completion or error.

Response

The responseObject returned to your callback function is in the following format:

{
  "status": "SUCCESS",
  "message": "User successfully connected their account",
  "last_api_response": "SUCCESS",
  "exit_point": "SUCCESS",
  "secondary_status": "SUCCESS",
  "bank": {
    "bank_identifier": "LEA1_RETAIL_SAU",
    "is_supported": true
  }
}

status enum
The end status of the LinkSDK at close.

message string

Further details on the end state. May be null.

last_api_response string

Details on the last response status from the Lean API. May be null.

exit_point enum

The last screen displayed before the user exited the SDK.

secondary_status enum

Further details on failures. May be null.

bank object

Details on the bank selected by the user.

Unsupported banks

Your users can indicate that their bank is not supported. When this happens, the callback from the LinkSDK will contain a false flag in the bank object.

{
  "status": "CANCELLED",
  "message": "User cancelled the operation",
  "exit_point": "UNSUPPORTED_BANK_REQUEST_SUCCESS",
  "last_api_response": "CANCELLED",
  "secondary_status": "CANCELLED",
  "bank": {
    "bank_identifier": "LEA1_MOCK_RETAIL_SAU",
    "is_supported": false
  }
}

Skip Bank List

In some use cases you may want to provide your own UI for the bank selection screen in the LinkSDK. This can be achieved by passing in a bank_identifier during the `.connect() flows.

You can get a list of available bank_identifiers for your application by making a call to the /banks/ endpoint.

Call:

curl -X GET 'https://api.sa.leantech.me/banks/v1/' \
  --header 'lean-app-token: 2c9a80897169b1dd01716a0339e30003' \
  --ca-cert ca.pem \
  --cert cert.crt \
  --key key.pem

Response:

[
	{
		"identifier": "LEA1_RETAIL_SAU",
		"name": "Lean Open Banking MockBank",
		"logo": "https://cdn.leantech.me/img/banks/white-lean.png",
		"logo_alt": "https://cdn.leantech.me/img/banks/white-lean.svg",
		"main_color": "#1beb75",
		"background_color": "#ffffff",
		"theme": "light",
		"country_code": "SAU",
		"active": true,
		"mock": true,
		"bank_type": "RETAIL",
		"traits": [
			"auth-redirect"
		],
		"supported_account_types": [
			"CREDIT",
			"SAVINGS",
			"CURRENT"
		]
	}
]

You can then use the bank identifier bankId directly with the LinkSDK to skip the bank selection screen:

Lean.manager.connect(
    customerId: String,
    permissions: ArrayOf<LeanPermission>,
  	failRedirectUrl: String,
  	successRedirectUrl: String,
    bankId: String,
    customization: LeanCustomization?,
    success: () -> (),
    error: (status) -> ()
)

Changing the SDK language

Link SDK is available in English and Arabic, fully supported with a right-to-left UI, including text alignment, icons and images. If no language is provided the default is English. The language parameter is provided to the Lean.manager.setup

...
Lean.manager.setup(
    language: String,
    ...
)

Language option

language enum

Customizing Link SDK

We are progressively releasing customization capabilities to the Link SDK to match its UI with your application branding style. This allows customers to programmatically theme the Link SDK directly from any of the methods.

For more detailed documentation on how best to use the customization feature see our guides.

Customisation Guide

Presentation options

dialog_mode string

Presents the Link SDK with or without a containing modal.

"contained" for modal (default), or "uncontained" for no modal.

button_border_radius string

Change the shape of the main button on each step. See guidance for examples.

A unitless number as a String. Options:

Color options

theme_color string

Buttons background color, active input borders, and loading spinners.

button_text_color string

Elements inside any primary button such as the text, icons and the loading spinner. It is useful to boost readability of the button color.

link_color string

CTAs and helpers.

overlay_color string

Overlay containing the Link SDK dialog box.

The following color formats are supported:

Example

var customConfig = LeanCustomization(
    dialogMode: String?, 
    themeColor: String?, 
    buttonTextColor: String?,
    buttonBorderRadius: String?,
    linkColor: String?, 
    overlayColor: String?
)

Lean.manager.connect(
    customerId: String,
    permissions: ArrayOf<LeanPermission>,
  	failRedirectUrl: String,
  	successRedirectUrl: String,
    bankId: String?
    customization: customConfig,
    success: () -> (),
    error: (status) -> ()
)