Installing the SDK

We recommend using Gradle to obtain the necessary files and keep them up-to-date.

Update your project plugins

In your root-level (project-level) Gradle file (build.gradle), add rules to include the Android Gradle plugin.

allprojects {
    repositories {
    	mavenCentral()
    }
}

Add the KnotAPI SDK to your app

In your module (app-level) Gradle file (usually app/build.gradle), add a line to the bottom of the file. The latest version of the KnotAPI SDK is Maven Central and can be found on Maven Central.

android {
  defaultConfig {
      minSdkVersion 21 // or greater
  }

  // Enable Java 8 support for Link to work
  compileOptions {
    sourceCompatibility JavaVersion.VERSION_1_8
    targetCompatibility JavaVersion.VERSION_1_8
  }
}

dependencies {
  // ...
  implementation 'com.knotapi.cardonfileswitcher:knotapi-android-sdk:<insert latest version>'
}

Importing the SDK

Import knotapi

import com.knotapi.cardonfileswitcher;

import com.knotapi.cardonfileswitcher

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.

Open Card on File Switcher

CardOnFileSwitcher cardOnFileSwitcher = CardOnFileSwitcher.getInstance();
Configuration switcherConfig = new Configuration(environment, clientId, sessionId);
cardOnFileSwitcher.init(context, switcherConfig);
cardOnFileSwitcher.openCardOnFileSwitcher("Onboarding");    // Onboarding is the entry point

var cardOnFileSwitcher = CardOnFileSwitcher.getInstance()
var switcherConfig = Configuration(environment, clientId, sessionId);
cardOnFileSwitcher?.init(this, switcherConfig)
cardOnFileSwitcher?.openCardOnFileSwitcher("Onboarding")   // Onboarding is the entry point

📘

Expected behavior

It's expected that your integration with Knot will retrieve and pass a new session_id into the SDK on each initialization.

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.

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

cardOnFileSwitcher.setMerchantIds(intArrayOf(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.

cardOnFileSwitcher.openCardOnFileSwitcher("onboarding");

cardOnFileSwitcher.openCardOnFileSwitcher("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.

cardOnFileSwitcher.setUseCategories(true);

cardOnFileSwitcher.setUseSearch(true);

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, call setOnSessionEventListener on the cardOnFileSwitcher instance like below:

cardOnFileSwitcher.setOnSessionEventListener(new OnSessionEventListener() {
      //override functions here
    })

cardOnFileSwitcher.setOnSessionEventListener(object : OnSessionEventListener {
      //override functions here
    })

Next, use the following override methods defined in the OnSessionEventListener.

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.

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

override fun onSuccess(merchant: String?) {
   Log.d("onSuccess", merchant!!)
}

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.

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

override fun onError(error: String?, errorMessage: String?) {
  Log.d("onError", "$error $errorMessage")
}

onExit

This event is called when a user closes the SDK.

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

override fun onExit() {
  Log.d("onExit", "exit")
}

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.

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

override fun onEvent(eventName: String?, merchantName: String?, taskId: String?) {
  Log.d("onEvent", "$eventName $merchantName $taskId")
}

Events

Other Options

Closing the SDK

You can explicitly close the SDK with the following method:

cardOnFileSwitcher.closeCardOnFileSwitcher();

Implementing using cookies for authentication

Knot clears cookies for security purposes, so if you use cookies in your app, you can allow list your domains using the domainUrls option. This is uncommon.

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

val options = Options()
val domainUrls = arrayOf("https://domain1.com", "https://domain2.com")
options.setDomainUrls(domainUrls)