KnotAPI Android SDK

Reference for integrating with the KnotAPI Card Switcher Android SDK

Overview

KnotAPI for Android is an embeddable framework that is bundled and distributed with your application used to create an easy and accessible experience for your customers to update their old saved cards across the web to your new card or cancel subscriptions.

Install Android 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>'
}

Import SDK

To open the Card on File Switcher first you must import the SDK

Import KnotAPI

import com.knotapi.cardonfileswitcher;

import com.knotapi.cardonfileswitcher

Create a session

Then, create a session and obtain the session ID. We recommend, saving this session ID for future debugging, logging, and connecting.

Card on File Switcher

Open Card on File Switcher

To open the Card on File Switcher, you can use the following:

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

The entry point parameter in the openCardOnFileSwitcher function is designed to provide detailed analytics on user interactions with the card switcher in your app. By specifying where in the SDK the function is invoked, you gain valuable insights into user behavior and preferences. This data is essential for understanding how different sections of your app contribute to the overall user experience.

Open with specific merchants

To open the Card on File Switcher with specific merchants, first contact [email protected] to receive the list of merchantIds and names. Pass in the ids or merchant names in the session instance as an array of numbers or strings.

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

cardOnFileSwitcher.setMerchantIds(intArrayOf(44, 16))

cardOnFileSwitcher.setMerchantNames(new String[]{"Amazon"});

cardOnFileSwitcher.setMerchantNames(arrayOf("Amazon"))

Environment

Development

Development is one of the KnotAPI environments on which you can run your code. Development is a test environment in which no real data can be used.

📘

Test Credentials

To test a merchant you can use the login:

username/email: user_good
password: pass_good

Completing the switch

Before showing success in the SDK, Knot expects to receive card details. On the server side, listen for theAUTHENTICATED webhook before sending the card. You can enter your webhook on the dashboard here. Alternatively, in development only, you can mock the endpoint without using a webhook.

Events

Events provide your application real time feedback on the user's journey. These events can be used for in app function, or logging purposes.

To handle events you can set OnSessionEventListener on cardOnFileSwitcher instance

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

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

Then you can override method defined in the OnSessionEventListener

onSuccess

The closure is called when a user successfully updates payment info. It takes a single argument, containing the Merchant name as a String.

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

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

onError

This closure is called when an error occurs during the Card on File Switcher initialization or if there is an issue updating payment info. It should take a two String arguments errorCode and errorMessage.

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

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

onExit

This optional closure is called when a user exits the Card on File Switcher without successfully updating all selected merchants, or when an unhandled error occurs during the Account Updater initialization or if an account has an issue updating payment info.

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

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

onEvent

This closure is called when certain events in the Card on File Switcher flow have occurred, for example, when the user start updating payment info of an account. This enables your application to gain further insight into what is going on as the user goes through the Account Updater flow. It should take a two String arguments eventName and merchantName.

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

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

Events

refresh session request

When the session used to initialize the SDK needs to be refreshed.

login started

When the Card on File Switcher starts to login into an account.

login success

When the Card on File Switcher successfully logs into an account.

require otp

When the Card on File Switcher requires the user to enter an OTP.

card error

When the Card on File Switcher encounters an error related the card info when updating the card.

error

When the Card on File Switcher encounters an error when updating the card.