> ## Documentation Index > Fetch the complete documentation index at: https://docs.knotapi.com/llms.txt > Use this file to discover all available pages before exploring further. # Android > Integrate the Knot Android SDK into your Android application to enable merchant account linking. ## Overview **SDK Updates**\ New versions of the SDK are released frequently, not only to add new features and address issues in the SDK, but also to continuously improve the conversion of merchant login flows. As a result, it is strongly recommended that you frequently update your SDK version across any platforms where you invoke the SDK. The Knot Link SDK provides a seamless way for end users to link their merchant accounts to your Android 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. ## Installation Follow the best-practice installation approach outlined below, which works seamlessly for both Java and Kotlin projects. Adding Maven Central to your root-level `build.gradle` file ensures that the Android Gradle plugin (and all other dependencies) are properly resolved and kept up-to-date. ```groovy Groovy theme={"system"} allprojects { repositories { mavenCentral() } } ``` In your module-level Gradle file (typically `app/build.gradle`), configure your Android settings-such as the minimum SDK version and Java 8 support-to ensure compatibility with the SDK. The Knot SDK Requires Android `API level 21` or greater. ```groovy Groovy theme={"system"} android { defaultConfig { minSdkVersion 21 // or greater } // Enable Java 8 support for KnotAPI SDK compileOptions { sourceCompatibility JavaVersion.VERSION_1_8 targetCompatibility JavaVersion.VERSION_1_8 } } ``` Include the Knot SDK dependency so that Gradle can fetch the SDK from [Maven Central](https://central.sonatype.com/artifact/com.knotapi.knot/knotapi-android-sdk). ```groovy Gradle theme={"system"} implementation group: 'com.knotapi.knot', name: 'knotapi-android-sdk', version: '' ``` ```groovy Gradle (short) theme={"system"} implementation 'com.knotapi.knot:knotapi-android-sdk:' ``` Replace `` with the current version provided by Knot. ```java Java icon=java theme={"system"} import com.knotapi.knot.*; ``` ```kotlin Kotlin icon=k theme={"system"} import com.knotapi.knot.* ``` ## Initialization Your backend will create a session by calling [Create Session](/api-reference/sessions/create-session) and provide it to your frontend. To initialize the Knot SDK, you must first configure the session with a `KnotConfiguration` class. The configuration allows you to set the environment, entry point, and other user experience configurations. It's expected that your integration with Knot will retrieve and pass a new session into the SDK on each initialization. ### Configure the session The `KnotConfiguration` and `CustomerConfiguration` classes are used to initialize the SDK with specific parameters. #### `KnotConfiguration` | Name | Type | Description | | :------------ | :------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | sessionId | String | The session created by calling `/session/create` in your backend. | | clientId | String | Your organization's client ID. Note that this varies between `development` and `production` environments. | | environment | Environment | The desired environment (`development` or `production`). | | entryPoint | String | **Optional.** The specific entry point from within your app where you are initializing the Knot SDK (e.g. `onboarding`). Only alphanumeric characters (a-z, A-Z, 0-9), spaces, ampersands (&), periods (.), and hyphens (-) are allowed. | | merchantIds | int\[] | **Optional.** A list of merchant ID(s) to display. It is recommended to provide 0 or 1 merchant IDs depending on your desired user experience. | | useCategories | Bool | **Optional.** Whether to display merchant categories and therefore group merchants into categories for discoverability. Default: `true`. | | useSearch | Bool | **Optional.** Whether to display the search bar, enabling users to search for merchants. Default: `true`. | | domainUrls | String\[] | **Optional. Deprecated in version 3.0.0+.** A set of domains for which Knot should explicitly not clear cookies. | | metadata | Map\ | **Optional.** Custom key-value pairs to include in [webhook](/webhooks#session-metadata) payloads. Maximum 10 keys with string values up to 500 characters each. | | locale | String | **Optional.** A [BCP-47](https://developer.mozilla.org/en-US/docs/Glossary/BCP_47_language_tag) language tag to set the locale for the SDK. Currently supported: `en-US`, `es-US`, `en-CA`, and `fr-CA`. If not provided, defaults to `en-US`. | | product | Product | **Optional. Ignored in version 2.0.12+.** The Knot product the session will inherit — the same as the type of session created (e.g. `card_switcher`, `transaction_link`). | #### `CustomerConfiguration` This class is entirely optional and infrequently used, typically only when you offer Knot for multiple, differently-named card programs in the same app. The Knot team will set pre-defined values of your choosing for each parameter that you can then subsequently pass into the SDK. Passing a value that is not pre-defined will result in an `onError` callback. To take advantage of this functionality, please contact the Knot team who will be happy to assist you. | Name | Type | Description | | :----------- | :----- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | cardName | String | **Optional.** The differentiated display name for the card product, used inside the Knot SDK (e.g. `Debit Card`, `Credit Card`). This value will override the default value `card`. | | customerName | String | **Optional.** The differentiated display name for the company, used both as a standalone and prepended to the `cardName` (e.g. `Smart Bank`, `Payment Corp`). This value will override your default customer name value. Only recommended if you issue cards under multiple brands. | | logoId | String | **Optional.** The differentiated logo for the company. This value will override your default logo. | See the following examples for how the parameters are used together in text inside the Knot SDK: `"Your [customerName] [cardName | card] was added."` ```java java icon=java theme={"system"} CustomerConfiguration customerConfig = new CustomerConfiguration( "Card Name", // cardName "Customer Name", // customerName "LogoId" // logoId ); Map metadata = new HashMap<>(); metadata.put("reference_token", "your-token"); metadata.put("trace_id", "your-trace-id"); KnotConfiguration config = new KnotConfiguration( "session_12345", // sessionId "client_67890", // clientId Environment.production, // environment new int[]{101}, // merchantIds true, // useCategories true, // useSearch new String[]{"https://example.com"}, // domainUrls (deprecated in 3.0.0+) "onboarding", // entryPoint metadata, // metadata for webhooks customerConfig, "es-US" // locale (optional BCP-47 language tag) ); ``` ```kotlin kotlin icon=k theme={"system"} val customerConfig = CustomerConfiguration( "Card Name", // cardName "Customer Name", // customerName "LogoId" // logoId ) val metadata = mapOf( "reference_token" to "your-token", "trace_id" to "your-trace-id" ) val config = KnotConfiguration( "session_12345", // sessionId "client_67890", // clientId Environment.PRODUCTION, // environment Knot.Product.card_switcher, // product intArrayOf(101, 102, 103), // merchantIds true, // useCategories true, // useSearch arrayOf("https://example.com"), // domainUrls (deprecated in 3.0.0+) "onboarding", // entryPoint metadata, // metadata for webhooks customerConfig, "es-US" // locale (optional BCP-47 language tag) ) ``` ### Open the session To begin the flow, use the `open` method with a `context`, a `KnotConfiguration` instance, and an optional `KnotEventDelegate`. ```java java icon=java theme={"system"} Knot.open(context, knotConfiguration, knotEventDelegate); ``` ```kotlin kotlin icon=k theme={"system"} Knot.open(context, knotConfiguration, knotEventDelegate) ``` ```java java icon=java theme={"system"} CustomerConfiguration customerConfig = new CustomerConfiguration( "Card Name", // cardName "Customer Name", // customerName "LogoId" // logoId ); Map metadata = new HashMap<>(); metadata.put("reference_token", "your-token"); KnotConfiguration config = new KnotConfiguration( "session_12345", // sessionId "client_67890", // clientId Environment.production, // environment new int[]{101}, // merchantIds true, // useCategories true, // useSearch new String[]{"https://example.com"}, // domainUrls (deprecated in 3.0.0+) "onboarding", // entryPoint metadata, // metadata for webhooks customerConfig, "es-US" // locale (optional BCP-47 language tag) ); Knot.open(context, config, knotEventDelegate); ``` ```kotlin kotlin icon=k theme={"system"} val customerConfig = CustomerConfiguration( "Card Name", // cardName "Customer Name", // customerName "LogoId" // logoId ) val metadata = mapOf("reference_token" to "your-token") val config = KnotConfiguration( "session_12345", // sessionId "client_67890", // clientId Environment.PRODUCTION, // environment Knot.Product.card_switcher, // product intArrayOf(101, 102, 103), // merchantIds true, // useCategories true, // useSearch arrayOf("https://example.com"), // domainUrls (deprecated in 3.0.0+) "onboarding", // entryPoint metadata, // metadata for webhooks customerConfig, "es-US" // locale (optional BCP-47 language tag) ) Knot.open(context, config, knotEventDelegate) ``` To test logging in to a merchant in the SDK, please reference a set of available test credentials for the CardSwitcher product [here](/card-switcher/testing) and the TransactionLink product [here](/transaction-link/testing). ## Single Merchant Flow If you decide to use [List Merchants](/api-reference/merchants/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.`If a single merchant ID is provided, the user will be sent directly to that merchant's login experience in the SDK. More in [Retrieving & Listing Merchants](/link/retrieving-and-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](https://dashboard.knotapi.com/). ## 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 `KnotConfiguration.entryPoint` when [configuring the session ](/sdk/android#configure-the-session). 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 updates from the SDK, implement `KnotEventDelegate` in your class. ```java java icon=java theme={"system"} // Initialize your event delegate KnotEventDelegate eventDelegate = new KnotEventDelegate() { @Override public void onSuccess(String merchant) { // Handle successful operation } @Override public void onError(KnotError knotError) { // Handle error operation using knotError } @Override public void onExit() { // Handle SDK exit event } @Override public void onEvent(KnotEvent knotEvent) { // Extract and process event details from KnotEvent } }; // Initialize Knot SDK and set the event delegate instance (assuming you have a KnotConfiguration object) Knot.open(context, knotConfiguration, eventDelegate) ``` ```kotlin kotlin icon=k theme={"system"} // Initialize your event delegate val eventDelegate = object : KnotEventDelegate { override fun onSuccess(merchant: String) { // Handle successful operation } override fun onError(knotError: KnotError) { // Handle error operation using knotError } override fun onExit() { // Handle SDK exit event } override fun onEvent(knotEvent: KnotEvent) { // Extract and process event details from KnotEvent } } // Initialize Knot SDK and set the event delegate instance (assuming you have a KnotConfiguration object) Knot.open(context, knotConfiguration, eventDelegate) ``` ### `onSuccess` This event is called when a user successfully logged in to the merchant and their card was switched. This event takes a single string argument representing the merchant's name. ### `onError` This event is called when an error occurs during SDK initialization. It emits a `KnotError` enum as described below. | Error Case | Description | Debugging Steps | | ------------------------ | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | INVALID\_SESSION | The session is invalid. | Ensure `KnotConfiguration.environment` matches the environment the `sessionId` was created for (`development` or `production`). | | EXPIRED\_SESSION | The session has expired. | Sessions are valid for 30 minutes. It is best practice to ensure that you create a new session **every time** a user invokes the SDK using [Create Session](/api-reference/sessions/create-session). | | INVALID\_CLIENT\_ID | The client ID is invalid. | Verify that the value you are providing for `KnotConfiguration.clientId` is for the environment matching the value you are providing for `KnotConfiguration.environment` (i.e. `development` or `production`). If you provide your production `clientId` but set `environment: development`, you will experience this error. | | INTERNAL\_ERROR | An internal error occurred. | Simply retry invoking the SDK with a new `sessionId`. | | MERCHANT\_ID\_NOT\_FOUND | The merchant ID is required. | The [`type`](/api-reference/sessions/create-session#body-type) of `sessionId` you are providing on invokation of the SDK requires that you also provide a value in `KnotConfiguration.merchantIds` to ensure the user is directed to a specific merchant's login flow in the SDK. You can retrieve a list of merchant IDs (the same in all environments) in [List Merchants](/api-reference/merchants/list-merchants). | | INVALID\_CARD\_NAME | The card name is invalid. | The value you are providing for `customerConfiguration.cardName` must exactly match an allowlisted value for your organization. Please reach out to the Knot team for access to this allowlist. | | INVALID\_CUSTOMER\_NAME | The customer name is invalid. | The value you are providing for `customerConfiguration.customerName` must exactly match an allowlisted value for your organization. Please reach out to the Knot team for access to this allowlist. | | INVALID\_LOGO\_ID | The logo ID is invalid. | The value you are providing for `customerConfiguration.logoId` must exactly match an allowlisted value for your organization. Please reach out to the Knot team for access to this allowlist. | | INVALID\_LOCALE | The locale is invalid. | The value you are providing for `KnotConfiguration.locale` must be a valid [BCP-47](https://developer.mozilla.org/en-US/docs/Glossary/BCP_47_language_tag) language tag. Currently supported: `en-US`, `es-US`, `en-CA`, and `fr-CA`. | Sessions are valid for 30 minutes. If a session expires while the SDK is open, an expired session error will be emitted via `onError` and the SDK will automatically close. To provide a seamless experience, handle the `REFRESH_SESSION_REQUEST` event via the `onEvent` callback to proactively extend the session using [Extend Session](/api-reference/sessions/extend-session) before expiration occurs. ```java java icon=java theme={"system"} public void onError(KnotError error) { switch (error) { case INVALID_SESSION: Log.e("KnotError", "Error: INVALID_SESSION - " + error.getErrorDescription()); break; case EXPIRED_SESSION: Log.e("KnotError", "Error: EXPIRED_SESSION - " + error.getErrorDescription()); break; case INVALID_CLIENT_ID: Log.e("KnotError", "Error: INVALID_CLIENT_ID - " + error.getErrorDescription()); break; case INTERNAL_ERROR: Log.e("KnotError", "Error: INTERNAL_ERROR - " + error.getErrorDescription()); break; case MERCHANT_ID_NOT_FOUND: Log.e("KnotError", "Error: MERCHANT_ID_NOT_FOUND - " +error.getErrorDescription()); break; case INVALID_CARD_NAME: Log.e("KnotError", "Error: INVALID_CARD_NAME - " +error.getErrorDescription()); break; case INVALID_CUSTOMER_NAME: Log.e("KnotError", "Error: INVALID_CUSTOMER_NAME - " +error.getErrorDescription()); break; case INVALID_LOGO_ID: Log.e("KnotError", "Error: INVALID_LOGO_ID - " +error.getErrorDescription()); break; case INVALID_LOCALE: Log.e("KnotError", "Error: INVALID_LOCALE - " +error.getErrorDescription()); break; } } ``` ```kotlin kotlin icon=k theme={"system"} fun onError(error: KnotError) { when (error) { KnotError.INVALID_SESSION -> Log.e("KnotError", "Error: INVALID_SESSION - ${error.errorDescription}") KnotError.EXPIRED_SESSION -> Log.e("KnotError", "Error: EXPIRED_SESSION - ${error.errorDescription}") KnotError.INVALID_CLIENT_ID -> Log.e("KnotError", "Error: INVALID_CLIENT_ID - ${error.errorDescription}") KnotError.INTERNAL_ERROR -> Log.e("KnotError", "Error: INTERNAL_ERROR - ${error.errorDescription}") KnotError.MERCHANT_ID_NOT_FOUND -> Log.e("KnotError", "Error: MERCHANT_ID_NOT_FOUND - ${error.errorDescription}") KnotError.INVALID_CARD_NAME -> Log.e("KnotError", "Error: INVALID_CARD_NAME - The card name is invalid.") KnotError.INVALID_CUSTOMER_NAME -> Log.e("KnotError", "Error: INVALID_CUSTOMER_NAME - The customer name is invalid.") KnotError.INVALID_LOGO_ID -> Log.e("KnotError", "Error: INVALID_LOGO_ID - ${error.errorDescription}") KnotError.INVALID_LOCALE -> Log.e("KnotError", "Error: INVALID_LOCALE - ${error.errorDescription}") } } ``` ### `onExit` This event is called when a user closes the SDK. ### `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. It emits a `KnotEvent` class as described below. ```java java icon=java theme={"system"} public void onEvent(KnotEvent knotEvent) { // Extract event details from the KnotEvent object // The type of event that occurred (e.g., "MERCHANT_CLICKED", "AUTHENTICATED") String eventType = knotEvent.getEvent(); // The product the event emitted from String product = knotEvent.getProduct(); // The environment the event emitted from String environment = knotEvent.getEnvironment(); // The merchant associated with the event (if applicable) String merchant = knotEvent.getMerchantName(); // The merchant Id associated with the event (if applicable) String merchantId = knotEvent.getMerchantId(); // The unique identifier for this specific event instance String taskId = knotEvent.getTaskId(); // Additional metadata a key-value map containing extra details related to the event Map metadata = knotEvent.getMetaData(); //Additional processing if applicable }; ``` ```kotlin kotlin icon=k theme={"system"} fun onEvent(knotEvent: KnotEvent) { // Extract event details from the KnotEvent object // The type of event that occurred (e.g., "MERCHANT_CLICKED", "AUTHENTICATED") val eventType: String = knotEvent.event // The product the event emitted from val product = knotEvent.getProduct() // The environment the event emitted from val environment = knotEvent.getEnvironment() // The merchant associated with the event val merchant: String = knotEvent.merchantName // The unique identifier for this specific event instance val taskId: String = knotEvent.taskId // Additional metadata - a key-value map containing extra details related to the event val metadata: Map = knotEvent.metaData // Additional processing if applicable } ``` Below is a list of all possible events emitted via the `KnotEvent.event` property. | Name | Description | | ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | REFRESH\_SESSION\_REQUEST | Emitted when the session used to initialize the SDK needs to be refreshed. Use [Extend Session](/api-reference/sessions/extend-session) to extend the session before expiration occurs. | | 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. | | ZIPCODE\_REQUIRED | Emitted when a user needs to enter their zip code to login to the merchant. | | LICENSE\_REQUIRED | Emitted when a user needs to enter their drivers license to login to the merchant. | ## Other Options ### Get current SDK version If you need to retrieve the current SDK version for your own use case, implement the following: ```java Java icon=java theme={"system"} String sdkVersion = Knot.getSdkVersion(); Log.d("Knot SDK Version", sdkVersion != null ? sdkVersion : "Unknown"); ``` ```kotlin Kotlin icon=k theme={"system"} val sdkVersion = Knot.getSdkVersion() Log.d("Knot SDK Version", sdkVersion ?: "Unknown") ``` ### 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. ```java java icon=java theme={"system"} Knot.close(); ``` ```kotlin kotlin icon=k theme={"system"} Knot.close() ``` ### Maintain cookies `domainUrls` is deprecated in version 3.0.0+ and will be removed in a future release. 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.** ```java java icon=java theme={"system"} // The allowed domains for cookies to add as a parameter in KnotConfiguration String[] domainUrls = new String[]{ "https://example.com", "https://secure.example.com", "https://auth.example.com" }; ``` ```kotlin kotlin icon=k theme={"system"} // The allowed domains for cookies to add as a parameter in KnotConfiguration val domainUrls = arrayOf( "https://example.com", "https://secure.example.com", "https://auth.example.com" ) ```