React Native
Overview
The Knot Link SDK provides a seamless way for end users to link their merchant accounts to your React Native app, serving as the foundation for Knot's merchant connectivity platform. It is a client-side integration, consisting of initializing & configuring the SDK and handling events.
Version 1.0 and later
Version 1.0 of the SDK introduces breaking changes that require changes in your application code if you had previously integrated an early version. See the Migration Guide for further details.
Documentation for older versions of the iOS SDK can be found here.
Installation
The Knot SDK can be installed using npm or yarn in your react-native project directory, like below:
npm install react-native-knotapi --save
From React Native 0.60 and higher, linking is automatic. If you need to manually install the SDK, run the below:
react-native link react-native-knotapi
Usage
import {
Knot,
addKnotListener,
} from "react-native-knotapi";
import {
Knot,
addKnotListener,
type KnotError,
type KnotEvent,
type KnotExit,
type KnotSuccess,
} from "react-native-knotapi";
Initialization
Your backend will create a session by calling Create Session and provide it to your frontend. To start a Knot session, you must first configure the session with a KnotConfiguration
class. The configuration allows you to set the environment, product type, entry point, and other user experience configurations.
Configure the session
The KnotConfiguration
class is used to initialize the SDK with specific parameters.
Name | Type | Description |
---|---|---|
sessionId | String | The session ID (provided by your backend). |
clientId | String | Your organization’s client ID. |
environment | Environment | The desired environment (development or production). |
product | String | The Knot product the session will inherit - the same as the type of session created. E.g. card_switcher . |
entryPoint | String | Optional. The specific entry point from within your app where you are initializing the Knot SDK (e.g. onboarding ). |
useCategories | Boolean | Optional. Whether to display merchant categories and therefore group merchants into categories for discoverability. Default: true . |
useSearch | Boolean | Optional. Whether to display the search bar, enabling users to search for merchants. Default: `true. |
merchantIds | number[] | Optional. A list of merchant ID(s) to display. It is recommended to provide 0 or 1 merchant ID depending on your desired user experience. |
domainURLs | string[] | Optional. Android only. A set of domains for which Knot should explicitly not clear cookies. |
Open the session
To begin the flow, use the open
method like below:
Knot.open({
sessionId: 'session_12345', // Current session ID
clientId: 'client_67890', // Your client ID
environment: 'development', // 'development' || 'production'
product: 'card_switcher', // 'card_switcher' | 'transaction_link'
entryPoint: 'onboarding', // Defined by customer
useCategories: true, // Recommend true
useSearch: true, // Recommend true
merchantIds: [52], // It is not recommended that you provide a long list of merchants
domainUrls: ["https://domain1.com", "https://domain2.com"],
});
Single Merchant Flow
If you decide to use List Merchants to retrieve a list of merchants, list them in your app, and then open the SDK with a single merchant, you can do so by passing a merchant ID when configuring the session in the KnotConfiguration
. More in Retrieving & Listing Merchants. The merchant ID is the same across all environments.
Although available, 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.
Entry Points
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 when when configuring the session in the KnotConfiguration
. This value will be returned in the AUTHENTICATED
webhook.
Categories & Search
Users are presented with a list of merchants in the SDK (unless you provide a single merchant as described above). Accompanying the list is a set of categories and a search experience. Each of these components is visible to users by default (as set in Knot's backend).
You can choose to remove either of them by setting useCategories: false
and useSearch: false
in KnotConfiguration
. This is not recommended.
Events
To receive events from the SDK, implement theaddKnotListener
method.
const onKnotSuccess = addKnotListener('onSuccess', (event) => {
console.log('onSuccess', 'event', event);
});
const onKnotEvent = addKnotListener('onEvent', (event) => {
console.log('onEvent', 'event', event);
});
const onKnotError = addKnotListener('onError', (event) => {
console.log('onError', 'event', event);
});
const onKnotExit = addKnotListener('onExit', (event) => {
console.log('onExit', 'event', event);
});
const onKnotSuccess = addKnotListener('onSuccess', (event: KnotSuccess) => {
console.log('onSuccess', 'event', event);
});
const onKnotEvent = addKnotListener('onEvent', (event: KnotEvent) => {
console.log('onEvent', 'event', event);
});
const onKnotError = addKnotListener('onError', (event: KnotError) => {
console.log('onError', 'event', event);
});
const onKnotExit = addKnotListener('onExit', (event: KnotExit) => {
console.log('onExit', 'event', event);
});
The provided Typescript types can be found below:
export type KnotError = {
errorCode: string;
errorMessage: string;
product?: 'card_switcher' | 'transaction_link';
};
export type KnotEvent = {
event: string;
environment: string;
merchant: string;
metaData?: Record<string, unknown>;
product?: 'card_switcher' | 'transaction_link';
taskId?: string;
};
export type KnotSuccess = {
merchant: string;
product?: 'card_switcher' | 'transaction_link';
};
export type KnotExit = { product?: 'card_switcher' | 'transaction_link' };
onSuccess
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.
onError
onError
This event is called when an error occurs during SDK initialization and emits a KnotError
with the following errors:
errorCode | errorMessage |
---|---|
Session_Not_Found | Invalid session. |
Session_Expired | Session has expired. |
Client_Id_Not_Found | Invalid client ID. |
Internal_Error | An internal error occurred. |
Merchant_Id_Not_Found | The merchant ID is required when product type = transaction_link. |
onExit
onExit
This event is called when a user closes the SDK.
onEvent
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. The following list contains all possible events emitted in the KnotEvent.event
property:
Name | Description |
---|---|
REFRESH_SESSION_REQUEST | Emitted when the session used to initialize the SDK needs to be refreshed. |
MERCHANT_CLICKED | Emitted when a user clicks on a merchant from the merchant list. |
LOGIN_STARTED | Emitted when a user submits their credentials to login to the merchant. |
AUTHENTICATED | Emitted when a user successfully logs in to the merchant. |
OTP_REQUIRED | Emitted when a user needs to enter an OTP code to login to the merchant. |
SECURITY_QUESTIONS_REQUIRED | Emitted when a user needs to enter answers to security questions to login to the merchant. |
APPROVAL_REQUIRED | Emitted when a user needs to approve the login - often via a push notification or directly in the merchant's mobile app - to login to the merchant. |
Other Options
Close the SDK
If you need to explicitly close the SDK, use the below method, otherwise end users will naturally close the SDK as they interact with the interface.
Knot.close();
Maintain cookies
Android only.
Knot clears cookies for security purposes. If your app relies on cookies, you can allowlist specific domains using the domainUrls
configuration in KnotConfiguration
. This is uncommon.
openCardOnFileSwitcher({
sessionId: SESSION_ID,
clientId: CLIENT_ID,
domainUrls: ["https://domain1.com", "https://domain2.com", .....],
environment: "development"
})
Updated 6 days ago