KnotAPI Android SDK

Reference for integrating with the KnotAPI Android Subscription Canceler 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>'
}

Subscription canceler

Import Subscription Canceler

import com.knotapi.cardonfileswitcher.SubscriptionCanceler;

import com.knotapi.cardonfileswitcher.SubscriptionCanceler

Open Subscription canceler

To open the subscription canceler, you can use the following:

SubscriptionCanceler subscriptionCanceler = SubscriptionCanceler.getInstance();
SubscriptionCanceler.init(context, clientId, environment);  // parameters data type => (Context, CLIENT_ID, Environment.SANDBOX | Environment.PRODUCTION)
SubscriptionCanceler.openSubscriptionCanceler(sessionId, merchants);    // parameters data type =>  (String, int[])

var subscriptionCanceler = SubscriptionCanceler.getInstance()
subscriptionCanceler?.init(this, this, customization)   // parameters data type => (Context, OnSessionEventListener, Customization)
subscriptionCanceler?.openSubscriptionCanceler(sessionId, merchants)   // parameters data type =>  (String, IntArray)

Open with specific merchants

To open the Subscription Canceler 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.

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

SubscriptionCanceler.setMerchantIds(intArrayOf(44, 16))

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

SubscriptionCanceler.setMerchantNames(arrayOf("Amazon"))

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 session instance

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

subscriptionCanceler.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 Subscription canceler 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 Subscription canceler 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 Subscription canceler 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 Subscription canceler starts to login into an account.

login success

When the Subscription canceler successfully logs into an account.

require otp

When the Subscription canceler requires the user to enter an OTP.

error

When the Subscription canceler encounters an error when updating the card.