This is the new Headless authentication SDK that is significantly faster and more robust than the previous version. This upgrade enhances performance, reliability, and security, ensuring a seamless authentication experience, along with a seamless integration process. We strongly recommend migrating to the new SDK for improved efficiency and better support. To migrate from the old SDK, remove the previous SDK dependency and integration and follow the below mentioned steps.

​
Step 1: Installation

Add the following to your pubspec.yaml:

dependencies:
  otpless_headless_flutter: ^<latest_version>

Then, run:

flutter pub get
Please find the latest version of the SDK here.

​
Step 2: Platform-specific Integrations

  1. Add intent filter inside your android/app/src/main/AndroidManifest.xml file into your Main activity code block:
<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_LOWERCASE"/>
</intent-filter>

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

  1. Add Network Security Config inside your android/app/src/main/AndroidManifest.xml file into your <application> code block (Only required if you are using the SNA feature):
android:networkSecurityConfig="@xml/otpless_network_security_config"
  1. Change your activity launchMode to singleTop and exported true for your Main Activity:
android:launchMode="singleTop"
android:exported="true"

​
Step 3: Initialize the SDK

  1. Import the SDK in your main.dart file:
import 'package:otpless_headless_flutter/otpless_flutter.dart';
  1. Then, create an instance of the SDK:
final _otplessHeadlessPlugin = Otpless();
  1. In your LoginScreen’s initState, initialize the SDK and set the response callback:
LoginScreen
@override
void initState() {
  super.initState();
  _otplessHeadlessPlugin.initialize("YOUR_APP_ID");
  _otplessHeadlessPlugin.setResponseCallback(onOtplessResponse);
}
  1. Create a callback function to handle the response:
LoginScreen
void onOtplessResponse(dynamic result) {
  _otplessHeadlessPlugin.commitResponse(result);

  final responseType = result['responseType'];

  switch (responseType) {
    case "SDK_READY":
      debugPrint("SDK is ready");
      break;

    case "FAILED":
      debugPrint("SDK initialization failed");
      // Handle SDK initialization failure
      break;

    case "INITIATE":
      if (result["statusCode"] == 200) {
        debugPrint("Headless authentication initiated");
        final authType = result["response"]["authType"]; // This is the authentication type
        if (authType == "OTP") {
         // Take user to OTP verification screen
        } else if (authType == "SILENT_AUTH") {
          // Handle Silent Authentication initiation by showing 
          // loading status for SNA flow.
        }
      } else {
        // Handle initiation error. 
        // To handle initiation error response, please refer to the error handling section.
        if (Platform.isAndroid) {
          handleInitiateErrorAndroid(result["response"]);
        } else if (Platform.isIOS) {  
          handleInitiateErrorIOS(result["response"]);
        }
      }
      break;

    case "OTP_AUTO_READ":
      // OTP_AUTO_READ is triggered only in ANDROID devices for WhatsApp and SMS.
        final otp = result["response"]["otp"];
        debugPrint("OTP Received: $otp");
      break;

    case "VERIFY":
      final authType = result["response"]["authType"];
      if (authType == "SILENT_AUTH") {
        if (result["statusCode"] == 9106) {
            // Silent Authentication and all fallback authentication methods in SmartAuth have failed.
            //  The transaction cannot proceed further. 
            // Handle the scenario to gracefully exit the authentication flow 
        } else {
            // Silent Authentication failed. 
            // If SmartAuth is enabled, the INITIATE response 
            // will include the next available authentication method configured in the dashboard.
        }
      } else {
        // To handle verification failed response, please refer to the error handling section.
        if (Platform.isAndroid) {
          handleVerifyErrorAndroid(result["response"]);
        } else if (Platform.isIOS) {  
          handleVerifyErrorIOS(result["response"]);
        }
      }
      break;

    case "DELIVERY_STATUS":
        // This function is called when delivery is successful for your authType.
        final authType = result["response"]["authType"];
        // It is the authentication type (OTP, MAGICLINK, OTP_LINK) for which the delivery status is being sent
        final deliveryChannel = result["response"]["deliveryChannel"];
        // It is the delivery channel (SMS, WHATSAPP, etc) on which the authType has been delivered
        break;

    case "ONETAP":
      final token = result["response"]["token"];
      if (token != null) {
        debugPrint("OneTap Data: $token");
        // Process token and proceed
      }
      break;

    case "FALLBACK_TRIGGERED":
        // A fallback occurs when an OTP delivery attempt on one channel fails,  
        // and the system automatically retries via the subsequent channel selected on Otpless Dashboard.  
        // For example, if a merchant opts for SmartAuth with primary channal as WhatsApp and secondary channel as SMS,
        // in that case, if OTP delivery on WhatsApp fails, the system will automatically retry via SMS.
        // The response will contain the deliveryChannel to which the OTP has been sent.
        final newDeliveryChannel = result["response"]["deliveryChannel"];
        if (newDeliveryChannel != null) {
            // This is the deliveryChannel to which the OTP has been sent
        }
      break;

    default:
      debugPrint("Unknown response type: $responseType");
      break;
  }

}

​
Step 4: Initiate Authentication

Initiate the authentication process based on the user’s selected method.

Phone authentication allows users to verify their identity using their phone number. Merchants can choose from various authentication methods:

  • Silent Authentication (SNA) – Automatically verifies the user without requiring OTP or MAGICLINK.
  • OTP on Desired Channel – Sends a one-time password (OTP) via SMS, WhatsApp, or another preferred channel.
  • Magic Link – Sends a link that users can click to authenticate.
  • SNA + OTP – Uses silent authentication first and falls back to OTP if needed.
  • OTP + Magic Link – Sends both an OTP and a magic link, allowing users to authenticate via either method.
void startWithPhone(String phoneNumber) {
    final Map<String, dynamic> args = {
        "phone": "phoneNumber",
        "countryCode": "countryCode",
    };
    _otplessHeadlessPlugin.start(onOtplessResponse, args);
}

​
Verify OTP

To verify the OTP entered by the user, use the verify method with the necessary parameters. Verifying OTP is required only in case of OTP authentication. No need to verify OTP in case of MAGICLINK.

void verifyPhoneOtp(String phoneNumber, String otp) {
    final Map<String, dynamic> args = {
        "phone": "phoneNumber",
        "countryCode": "countryCode",
        "otp": "otp",
    };
    _otplessHeadlessPlugin.start(onOtplessResponse, args);
}

​
Error Handling

The error codes for android and iOS have to be handled separately.

void handleInitiateErrorAndroid(dynamic response) {
  final String? errorCode = response?['errorCode'];
  final String? errorMessage = response?['errorMessage'];

  if (errorCode == null) {
    debugPrint("OTPless Error: Unknown error - $errorMessage");
    return;
  }

  switch (errorCode) {
    case "7101":
      debugPrint("OTPless Error: Invalid parameters values or missing parameters - $errorMessage");
      break;
    case "7102":
      debugPrint("OTPless Error: Invalid phone number - $errorMessage");
      break;
    case "7103":
      debugPrint("OTPless Error: Invalid phone number delivery channel - $errorMessage");
      break;
    case "7104":
      debugPrint("OTPless Error: Invalid email - $errorMessage");
      break;
    case "7105":
      debugPrint("OTPless Error: Invalid email channel - $errorMessage");
      break;
    case "7106":
      debugPrint("OTPless Error: Invalid phone number or email - $errorMessage");
      break;
    case "7113":
      debugPrint("OTPless Error: Invalid expiry - $errorMessage");
      break;
    case "7116":
      debugPrint("OTPless Error: OTP Length is invalid (4 or 6 only allowed) - $errorMessage");
      break;
    case "7121":
      debugPrint("OTPless Error: Invalid app hash - $errorMessage");
      break;
    case "4000":
      debugPrint("OTPless Error: Invalid request values - $errorMessage");
      break;
    case "4001":
      debugPrint("OTPless Error: Unsupported 2FA request - $errorMessage");
      break;
    case "4003":
      debugPrint("OTPless Error: Incorrect request channel - $errorMessage");
      break;
    case "401":
    case "7025":
      debugPrint("OTPless Error: Unauthorized request or country not enabled - $errorMessage");
      break;
    case "7020":
    case "7022":
    case "7023":
    case "7024":
      debugPrint("OTPless Error: Too many requests (rate limiting) - $errorMessage");
      break;
    case "9100":
    case "9104":
    case "9103":
      debugPrint("OTPless Error: Network connectivity error - $errorMessage");
      break;
    default:
      debugPrint("OTPless Error: Unknown error - $errorMessage");
  }
}

Validate Token

Learn how to securely `validate token` returned by OTPLESS flutter SDK to ensure the authenticity of sign-in events from your backend server.