iOS
Installing the SDK
We recommend using CocoaPods to obtain the necessary files and keep them up-to-date. The latest version can be found here.
CocoaPods
-
If you haven’t already, install the latest version of CocoaPods.
-
If you don’t have an existing Podfile, run the following command to create one:
pod init
- Add this line to your Podfile:
pod 'KnotAPI'
- Run the following command:
pod install
Swift Package Manager
To integrate KnotAPI using Swift Package Manager, you'll need Swift version 5.3 or later. Follow these steps within your Xcode project:
- Go to File, Add Packages.
- In the top right corner of the dialog box, you'll see a search bar. Enter the KnotAPI package URL: https://github.com/millionscard/knot-api-ios.
- From the results, choose the knot-api-ios package.
- Decide on your Dependency Rule. We suggest opting for Up to Next Major Version.
- Choose the project you want to integrate with KnotAPI, and then click on Add Package.
- Pick the KnotAPI package product and click on Add Package.
- Confirm that KnotAPI Swift package was added as a package dependency to your project successfully.
Importing the SDK
Import KnotAPI
import KnotAPI
#import "KnotAPI/KnotAPI-Swift.h"
Create a Session
Then, Create a Session to retrieve a session_id
. We recommend saving this session_id
for future debugging and logging in development.
Initialize a Session
let session = Knot.createCardSwitcherSession(sessionId: "SESSION_ID", clientId: "CLIENT_ID", environment: .development)
KnotSession * session = [Knot createCardSwitcherSessionWithId:@"SessionId" clientId:@"ClientID" environment: EnvironmentSandbox];
Expected behavior
It's expected that your integration with Knot will retrieve and pass a new
session_id
into the SDK on each initialization.
Open Card on File Switcher
session.entryPoint = "Onboarding" // Optionally, set an entry point for the session
session.merchantNames = ["T-Mobile", "Amazon"] // Optionally, set a restricted list of merchants
Knot.open(session: session)
session.entryPoint = @"onBoarding";
session.merchantNames = @[@"T-Mobile", @"Amazon"];
[Knot openWithSession: session];
Create Card on File Switcher View Controller and Embed it Into your UI Hierarchy
class MyViewController : UIViewController {
func configureKnot() {
let controller = Knot.createViewController(session: session)
view.addSubview(controller.view)
addChild(controller)
}
...
}
To ensure seamless integration and avoid any UI issues when embedding the Card on File Switcher 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.
Switch a Card
After a user authenticates to a merchant, you will receive the AUTHENTICATED
webhook indicating that it is time to switch the card. Immediately upon receiving this webhook, make a call to the Switch Card endpoint.
Opening With Specific Merchants
If you decide to use Get Merchants to retrieve a list of merchants, list them in your app, and then open the SDK with a specific merchant, you can do so by passing a merchant ID in the session instance as an array of numbers. More in Retrieving & Listing Merchants. The merchant ID is the same across all environments.
Single Merchant ID
If a single merchant ID or merchant name is provided, the user will be sent directly to that merchant's login experience in the SDK.
Multiple Merchant IDs (Not Recommended)
If multiple merchant IDs are provided, the user will see a list of only those merchants to select from. 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.
session.merchantIds = [44]
session.merchantIds = @[@44, @16];
Opening With an Entry Point
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 the session instance when you open the SDK. This value will be returned in the AUTHENTICATED
webhook.
session.entryPoint = "onboarding"
Opening With Categories and Search
Users are presented with a list of merchants in the SDK (unless you provide a single merchant as described above). Along with the list is a set of categories and search experience. Each of these components is visible to users by default (as set in Knot's backend), however, you can choose to remove either of them by setting setUseCategories: false
and setUseSearch: false
. This is not recommended.
session.setUseCategories = true
session.merchantNames = @[@"Amazon"];
session.setUseSearch = true
session.merchantNames = @[@"Amazon"];
Testing in Development
To test a user's lifecycle through the SDK in the Development environment, you can use the following credentials when authenticating to a merchant:
username/email: user_good; password: pass_good
A full list of credentials useful in testing various merchant login scenarios can be found here.
Events
Events provide your application with real time feedback and can be used to build in-app functionality or for logging purposes. To handle events, add callbacks to the session instance, first by creating a session object like below:
let session = Knot.createCardSwitcherSession(sessionId: "SESSION_ID", clientId: "CLIENT_ID", environment: .development)
KnotSession * session = [Knot createCardSwitcherSessionWithId:@"SessionId" clientId:@"ClientID" environment: EnvironmentSandbox];
Next, set closures on the session.
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.
session.onSuccess = { merchant in
print("merchant: \(merchant)")
}
session.onSuccess = ^(NSString *merchant) {
// handle success event
};
onError
This event is called when an error occurs during SDK initialization or when a card switch is unsuccessful. It takes two string arguments containing the error code and error message.
session.onError = { errorCode, errorMessage in
print("errorCode: \(errorCode), errorMessage: \(errorMessage)")
}
session.onError =^(NSString * error, NSString * message) {
// handle error event
};
onExit
This event is called when a user closes the SDK.
session.onExit = {
print("onExit")
}
session.onExit = ^{
// handle exit event
};
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. This event takes three string arguments containing the event name, merchant name, and task id.
session.onEvent = { event, merchant, taskId in
print("event: \(eventName), merchant: \(merchantName), taskId: \(taskId)")
}
session.onEvent = ^(NSString * event, NSString * message) {
// handle event
};
Events
Event | Description |
---|---|
refresh session request | When the session used to initialize the SDK needs to be refreshed. |
merchant clicked | When a user clicks on a merchant from the merchant list. |
login started | When a user submits their credentials to login to the merchant. |
login success (deprecated) | When a user successfully logs in to the merchant. |
authenticated | When a user successfully logs in to the merchant. |
require otp | When a user needs to enter an OTP code to login to the merchant. |
Other Options
Closing the SDK
You can explicitly close the SDK with the following method:
Knot.close()
[Knot close];
Updated about 1 month ago