​
Overview

Version 1.0+ of the iOS SDK introduces breaking changes that require changes in your application code if you had previously integrated an early version. See the Migration Guide for further details.
SDK Updates
New versions of the SDK are released frequently, not only to add new features and address issues in the SDK, but also to continuously improve the conversion of merchant login flows. As a result, it is strongly recommended that you frequently update your SDK version across any platforms where you invoke the SDK.
The Knot Link SDK provides a seamless way for end users to link their merchant accounts to your iOS app, serving as the foundation for Knot’s merchant connectivity platform. It is a client-side integration, consisting of initializing & configuring the SDK and handling events.

​
Installation

The Knot SDK can be installed using CocoaPods or Swift Package Manager (SPM).

​
Using CocoaPods

1

Install CocoaPods

If you haven’t already, install the latest version of CocoaPods.
2

Create a Podfile

If you don’t have an existing Podfile, run the following command to create one:
pod init
3

Add to your Podfile

Add the below line to your Podfile in your iOS project directory:
pod 'KnotAPI'

​
Using Swift Package Manager (SPM)

To install the Knot SDK using Swift Package Manager, ensure you’re using Swift version 5.3 or later.
1

Go to File, Add Packages

In your Xcode project, go to File, Add Packages.
2

Enter Knot package URL

In the top right corner of the dialog box, you’ll see a search bar. Enter the Knot package URL: https://github.com/millionscard/knot-api-ios. From the results, choose the knot-api-ios package.
3

Decide on your Dependency Rule

It is recommended to opt for Up to Next Major Version. Choose the project you want to integrate with KnotAPI and click on Add Package.
4

Confirm package dependency

Confirm that the KnotAPI Swift package was added as a package dependency to your project successfully.

​
Initialization

Your backend will create a session by calling Create Session and provide it to your frontend. To start a Knot session, you must first configure the session with a KnotConfiguration class. The configuration allows you to set the environment, entry point, and other user experience configurations.
It’s expected that your integration with Knot will retrieve and pass a new session into the SDK on each initialization.

​
Configure the session

The KnotConfiguration and CustomerConfiguration classes are used to initialize the SDK with specific parameters.

​
KnotConfiguration

NameTypeDescription
sessionIdStringThe session created by calling /session/create in your backend.
clientIdStringYour organization’s client ID. Note that this varies between development and production environments.
environmentEnvironmentThe desired environment (development or production).
productProductOptional. Ignored in version 1.0.11+ and fully deprecated in the next major version. The Knot product the session will inherit the same as the type of session created (e.g. card_switcher, transaction_link).
entryPointString?Optional. The specific entry point from within your app where you are initializing the Knot SDK (e.g. onboarding).
useCategoriesBoolOptional. Whether to display merchant categories and therefore group merchants into categories for discoverability. Default: true.
useSearchBoolOptional. Whether to display the search bar, enabling users to search for merchants. Default: true.
merchantIds[Int]?Optional. A list of merchant ID(s) to display. It is recommended to provide 0 or 1 merchant ID depending on your desired user experience.

​
CustomerConfiguration

This class is entirely optional and infrequently used, typically only when you offer Knot for multiple, differently-named card programs in the same app. The Knot team will set pre-defined values for each parameter that you can then subsequently pass into the SDK. Passing a value that is not pre-defined will result in an onError callback. To take advantage of this functionality, please contact the Knot team who will be happy to assist you.
NameTypeDescription
cardNameStringOptional. The differentiated display name for the card product, used inside the Knot SDK (e.g. Debit Card, Credit Card). This value will override the default value Card.
customerNameStringOptional. The differentiated display name for the company, used both as a standalone and prepended to the cardName (e.g. Smart Bank, Payment Corp). This value will override your default customer name value. Only recommended if you issue cards under multiple brands.
logoIdStringOptional. The differentiated logo for the company. This value will override your default logo.
See the following real example for how the parameters are used together in text inside the Knot SDK: "Your [customerName] [cardName | Card] was added." 
let customerConfiguration = CustomerConfiguration(
    cardName: "Card Name",		    // Your cardName
    customerName: "Customer Name",  // Your customerName
    logoId: "LogoId"				// Your logoID
)

let config = KnotConfiguration(
    sessionId: "session_12345",     // Current session ID
    clientId: "client_67890",       // Your client ID
    environment: .production,       // 'development' | 'production'
    merchantIds: [52],              // Recommend 0 or 1 merchant IDs
    useCategories: true,            // Recommend true
    useSearch: true,                // Recommend true
    domainUrls: nil,                // Explicitly passing nil
    entryPoint: "onboarding",       // Defined by you
    customerConfiguration: customerConfiguration
)

​
Open the session

To begin the flow, use the open method with a KnotConfiguration instance and an optional KnotEventDelegate. 
Knot.open(configuration: myConfiguration, delegate: self)

let customerConfiguration = CustomerConfiguration(
    cardName: "Card Name",		   
    customerName: "Customer Name",
    logoId: "LogoId"	
)

let config = KnotConfiguration(
    sessionId: "session_12345",
    clientId: "client_67890",
    environment: .development,
    entryPoint: "onboarding",
    useCategories: true,
    useSearch: true,
    merchantIds: [52]
	customerConfiguration: customerConfiguration
)

Knot.open(configuration: config, delegate: self)
To ensure seamless integration and avoid any UI issues when embedding the view controller into your UI hierarchy, it’s crucial to properly position the view controller within the safe area of your application’s interface. This practice helps maintain the accessibility and visibility of the controller across different devices and screen sizes, especially considering the presence of notches, status bars, and navigation elements that might obscure the content.
class MyViewController : UIViewController {

  func configureKnot() {
    let controller = Knot.createKnotViewController(configuration: session, delegate: delegate)
    view.addSubview(controller.view)
    addChild(controller)
  }

  ...
}
To test logging in to a merchant in the SDK, please reference a set of available test credentials for the CardSwitcher product here and Transaction Link product here.

​
Single Merchant Flow

If you decide to use List Merchants to retrieve a list of merchants, list them in your app, and then open the SDK with a single merchant, you can do so by passing a merchant ID when configuring the session in the KnotConfiguration. More in Retrieving & Listing Merchants. The merchant ID is the same across all environments.
Although available, it is not recommended that you provide a long list of merchants in order to remove a few, but rather “hide” certain merchants that you desire from your Customer Dashboard.

​
Entry Points

In your app’s user experience, you may choose to integrate Knot in one or multiple places (e.g. from different tabs or screens). How users behave when interacting with Knot from each of these “entry points” may vary and it will be useful for you to be able to differentiate these groups of users by entry point in order to assess the value of each entry point. You can provide a value for the entry point in when configuring the session in the KnotConfiguration. This value will be returned in the AUTHENTICATED webhook. Users are presented with a list of merchants in the SDK (unless you provide a single merchant as described above). Accompanying the list is a set of categories and a search experience. Each of these components is visible to users by default (as set in Knot’s backend). You can choose to remove either of them by setting useCategories: false and useSearch: false in KnotConfiguration. This is not recommended.

​
Events

To receive updates from the SDK, implement KnotEventDelegate in your class. 
class MyViewController: UIViewController, KnotEventDelegate {
    func onSuccess(merchant: String) {
        print("Merchant \(merchant) successfully authenticated.")
    }

    func onError(error: KnotError) {
        print("Error occurred: \(error.errorDescription)")
    }

    func onEvent(event: KnotEvent) {
        print("Received event: \(event.event)")
    }

    func onExit() {
        print("Knot session exited.")
    }
}

​
onSuccess

This event is called when a user successfully logged in to the merchant and their card was switched. It takes a single string argument containing the name of the merchant.

​
onError

This event is called when an error occurs during SDK initialization and emits a KnotError enum with 4 possible cases, as described below.
Error CaseDescription
.invalidSessionThe session is invalid.
.expiredSessionThe session has expired.
.invalidClientIdThe client ID is invalid.
.internalErrorAn internal error occurred.
.merchantIdNotFoundThe merchant ID is required.
.invalidCardNameThe card name is invalid.
.invalidCustomerNameThe customer name is invalid.
.invalidLogoIdThe logo ID is invalid.
func onError(error: KnotError) {
    switch error {
    case .invalidSession:
        print("Error: \(error.errorDescription)")
    case .expiredSession:
        print("Error: \(error.errorDescription)")
    case .invalidClientId:
        print("Error: \(error.errorDescription)")
    case .internalError:
        print("Error: \(error.errorDescription)")
	case .merchantIdNotFound:
        print("Error: \(error.errorDescription)")
	case .invalidCardName:
        print("Error: \(error.errorDescription)")
	case .invalidCustomerName:
        print("Error: \(error.errorDescription)")
	case .invalidLogoId:
        print("Error: \(error.errorDescription)")
    }
}

​
onExit

This event is called when a user closes the SDK.

​
onEvent

This event is called when certain events occur in the SDK. With this callback, you will be able to understand how a user is progressing through their lifecycle of authenticating to a merchant. It emits a KnotEvent class as described below. 
/// Represents a Knot event received during user interaction within the Knot SDK.
@objc public class KnotEvent {

    /// The environment the event emitted from
    @objc public let evironment: Environment
    
    /// The product the event emitted from
    @objc public let product: Product
    
    /// The primary event code.
    @objc public let event: String
    
    /// The merchant associated with the event (if applicable).
    @objc public let merchant: String?

	/// The merchant ID associated with the event (if applicable).
    @objc public let merchantId: String?
    
    /// Additional metadata related to the event, stored as an Objective-C compatible dictionary.
    @objc public let metaData: NSDictionary
    
    /// The identifier associated with this event.
    @objc public let taskId: String?
    
...
}
The following list contains all possible events emitted in the KnotEvent.event property.
NameDescription
REFRESH_SESSION_REQUESTEmitted when the session used to initialize the SDK needs to be refreshed.
MERCHANT_CLICKEDEmitted when a user clicks on a merchant from the merchant list.
LOGIN_STARTEDEmitted when a user submits their credentials to login to the merchant.
AUTHENTICATEDEmitted when a user successfully logs in to the merchant.
OTP_REQUIREDEmitted when a user needs to enter an OTP code to login to the merchant.
SECURITY_QUESTIONS_REQUIREDEmitted when a user needs to enter answers to security questions to login to the merchant.
APPROVAL_REQUIREDEmitted when a user needs to approve the login - often via a push notification or directly in the merchant’s mobile app - to login to the merchant.
ZIPCODE_REQUIREDEmitted when a user needs to enter their zip code to login to the merchant.
LICENSE_REQUIREDEmitted when a user needs to enter their drivers license to login to the merchant.

​
Other Options

​
Get current SDK version

If you need to retrieve the current SDK version for your own use case, implement the following: 
let sdkVersion = Knot.SDKVersion()
print("Knot SDK Version: \(sdkVersion ?? "Unknown")")

​
Close the SDK

If you need to explicitly close the SDK, use the below method, otherwise end users will naturally close the SDK as they interact with the interface. 
Knot.close()