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
-
Package Name Change
- Legacy:
io.github.otpless-tech:otpless-android-sdk
- New:
io.github.otpless-tech:otpless-headless-sdk
-
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:
-
Error Handling
- Legacy SDK: Basic error message extraction
- New SDK: Comprehensive error handling with specific error codes and messages
-
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
}
}
-
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
- Improved Performance: The new SDK is significantly faster and more efficient.
- Better Error Handling: More detailed error responses and improved error handling.
- Modern Kotlin Features: Utilizes Kotlin Coroutines for better concurrency.
- 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.
