Android
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();
cardOnFileSwitcher.init(context, clientId, environment); // parameters data type => (Context, CLIENT_ID, Environment.Development | Environment.PRODUCTION)
cardOnFileSwitcher.openCardOnFileSwitcher(sessionId, merchants); // parameters data type => (String, int[])
var cardOnFileSwitcher = CardOnFileSwitcher.getInstance()
cardOnFileSwitcher?.init(this, this, customization) // parameters data type => (Context, OnSessionEventListener, Customization)
cardOnFileSwitcher?.openCardOnFileSwitcher(sessionId, merchants) // parameters data type => (String, IntArray)
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
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.
Updated 29 days ago