Headless
Utilize our Headless SDK for ultimate flexibility. This guide provides detailed instructions on integrating custom UI elements with OTPLESS’s backend authentication functions.
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
:
Then, run:
Step 2: Platform-specific Integrations
- Add intent filter inside your
android/app/src/main/AndroidManifest.xml
file into your Main activity code block:
Replace YOUR_APP_ID
with your actual App
ID provided in
your OTPLESS dashboard.
- 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):
- Change your activity launchMode to singleTop and exported true for your Main Activity:
- Add intent filter inside your
android/app/src/main/AndroidManifest.xml
file into your Main activity code block:
Replace YOUR_APP_ID
with your actual App
ID provided in
your OTPLESS dashboard.
- 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):
- Change your activity launchMode to singleTop and exported true for your Main Activity:
- Go to your project’s root folder in the terminal and run.
- Add the following block to your
ios/Runner/info.plist
file:
Replace YOUR_APP_ID
with your actual App
ID provided in
your OTPLESS dashboard.
- Add the following block to your
ios/Runner/info.plist
file (Only required if you are using the SNA feature):
- Import the OTPLESS SDK in your respective
ios/Runner/AppDelegate.swift
file to handle redirection.
Step 3: Initialize the SDK
- Import the SDK in your
main.dart
file:
- Then, create an instance of the SDK:
- In your LoginScreen’s
initState
, initialize the SDK and set the response callback:
- Create a callback function to handle the response:
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.
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
.
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.
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
.
Email Authentication 📧
Email authentication verifies users using their email address. Merchants can choose from:
- OTP via Email – Sends a one-time password to the user’s email.
- Magic Link – Sends a clickable authentication link to the email.
- OTP + Magic Link – Provides both options for flexibility.
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
.
OAuth Authentication 🔑
OAuth allows users to authenticate using third-party services like Google, GitHub, or WhatsApp. Instead of entering credentials manually, users can log in using their existing accounts, streamlining the authentication process.
This is the list of channels you can use for OAuth login:
- APPLE
- GMAIL
- DISCORD
- SLACK
- MICROSOFT
- LINE
- LINEAR
- NOTION
- TWITCH
- GITHUB
- BITBUCKET
- ATLASSIAN
- GITLAB
Error Handling
The error codes for android and iOS have to be handled separately.
- Checkout android error codes
- Checkout iOS error codes
- To handle all the verification/initiation error codes for android and iOS, refer to the following code: