Overview
To simplify your application logic and integration with the Knot iOS SDK, Version 1.0 includes a number of breaking changes that may affect the way your integration works or behaves.
The new version includes a number of significant improvements:
- Enhanced speed and stability in loading merchant flows.
- More streamlined initialization of the SDK.
- Simplified event handling, more informative event messaging, and uniform naming conventions for easier debugging.
- Improved maintainability and foundations for new feature compatibility.
Breaking Changes
Configuring and opening the Knot SDK has changed significantly in iOS Version 1.0 and requires some refactoring in order to initialize the SDK with a session. Errors are now encapsulated in a KnotError object which provides an enumerated value to debug with.
Session Initialization
Changes
Knot.createCardSwitcherSession and Knot.createTransactionsLinkSession are replaced with a more flexible KnotConfiguration.- The new interface allows configuration of additional properties such as
useCategories, useSearch, and merchantIds.
- The
open action now requires a KnotConfiguration and an optional KnotEventDelegate which is now Knot.open(configuration:delegate:).
Before
let session = CardOnFileSwitcherSession(sessionId: "SESSION_ID", clientId: "CLIENT_ID", environment: .sandbox)
session.entryPoint = "Onboarding" // Optionally, set an entry point.
session.merchantIds = [44] // Optionally, a specific merchant Id
Knot.open(session: session)
let configuration = KnotConfiguration(
sessionId: "SESSION_ID",
clientId: "CLIENT_ID",
environment: .development,
entryPoint: nil,
product: .card_switcher,
useCategories: true,
useSearch: false,
merchantIds: nil
)
Knot.open(configuration: configuration, delegate: self)
Event Handling
Changes
- Event handling is now managed through
KnotEventDelegate instead of closures.
- Events like
onSuccess, onError, and onExit are now explicit methods inside a delegate.
- The
onEvent method introduces the KnotEvent object to better handle Knot emitted events.
- The
KnotError type provides improved error descriptions.
- The
sendCard parameter is deprecated and its functionality incorporated into the metaData dictionary within KnotEvent when KnotEvent.event equals AUTHENTICATED.
Before
session.onSuccess = { merchant in
print("Successfully updated card for \(merchant)")
}
session.onError = { errorCode, errorMessage in
print("Error: \(errorCode) - \(errorMessage)")
}
session.onExit = {
print("User exited the SDK")
}
session.onEvent = { event, merchant, taskId, sendCard in
print("event code: \(event), merchant: \(merchant), taskId: \(taskId), sendCard: \(sendCard)")
}
class MyViewController: UIViewController, KnotEventDelegate {
func onSuccess(merchant: String) {
print("Successfully updated card for \(merchant)")
}
func onError(error: KnotError) {
print("Error: \(error.errorDescription)")
}
func onEvent(event: KnotEvent) {
print("Event: \(event.event)")
}
func onExit() {
print("User exited the SDK")
}
}
Most apps do not use the explicit sendCard method, as it is rarely applicable to the integration with the Knot SDK.
sendCard parameter has been deprecated and its functionality is incorporated into the metaData dictionary within KnotEvent when the KnotEvent.event equals AUTHENTICATED. This change enhances flexibility by allowing additional contextual data to be included in events without requiring separate parameters. Previously, sendCard was accessed as a standalone value, but now developers can retrieve it from the metaData dictionary in the event callback. This approach ensures better extensibility and consistency across different event types. To access the sendCard value, simply extract it from the event’s metaData dictionary.
class MyViewController: UIViewController, KnotEventDelegate {
func onSuccess(merchant: String) {
print("Successfully updated card for \(merchant)")
}
func onError(error: KnotError) {
print("Error: \(error.errorDescription)")
}
func onEvent(event: KnotEvent) {
if event.event == "AUTHENTICATED" {
print("Event.AUTHENTICATED sendCard: \(event.metaData["sendCard"] as? Bool)")
}
}
func onExit() {
print("User exited the SDK")
}
}}
| Event Name Prior to 1.0 | 1.0 Event Name |
|---|
| refresh session request | REFRESH_SESSION_REQUEST |
| merchant clicked | MERCHANT_CLICKED |
| login started | LOGIN_STARTED |
| authenticated | AUTHENTICATED |
| otp required | OTP_REQUIRED |
| security questions required | SECURITY_QUESTIONS_REQUIRED |
| approval required | APPROVAL_REQUIRED |
Error Handling
Error handling has been improved with more structured and meaningful error messages.
Changes
- Errors are now encapsulated in the
KnotError enum.
- Each error has a human-readable description (
errorDescription) and a unique error code (errorCode).
- Improved clarity and consistency across error messages.
Before
session.onError = { errorCode, errorMessage in
print("Error: \(errorCode) - \(errorMessage)")
}
func onError(error: KnotError) {
switch error {
case .invalidSession:
print("Error: Session is invalid. Please check your session ID.")
case .expiredSession:
print("Error: Session has expired. Please start a new session.")
case .invalidClientId:
print("Error: Invalid client ID. Ensure your credentials are correct.")
case .internalError:
print("Error: An internal error occurred. Try again later.")
}
}
| Error Case | Description |
|---|
| .invalidSession | The session is invalid. |
| .expiredSession | The session has expired. |
| .invalidClientId | The client ID is invalid. |
| .internalError | An internal error occurred. |
Closing the SDK
Most apps do not use the explicit close method, as it is infrequently applicable to the integration with the Knot SDK.
- Closing the SDK is now statically accessed via
Knot.close() as opposed to being bound to the session object.
Before
After
