​
Overview

This guide will help you migrate from the legacy OTPLESS Headless SDK to the new version. The new SDK offers improved performance, reliability, and security features.

​
Key Changes

  1. Package Name Change

    • Legacy: io.github.otpless-tech:otpless-android-sdk
    • New: io.github.otpless-tech:otpless-headless-sdk

  2. Minimum Requirements

    • compileSdk 35
    • minSdk 21 (Android 5.0)
    • Kotlin 1.9.0+
    • Gradle 8.3.1+

​
Migration Steps

​
1. Update Dependencies

Please check the latest version of the SDK here.

- implementation 'io.github.otpless-tech:otpless-android-sdk:2.6.3'
+ implementation 'io.github.otpless-tech:otpless-headless-sdk:latest_version'

​
2. Update Import Statements

- import com.otpless.main.OtplessManager
- import com.otpless.main.OtplessView
+ import com.otpless.v2.android.sdk.main.OtplessSDK

​
3. Update Initialization

- val otplessView = OtplessManager.getInstance().getOtplessView(this)
- otplessView.initHeadless("YOUR_APP_ID")
- otplessView.setHeadlessCallback(this::onHeadlessCallback)
+ OtplessSDK.initialize(appId = "YOUR_APP_ID", activity = activity)
+ OtplessSDK.setResponseCallback(this::onOtplessResponse)

​
4. Update URL Handling

​
In Activity:

override fun onNewIntent(intent: Intent?) {
    super.onNewIntent(intent)
-   otplessView?.onNewIntent(intent)
+   lifecycleScope.launch {
+       OtplessSDK.onNewIntent(intent)
+   }
}

- override fun onBackPressed() {
-     if (otplessView?.onBackPressed() == true) return
-     super.onBackPressed()
- }

​
5. Update Request Objects

- val request = HeadlessRequest()
+ val request = OtplessRequest()

// For Phone Auth
- request.setPhoneNumber("91", "9899038845")
+ request.setPhoneNumber(number = "9899038845", countryCode = "91")

// For Email Auth
- request.setEmail("user@example.com")
+ request.setEmail("user@example.com")

// For OAuth
- request.setChannelType(HeadlessChannelType.WHATSAPP)
+ request.setChannelType(OtplessChannelType.WHATSAPP)

​
6. Update Authentication Calls

- otplessView.startHeadless(request, this::onHeadlessCallback)
+ lifecycleScope.launch {
+     OtplessSDK.start(request = request, callback = ::onOtplessResponse)
+ }

​
7. Update Response Handling

The callback handling has been significantly improved in the new SDK. Here’s how to migrate your callback implementation (For more information find new sdk documentation):

- private fun onHeadlessCallback(response: HeadlessResponse) {
-     when (response.getResponseType()) {
-         "INITIATE" -> {
-             // Handle initiation
-         }
-         "VERIFY" -> {
-             // Handle verification
-         }
-         "ONETAP" -> {
-             val token = response.getResponse().optString("token")
-         }
-     }
- }

+ private fun onOtplessResponse(response: OtplessResponse) {
+     OtplessSDK.commit(response)
+     when (response.responseType) {
+         ResponseTypes.SDK_READY -> {
+             // SDK has been initialized successfully
+             // You can enable your continue button or proceed with user authentication
+         }
+         
+         ResponseTypes.FAILED -> {
+             if (response.statusCode == 5003) {
+                 // SDK initialization failed, try to initialize again
+             }
+         }
+         
+         ResponseTypes.INITIATE -> {
+             if (response.statusCode != 200) {
+                 handleInitiateError(response)
+             } else {
+                 val authType = response.response?.optString("authType")
+                 when (authType) {
+                     "OTP" -> {
+                         // Navigate to OTP verification screen
+                     }
+                     "SILENT_AUTH" -> {
+                         // Show loading status for Silent Authentication
+                     }
+                 }
+             }
+         }
+         
+         ResponseTypes.OTP_AUTO_READ -> {
+             val otp = response.response?.optString("otp")
+             if (!otp.isNullOrBlank()) {
+                 // Autofill the OTP in your input field
+             }
+         }
+         
+         ResponseTypes.VERIFY -> {
+             if (response.response?.optString("authType") == "SILENT_AUTH") {
+                 if (response.statusCode == 9106) {
+                     // Silent Authentication and all fallback methods failed
+                     // Handle graceful exit from authentication flow
+                 } else {
+                     // Silent Authentication failed
+                     // If SmartAuth is enabled, INITIATE response will include next available auth method
+                 }
+             } else {
+                 handleVerifyError(response)
+             }
+         }
+         
+         ResponseTypes.DELIVERY_STATUS -> {
+             val authType = response.response?.optString("authType")
+             val deliveryChannel = response.response?.optString("deliveryChannel")
+             // Update UI based on delivery channel (SMS, WhatsApp, etc.)
+         }
+         
+         ResponseTypes.FALLBACK_TRIGGERED -> {
+             val newDeliveryChannel = response.response?.optString("deliveryChannel")
+             // Update UI to show new delivery channel
+         }
+         
+         ResponseTypes.ONETAP -> {
+             val data = response.response?.optJSONObject("data")
+             val token = data?.optString("token")
+             if (!token.isNullOrBlank()) {
+                 // Process authentication token
+                 // Send to your backend for validation
+             }
+         }
+     }
+ }

​
Key Differences in Response Handling:

  1. Error Handling

    • Legacy SDK: Basic error message extraction
    • New SDK: Comprehensive error handling with specific error codes and messages

  2. Silent Authentication The new SDK adds support for Silent Authentication (SNA) with proper fallback handling:

    if (response.response?.optString("authType") == "SILENT_AUTH") {
    if (response.statusCode == 9106) {
        // All authentication methods failed
    } else {
        // Fallback to next authentication method
    }
}

  3. Delivery Status The new SDK provides detailed delivery status information:

    ResponseTypes.DELIVERY_STATUS -> {
    val authType = response.response?.optString("authType")
    val deliveryChannel = response.response?.optString("deliveryChannel")
}

​
Key Benefits of Migration

  1. Improved Performance: The new SDK is significantly faster and more efficient.
  2. Better Error Handling: More detailed error responses and improved error handling.
  3. Modern Kotlin Features: Utilizes Kotlin Coroutines for better concurrency.
  4. Improved Type Safety: Better type safety with enhanced Kotlin type system usage.

​
Need Help?

If you encounter any issues during migration, please reach out to our support team or refer to our documentation.

Was this page helpful?