KnotAPI iOS SDK

Reference for integrating with the KnotAPI iOS Subscription Canceler SDK

Overview

KnotAPI for iOS 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 iOS SDK

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

CocoaPods

1. If you haven’t already, install the latest version of CocoaPods.

2. If you don’t have an existing Podfile, run the following command to create one:

pod init

3. Add this line to your Podfile:

pod 'KnotAPI', '0.1.49'

4. Run the following command:

pod install

Import SDK

To open the Subscription Canceler first you must import the SDK

Import KnotAPI

import KnotAPI

#import "KnotAPI/KnotAPI-Swift.h"

Create a user

Now, create a user and obtain the knot_access_token. We recommend, saving this knot_access_token for future debugging, logging, and connecting.

Create a session

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

Subscription Canceler

Initialize a session

To initialize a session, you can use the following:

let session = SubscriptionCancelerSession(sessionId: "SESSION_ID", clientId: "CLIENT_ID, environment: .sandbox)

SubscriptionCancelerSession * session = [[SubscriptionCancelerSession alloc] initWithSessionId:@"SessionId" clientId:@"ClientID" environment: EnvironmentSandbox];

Open Subscription Canceler

To open the Subscription Canceler, you can use the following:

session.openSubscriptionCanceler()

[session openOnSubscriptionCancelerWithMerchants:@[]];

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.

session.setMerchantIds(merchantIds: [44, 16])

[session setMerchantIdsWithMerchantIds:@[@44, @16]];

session.setMerchantNames(merchantNames: ["Netflix"])

[session setMerchantNamesWithMerchantNames:@[@"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 create an instance of SubscriptionCancelerConfiguration and set it on the session instance:

class ViewController: UIViewController  {
  let session = CardOnFileSwitcherSession(sessionId: "SESSION_ID")
  let config = SubscriptionCancelerConfiguration()
  session.setConfiguration(config: config)

CardOnFileSwitcherSession * session = [[CardOnFileSwitcherSession alloc] initWithSessionId:@"SESSION_ID"];
SubscriptionCancelerConfiguration *config = [[SubscriptionCancelerConfiguration alloc] init];
[session setConfigurationWithConfiguration: config];

Then you can set closures on the config instance

onSuccess

The closure is called when a user successfully cancels a subscription. It should take a single argument, containing the Merchant name.

config.setOnSuccess { merchant in
            print("SubscriptionCanceler onSuccess Merchant: \(merchant)")
        }

[config setOnSuccessOnSuccess:^(NSString *merchant) {
  // handle success
}];

onError

This closure is called when an error occurs during Subscription Canceler initialization or if an account has an issue canceling a subscription. It should take a two String arguments errorCode and errorMessage.

config.setOnError { error, message in
            print("SubscriptionCanceler Error: \(error), Message: \(message)")
        }

[config setOnErrorOnError:^(NSString * error, NSString * message) {
  // handle error
}];

onExit

This optional closure is called when a user exits Subscription Canceler without successfully updating all selected merchants, or when an unhandled error occurs during Subscription Canceler initialization or if an account has an issuing canceling a subscription.

config.setOnExit {
            print("SubscriptionCanceler onExit")
        }

[config setOnExitOnExit:^{
  // handle exit
}];

onEvent

This closure is called when certain events in the Subscription Canceler flow have occurred, for example, when the user starts canceling a subscription. This enables your application to gain further insight into what is going on as the user goes through the Subscription Canceler flow. It should take a two String arguments eventName and merchantName.

config.setOnEvent(onEvent: { event, merchant in
            print("SubscriptionCanceler Event: \(event), Merchant: \(merchant)")
        })

[config setOnEventOnEvent:^(NSString * event, NSString * message) {
  // handle event
}];

Events

login started

When the Subscription Canceler starts authenticating an account.

login success

When the Subscription Canceler successfully authenticates an account.

require otp

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

error

When the Subscription Canceler encounters an error when canceling the subscription.