Android Version 2.0+

Overview

To simplify your application logic and integration with the Knot Android SDK, Version 2.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 Android Version 2.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

CardOnFileSwitcher.getInstance(); and Configuration(environment, clientId, sessionId); are replaced with a more flexible KnotConfiguration.
The product type is now defined by Product enum values .card_switcher | .transaction_link.
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(context, knotConfiguration, knotEventDelegate).

Before

CardOnFileSwitcher cardOnFileSwitcher = CardOnFileSwitcher.getInstance();
Configuration switcherConfig = new Configuration(environment, clientId, sessionId);

cardOnFileSwitcher.setMerchantIds(new int[]{44});
cardOnFileSwitcher.setUseCategories(true);
cardOnFileSwitcher.setUseSearch(true);

Options options = new Options();
String[] domainUrls = {"https://domain1.com", "https://domain2.com", ....};
options.setDomainUrls(domainUrls);

cardOnFileSwitcher.init(context, switcherConfig, options, onSessionEventListener);

cardOnFileSwitcher.openCardOnFileSwitcher("Onboarding");

After

KnotConfiguration config = new KnotConfiguration(
    "session_12345",                      // sessionId
    "client_67890",                       // clientId
    Environment.production,               // environment
    Knot.Product.card_switcher,           // product
    new int[]{101, 102, 103},             // merchantIds
    true,                                 // useCategories
    true,                                 // useSearch
    new String[]{"https://example.com"},  // domainUrls
    "onboarding"                          // entryPoint
);

KnotEventDelegate knotEventDelegate = new KnotEventDelegate() {
    @Override
    public void onSuccess(String merchant) {
        // Handle successful operation
    }

    @Override
    public void onError(KnotError knotError) {
        // Handle error operation using knotError
    }

    @Override
    public void onExit() {
        // Handle SDK exit event
    }

    @Override
    public void onEvent(KnotEvent knotEvent) {
        // Extract and process event details from KnotEvent
    }
};

Knot.open(context, config, knotEventDelegate);

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

cardOnFileSwitcher.setOnSessionEventListener(new OnSessionEventListener() {
    @Override
    public void onSuccess(String merchant) {
        Log.d("onSuccess", merchant);
    }

    @Override
    public void onError(String errorCode, String errorMessage) {
        Log.d("onError", errorCode + " " + errorMessage);
    }

    @Override
    public void onExit() {
        Log.d("onExit", "exit");
    }

    @Override
    public void onEvent(String eventName, String merchantName, String taskId) {
        Log.d("onEvent", eventName + " " + merchantName + " " + taskId);
    }
});

After

KnotEventDelegate knotEventDelegate = new KnotEventDelegate() {
    @Override
    public void onSuccess(String merchant) {
        // Handle successful operation
    }

    @Override
    public void onError(KnotError knotError) {
        // Handle error operation using knotError
    }

    @Override
    public void onExit() {
        // Handle SDK exit event
    }

    @Override
    public void onEvent(KnotEvent knotEvent) {
        // Extract and process event details from KnotEvent
    }
};

SendCard

Most apps do not use the explicit sendCard method, as it is rarely applicable to the integration with the Knot SDK.

The sendCard parameter has been deprecated and its functionality is incorporated into the metaData object 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 object 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 object.

@Override
public void onEvent(KnotEvent knotEvent) {
    // Extract the metadata map from the KnotEvent
    Map<String, Object> metaData = knotEvent.getMetaData();
    
    // Check if the metadata contains a sendCard flag 
    if (knotEvent.getEvent().equalsIgnoreCase("AUTHENTICATED") && metaData != null && metaData.containsKey("sendCard")) {
        Boolean sendCard = (Boolean) metaData.get("sendCard");
        Log.d("KnotEvent", "sendCard: " + sendCard);
    } 
}

Event Names

The SDK now maps raw event names to standardized event names for easier handling.

Event Name Prior to 2.0	2.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

@Override
public void onError(String errorCode, String errorMessage) {
  Log.d("onError", errorCode + " " + errorMessage);
}

After

public void onError(KnotError error) {
    switch (error) {
        case INVALID_SESSION:
            Log.e("KnotError", "Error: INVALID_SESSION - " + error.getErrorDescription());
            break;
        case EXPIRED_SESSION:
            Log.e("KnotError", "Error: EXPIRED_SESSION - " + error.getErrorDescription());
            break;
        case INVALID_CLIENT_ID:
            Log.e("KnotError", "Error: INVALID_CLIENT_ID - " + error.getErrorDescription());
            break;
        case INTERNAL_ERROR:
            Log.e("KnotError", "Error: INTERNAL_ERROR - " + error.getErrorDescription());
            break;
    }
}

Error Types

The Knot SDK provides predefined error cases for you to handle based on your own needs.

Error Case	Description
INVALID_SESSION	The session is invalid.
EXPIRED_SESSION	The session has expired.
INVALID_CLIENT_ID	The client ID is invalid.
INTERNAL_ERROR	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.

Changes

Closing the SDK is now statically accessed via Knot.close() as opposed to being bound to the session object.

Before

cardOnFileSwitcher.closeCardOnFileSwitcher();

After

Knot.close();

On this page

Overview
Breaking Changes
Session Initialization
Event Handling
Error Handling
Closing the SDK

Overview

To simplify your application logic and integration with the Knot Android SDK, Version 2.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

Session Initialization

Changes

CardOnFileSwitcher.getInstance(); and Configuration(environment, clientId, sessionId); are replaced with a more flexible KnotConfiguration.
The product type is now defined by Product enum values .card_switcher | .transaction_link.
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(context, knotConfiguration, knotEventDelegate).

Before

CardOnFileSwitcher cardOnFileSwitcher = CardOnFileSwitcher.getInstance();
Configuration switcherConfig = new Configuration(environment, clientId, sessionId);

cardOnFileSwitcher.setMerchantIds(new int[]{44});
cardOnFileSwitcher.setUseCategories(true);
cardOnFileSwitcher.setUseSearch(true);

Options options = new Options();
String[] domainUrls = {"https://domain1.com", "https://domain2.com", ....};
options.setDomainUrls(domainUrls);

cardOnFileSwitcher.init(context, switcherConfig, options, onSessionEventListener);

cardOnFileSwitcher.openCardOnFileSwitcher("Onboarding");

After

KnotConfiguration config = new KnotConfiguration(
    "session_12345",                      // sessionId
    "client_67890",                       // clientId
    Environment.production,               // environment
    Knot.Product.card_switcher,           // product
    new int[]{101, 102, 103},             // merchantIds
    true,                                 // useCategories
    true,                                 // useSearch
    new String[]{"https://example.com"},  // domainUrls
    "onboarding"                          // entryPoint
);

KnotEventDelegate knotEventDelegate = new KnotEventDelegate() {
    @Override
    public void onSuccess(String merchant) {
        // Handle successful operation
    }

    @Override
    public void onError(KnotError knotError) {
        // Handle error operation using knotError
    }

    @Override
    public void onExit() {
        // Handle SDK exit event
    }

    @Override
    public void onEvent(KnotEvent knotEvent) {
        // Extract and process event details from KnotEvent
    }
};

Knot.open(context, config, knotEventDelegate);

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

cardOnFileSwitcher.setOnSessionEventListener(new OnSessionEventListener() {
    @Override
    public void onSuccess(String merchant) {
        Log.d("onSuccess", merchant);
    }

    @Override
    public void onError(String errorCode, String errorMessage) {
        Log.d("onError", errorCode + " " + errorMessage);
    }

    @Override
    public void onExit() {
        Log.d("onExit", "exit");
    }

    @Override
    public void onEvent(String eventName, String merchantName, String taskId) {
        Log.d("onEvent", eventName + " " + merchantName + " " + taskId);
    }
});

After

KnotEventDelegate knotEventDelegate = new KnotEventDelegate() {
    @Override
    public void onSuccess(String merchant) {
        // Handle successful operation
    }

    @Override
    public void onError(KnotError knotError) {
        // Handle error operation using knotError
    }

    @Override
    public void onExit() {
        // Handle SDK exit event
    }

    @Override
    public void onEvent(KnotEvent knotEvent) {
        // Extract and process event details from KnotEvent
    }
};

SendCard

Most apps do not use the explicit sendCard method, as it is rarely applicable to the integration with the Knot SDK.

@Override
public void onEvent(KnotEvent knotEvent) {
    // Extract the metadata map from the KnotEvent
    Map<String, Object> metaData = knotEvent.getMetaData();
    
    // Check if the metadata contains a sendCard flag 
    if (knotEvent.getEvent().equalsIgnoreCase("AUTHENTICATED") && metaData != null && metaData.containsKey("sendCard")) {
        Boolean sendCard = (Boolean) metaData.get("sendCard");
        Log.d("KnotEvent", "sendCard: " + sendCard);
    } 
}

Event Names

The SDK now maps raw event names to standardized event names for easier handling.

Event Name Prior to 2.0	2.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

@Override
public void onError(String errorCode, String errorMessage) {
  Log.d("onError", errorCode + " " + errorMessage);
}

After

public void onError(KnotError error) {
    switch (error) {
        case INVALID_SESSION:
            Log.e("KnotError", "Error: INVALID_SESSION - " + error.getErrorDescription());
            break;
        case EXPIRED_SESSION:
            Log.e("KnotError", "Error: EXPIRED_SESSION - " + error.getErrorDescription());
            break;
        case INVALID_CLIENT_ID:
            Log.e("KnotError", "Error: INVALID_CLIENT_ID - " + error.getErrorDescription());
            break;
        case INTERNAL_ERROR:
            Log.e("KnotError", "Error: INTERNAL_ERROR - " + error.getErrorDescription());
            break;
    }
}

Error Types

The Knot SDK provides predefined error cases for you to handle based on your own needs.

Error Case	Description
INVALID_SESSION	The session is invalid.
EXPIRED_SESSION	The session has expired.
INVALID_CLIENT_ID	The client ID is invalid.
INTERNAL_ERROR	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.

Changes

Closing the SDK is now statically accessed via Knot.close() as opposed to being bound to the session object.

Before

cardOnFileSwitcher.closeCardOnFileSwitcher();

After

Knot.close();

On this page

Overview
Breaking Changes
Session Initialization
Event Handling
Error Handling
Closing the SDK

​Overview

​Breaking Changes

​Session Initialization

​Event Handling

​Error Handling

​Closing the SDK

​Overview

​Breaking Changes

​Session Initialization

​Event Handling

​Error Handling

​Closing the SDK

Overview

Breaking Changes

Session Initialization

Event Handling

Error Handling

Closing the SDK

Overview

Breaking Changes

Session Initialization

Event Handling

Error Handling

Closing the SDK