Introduction

Requirements

The compileSdk version should be 35.
The minimum SDK version supported by the SDK is 21.
The kotlin version should be 1.9.0 and above.
The gradle version should be 8.3.1 and above.

We have launched a new SDK for Headless integration. Please consider migrating from the current SDK to the new SDK for more seamless integration and robust performance. Checkout the new SDK here. This SDK (legacy) will be deprecated and archived soon, we suggest migrating to the new SDK at the earliest.

Step 1: Add SDK Dependency

First, let’s add the OTPLESS SDK to your project. Update your app’s build.gradle file by adding the following dependency:

implementation 'io.github.otpless-tech:otpless-android-sdk:2.6.6'

Make sure to synchronize your Gradle project to fetch the dependency.

Step 2: Configure AndroidManifest.xml

Next, we’ll configure your AndroidManifest.xml to handle deep links. This setup is crucial for managing the authentication flow via Link. Add the following intent filter within the activity responsible for sign-up or sign-in:

<intent-filter>
  <action android:name="android.intent.action.VIEW" />
  <category android:name="android.intent.category.DEFAULT" />
  <category android:name="android.intent.category.BROWSABLE" />
  <data android:host="otpless" android:scheme="otpless.your_app_id_in_lowercase" />
</intent-filter>

Replace YOUR_APP_ID with your actual App ID provided in your OTPLESS dashboard.

Additionally, ensure your activity is set to singleTop launch mode and that the exported attribute is true:

android:launchMode="singleTop"
android:exported="true"

Great! Now let’s configure your activity for sign-up or sign-in. Below are the steps for both Java and Kotlin.

Java
Kotlin

First, import the necessary classes from the OTPLESS SDK:

import com.otpless.main.OtplessManager;
import com.otpless.main.OtplessView;
import com.otpless.dto.HeadlessRequest;
import com.otpless.dto.HeadlessResponse;
import com.otpless.dto.HeadlessChannelType;

Declare an OtplessView instance:

OtplessView otplessView;

Within your onCreate() method, initialize and set up the OTPLESS sign-in:

// Initialize OtplessView
otplessView = OtplessManager.getInstance().getOtplessView(this);
otplessView.initHeadless("YOUR_APP_ID");
otplessView.setHeadlessCallback(this::onHeadlessCallback);

Replace YOUR_APP_ID with your actual App ID provided in your OTPLESS dashboard.

Step 4: Handle Callback

Now, let’s implement a callback method to handle the response from the OTPLESS SDK:

private void onHeadlessCallback(@NonNull final HeadlessResponse response) {
    otplessView.commitHeadlessResponse(response);
    if (response.getStatusCode() == 200) {
        switch (response.getResponseType()) {
            case "INITIATE":
                // notify that headless authentication has been initiated
                break;
            case "VERIFY":
                // notify that verification is completed
                // and this is notified just before "ONETAP" final response
                break;
            case "OTP_AUTO_READ":
                final String otp = response.getResponse().optString("otp");
                break;
            case "ONETAP":
                // final response with token
                final JSONObject responseWithToken = response.getResponse();
                break;
            case "FALLBACK_TRIGGERED":
                // In case of Smart Auth when channel fallback triggered
                final JSONObject fallbackResponse = response.getResponse();
                break;
        }
        JSONObject successResponse = response.getResponse();
    } else if (response.getStatusCode() == 5002) {
        // handle network connectivity error
    } else if (response.getStatusCode() == 5050) {
        // failed to add webview, terminal case go to your login
    } else {
      // handle error
      String error = response.getResponse().optString("errorMessage");
    }
}

ResponseType	Description
INITIATE	When authentication is initiated.
VERIFY	When OTP is verified for an authentication and in case of link based authentication when user redirected back to the application after clicking the link.
ONETAP	This is the final response of an authentication session. It includes the token that should be sent to your backend for server-to-server validation.
OTP_AUTO_READ	When the OTP is automatically retrieved from SMS or WhatsApp. It includes OTP value in this responseType

Error Codes

StatusCode	ErrorMessage	Short Description
`401`	Unauthorized request! Please check your appId	Suggests missing or invalid app ID for authorization.
`500`	API_ERROR	Indicates a server-side error, possibly due to parameter issues.
`4000`	The request values are incorrect, see details.	Points to incorrect request values; refer to details for corrections.
`4001`	OTPless headless SDK doesn’t support 2FA as of now	Indicates the lack of 2FA support in the SDK.
`4002`	The request parameters are incorrect, see details.	Suggests parameter errors; check details for specifics.
`4003`	The request channel is incorrect, see details.	Notes an incorrect request channel; see details for correct usage.
`5002`	No internet connection is present.	Indicates no internet connection, troubleshoot network and device.

Override onNewIntent()Ensure you override the onNewIntent() method to correctly handle intent verification:

if (otplessView != null) {
  otplessView.onNewIntent(intent);
}

Override onBackPressed()Override the onBackPressed() method to manage back press actions properly:

// Make sure you call this code before super.onBackPressed();
if (otplessView.onBackPressed()) return;

First, import the necessary classes from the OTPLESS SDK:

import com.otpless.main.OtplessManager
import com.otpless.main.OtplessView
import com.otpless.dto.HeadlessRequest
import com.otpless.dto.HeadlessResponse
import com.otpless.dto.HeadlessChannelType

Declare an OtplessView instance:

private lateinit var otplessView: OtplessView

Within your onCreate() method, initialize and set up the OTPLESS sign-in:

// Initialize OtplessView
otplessView = OtplessManager.getInstance().getOtplessView(this)
otplessView.initHeadless("YOUR_APP_ID")
otplessView.setHeadlessCallback(this::onHeadlessCallback)

Replace YOUR_APP_ID with your actual App ID provided in your OTPLESS dashboard.

Step 4: Handle Callback

Now, let’s implement a callback method to handle the response from the OTPLESS SDK:

private fun onHeadlessCallback(response: HeadlessResponse) {
    otplessView.commitHeadlessResponse(response)
    if (response.getStatusCode() == 200) {
        when (response.getResponseType()) {
            "INITIATE" -> {
                // notify that headless authentication has been initiated
            }
            "VERIFY" -> {
                // notify that verification is completed
                // and this is notified just before "ONETAP" final response
            }
            "OTP_AUTO_READ" -> {
                val otp = response.getResponse().optString("otp")
            }
            "ONETAP" -> {
                // final response with token
                val responseWithToken = response.getResponse()
            }
            "FALLBACK_TRIGGERED" -> {
             // In case of Smart Authentication when channel fallback triggered
              val fallbackResponse = response.getResponse()
            }
        }
        val successResponse = response.getResponse()
    } else if (response.getStatusCode() == 5002) {
            // handle network connectivity error
    } else if (response.getStatusCode() == 5050) {
        // failed to add webview, terminal case go to your login
    } else {
        // handle error
        val error = response.getResponse().optString("errorMessage")
    }
}

ResponseType	Description
INITIATE	When authentication is initiated.
VERIFY	When OTP is verified for an authentication and in case of link based authentication when user redirected back to the application after clicking the link.
ONETAP	This is the final response of an authentication session. It includes the token that should be sent to your backend for server-to-server validation.
OTP_AUTO_READ	When the OTP is automatically retrieved from SMS or WhatsApp. It includes OTP value in this responseType

Error Codes

StatusCode	ErrorMessage	Short Description
`401`	Unauthorized request! Please check your appId	Suggests missing or invalid app ID for authorization.
`500`	API_ERROR	Indicates a server-side error, possibly due to parameter issues.
`4000`	The request values are incorrect, see details.	Points to incorrect request values; refer to details for corrections.
`4001`	OTPless headless SDK doesn’t support 2FA as of now	Indicates the lack of 2FA support in the SDK.
`4002`	The request parameters are incorrect, see details.	Suggests parameter errors; check details for specifics.
`4003`	The request channel is incorrect, see details.	Notes an incorrect request channel; see details for correct usage.
`5002`	No internet connection is present.	Indicates no internet connection, troubleshoot network and device.

Override onNewIntent()Ensure you override the onNewIntent() method to correctly handle intent verification:

if (otplessView != null) {
  otplessView.onNewIntent(intent)
}

Override onBackPressed()Override the onBackPressed() method to manage back press actions properly:

// Make sure you call this code before super.onBackPressed();
if (otplessView.onBackPressed()) return

Step 5: Initiate Authentication

Well done! You have completed the foundational setup of the SDK. Now, let’s move to the next step and understand how to initiate and verify different authentication modes. Choose the authentication mode you want to integrate from the options below:

OTP

Send a One-Time Password (OTP) via SMS, WhatsApp, or Email for secure user verification.

Magic Link

Provide a seamless login experience by sending an authentication link through SMS, WhatsApp, or Email.

Social Auth

Authenticate users through popular social applications like WhatsApp, Google, Apple, and GitHub.

Web SDKs

Native/Mobile SDKs

References

Requirements

Step 1: Add SDK Dependency

Step 2: Configure AndroidManifest.xml

Step 4: Handle Callback

Error Codes

Step 4: Handle Callback

Error Codes

Step 5: Initiate Authentication

OTP

Magic Link

Social Auth

Requirements

​Step 1: Add SDK Dependency

​Step 2: Configure AndroidManifest.xml

​Step 3: Configure Your Signup/Sign In Activity

​Step 4: Handle Callback

​Error Codes

​Step 4: Handle Callback

​Error Codes

​Step 5: Initiate Authentication

OTP

Magic Link

Social Auth

Step 1: Add SDK Dependency

Step 2: Configure AndroidManifest.xml

Step 3: Configure Your Signup/Sign In Activity

Step 4: Handle Callback

Error Codes

Step 4: Handle Callback

Error Codes

Step 5: Initiate Authentication