Android UIDAI/Digilocker SDK
Aadhaar SDK provides the user to verify Aadhaar status and get relevant information from UIDAI.
Find steps below to integrate the Application SDK
- Aadhaar SDK has to be integrated with mobile application.
- In the integration UserId and CredentialId are mandatory fields for integration. CredentialId is unique and provided by Bureau.
- UserId is a unique id that is generated per user and can be either the phone number/email/UUID etc that is used to represent every unique user.
Aadhaar Flow
- User is guided to the UIDAI website to download the paperless e-KYC (Aadhaar .xml) Inputs for "Aadhaar Number" & Captcha are filled by the end user. Both the details will be validated by UIDAI on the screen and in case of validation error the message will be displayed accordingly on the screen.
- On continuing, An OTP is received by the end user which is then auto read by the SDK.
- Once the details entered are authenticated, the Aadhaar .xml is downloaded in a .zip which is password(share code) protected
Minimum Requirements
- minSdkVersion 21
- AndroidX
Integrations Guide
Add following lines in your root build.gradle
allprojects {
repositories {
...
maven { url "https://jitpack.io" }
}
}
Add following lines in your module level build.gradle
android {
...
compileOptions {
sourceCompatibility = 1.8
targetCompatibility = 1.8
}
}
dependencies {
....
implementation 'com.github.Bureau-Inc:android-aadhaar-all-in-one-sdk:1.0.0'
}
SDK Change log https://docs.bureau.id/page/uidai-android-sdk-changelog
Latest version - 0.72.0
Initialise SDK
PrismEntryPoint prism;
yourinitbutton.setOnClickListener(new View.OnClickListener() {
@Override
public void onClick(View v) {
//instantiate your prism
prism = PrismInstanceProvider.getInstance(context,activity);
//Initialize your prism only once
prism.initialize(your credentialId,your user id,
new PrismCallBack(){
override fun onKYCFinished(
aadhaarData: ClientAadhaarData?,
methodName: String?,
isSuccess: Boolean?, errorType: String
) {
//log your aadhaar data or error type
}
override fun eventCalled(eventName: String) {
//log your event here
}
override fun onTryAgainShown(
numberOfRetriesLeft: Int,
retryCallback: RetryCallback
) {
retryCallback.onStopSDK() //To stop SDK(Note: You need only call beginkycflow again and not initialize)
//or
retryCallback.onContinue()//To continue show the sdk try again error screen
}
}
,a boolean to indicate whether flow should be run on production configuration,an integer to indicate number of retries for try again screen,PrismCustomisation.Builder().build());
//You can Add customisation to SDK's UI by adding values to PrismCustomisation Builder
//Adding config to specify the new Aadhaar Flow
prism.addConfig(new Config(myAadhaarUidaiFlow));
//KYC initiate call
prism.beginKYCFLowWithOfflineKYC(BOOLEAN_TO_INDICATE_AUTH_HISTORY_CHECK,AUTH_HISTORY_START_DATE,AUTH_HISTORY_END_DATE,AUTH_HISTORY_TRANSACTIO_LIMIT) //For Offline KYC
prism.beginKYCFLowWithDigilocker(SUCCESS_URL, FAILURE_URL) //For Digilocker
}
});
In your fragment's/activity's onDestroy function, call
prims.resetPrismSDKConfig()
To set number of retries and custom error messages.
var errorMap = HashMap<String,String>(
errorMap.put(ERROR_MESSAGE_FOR_OTP_GENERATION,"Your custom error")
errorMap.put(ERROR_MESSAGE_FOR_OTP_SUBMISSION,"Your custom error")
prism.initialize(
merchantId,
userId,
object : PrismCallBack {
override fun onKYCFinished(
aadhaarData: ClientAadhaarData?,
methodName: String?,
isSuccess: Boolean?, errorType: String
) {
}
override fun eventCalled(eventName: String) {
}
},
isProduction,//Boolean to indicate if SDK is to be used in production
prismCustomisation = PrismCustomisation.Builder().toolBarTitle("YOUR_TITLE").hideToolbar(false).setLogoDrawable(R.drawable.your_logo).mainPageTitle("<Your Aadhaar Entry title>").otpPageTitle("<Your OTP Title>").build(),
numberOfRetries = n,errorMap )//n is an integer to indicate the number of retries, if this is not required this can be set to 0
Notes
- Please call the above function only on onDestroy of the fragment where instanceProvider and initialize has been called.
- This call is optional and forces sdk cache to clear. Call only when retention of old sdk config is maintained.
- Once the call is invoked it clears all config so make sure you call instanceProvider and initialize again when starting a new flow.
- prism.beginKYCFlow can be called multiple times in between initialize and resetPrismSDKConfig
Callback
When Aadhaar fetch is successful the callback returns the isSuccess boolean as true and when a failure happens the callback returns the isSuccess boolean as false.
new PrismCallBack(){
@Override
public void onKYCFinished(ClientAadhaarData aadhaarData, String methodName, Boolean isSuccess,String errorType) {
if(isSuccess)
{
//Write your success logic here
//the object aadhaar data contains the details
//errorType will be empty here
Log.d("Aadhaar Data", aadhaarData.getJsonString.ToString());
Log.d("XML File Uri", aadhaarData.getXmlFileUri().toString());
Log.d("Aadhaar Data", aadhaarData.getZipFileUri().toString());
Log.d("Aadhaar Data", aadhaarData.getShareCode.toString());
}
else
{ //Check errorType here
if(errorType== ENDPOINTS_DOWN)
Log.w("Aadhaar Error","No endpoints Available")
else if(errorType== INVOID_AUTH_ERROR)
Log.w("Aadhaar Error","Not authorized")
else if(errorType== UIDAI_ERROR)
Log.w("Aadhaar Error","UIDAI Site Error")
else if(errorType== INTERNET_ERROR)
Log.w("Aadhaar Error","Intenet Error")
else if(errorType== SDK_ERROR)
Log.w("Aadhaar Error","SDK Error")
else if(errorType== USER_CANCELLED)
Log.w("Aadhaar Error","Cancelled by user")
//Write your failure logic here
//You can retry the method by calling beginKYCFlow() again as shown below
prism.beginKYCFLow();
}
}
}
Notes
- UserId and MerchantId are mandatory fields and should not be empty. UserId is a unique string that represents each unique user trying the flow.
- UserTracking
UserId can be used to call Bureau backend API to fetch data regarding user. It should be unique string in nature. For each KYC flow the userId should be uniquely generated. It can be mobile number or any email associated to a user also. - If the BOOLEAN_TO_INDICATE_AUTH_HISTORY_CHECK is set as 'true' the trailing parameters becomes mandatory if not those are optional add the following to last of the initialize function after error maps. AN_OPTIONAL_BOOLEAN_TO_ENABLE_BUREAU'S_HEALTH_CHECK default is false.
- Response returned from the SDK
- xml file uri
- zip file uri
- share code to open zip file
- processedJSON
- The PrismCallBack added in the initialize function return's whether we have successfully fetched details or not
SDK Callbacks
These are event callbacks that can be used to get user details.
| Description | SDK Code |
|---|---|
| AADHAAR_ENTRY_SCREEN | Aadhaar Entry Screen |
| OTP_ENTRY_SCREEN | OTP Entry Screen |
| PROGRESS_SCREEN | Loading Screen |
| WARNING_SCREEN | Try Again Screen |
| SUCCESS_SCREEN | Success Screen |
SDK Errors
| SDK Code | Description |
|---|---|
| UIDAI_ERROR | UIDAI services are down |
| INVOID_AUTH_ERROR | Not authorised |
| INTERNET_ERROR | Network error |
| USER_CANCELLED | User cancelled |
| SDK_ERROR | Bureau SDK error |
| ENDPOINTS_DOWN | All endpoints are down |
| MOBILE_NOT_LINKED | Aadhaar number does not have mobile number |
| FORCE_STOP_FROM_PARENT_APP | The sdk process has been terminated by the parent app |
| UIDAI_VERIFICATION_FAILED | Failure in obtaining XML file after successful submission of the OTP |
Serverside Base URL's
- Sandbox - https://api.sandbox.bureau.id/v1/
- Production - https://api.bureau.id/v1/
Server side code to get the details
curl --location --request GET 'https://api.sandbox.bureau.id/v1/id/<UserId>/suppliers/offline-aadhaar' \
--header 'Authorization: Basic AuthHeader'
curl --location --request GET 'https://api.bureau.id/v1/id/<UserId>/suppliers/offline-aadhaar' \
--header 'Authorization: Basic AuthHeader'
Response
{
"aadhaarXMLUrl": "https://xxx-prd-mb-xxx-documents-/91feeafe-1111-1111-1111-8e9fe0400920.xml?",
"city": "User City",
"district": "User District",
"dob": "DD-MM-YYYY",
"gender": "M",
"merchantId": "auth0|61d11111114e7021",
"name": "User Name",
"pincode": "pin code",
"requestId": "57e7b43d-1111-4e4c-1111-a096e7400a5f",
"state": "Karnataka",
"statusCode": 200,
"street": "addresss",
"timestamp": 1674201457708
}
{
"errors": {
"code": 400,
"description": "Request contains an invalid param in request body which does not exist",
"message": "BAD_REQUEST",
"metadata": " ",
"referenceId": "b090f2a1-ebf4-4fdc-bcdc-296cfc7e4ea1",
"type": "BAD_REQUEST"
},
"merchantId": "auth0|61df1111107111021",
"requestId": "d46ff15d-1111-4568-1111-b21bbdd3962f",
"statusCode": 400,
"timestamp": 1657794502770
}
{
"errors": {
"code": 422,
"description": " ",
"message": "NO_RECORD_FOUND",
"metadata": " ",
"referenceId": "b090f2a1-ebf4-4fdc-bcdc-296cfc7e4ea1",
"type": "NO_RECORD_FOUND"
},
"merchantId": "auth0|61df1111107111021",
"requestId": "d46ff15d-1111-4568-1111-b21bbdd3962f",
"statusCode": 422,
"timestamp": 1657794502770
}
{
"errors": {
"code": 503,
"description": " ",a
"message": "INTERNAL_SERVICE_UNAVAILABLE",
"metadata": " ",
"referenceId": "b090f2a1-ebf4-4fdc-bcdc-296cfc7e4ea1",
"type": ""
},
"merchantId": "auth0|61df1111107111021",
"requestId": "d46ff15d-1111-4568-1111-b21bbdd3962f",
"statusCode": 503,
"timestamp": 1657794502770
}
SDK Customisations
To customise the theme of the activity use the following theme in your styles.xml file.
Error message show to the user can be customised by defining following strings in your strings.xml file
<style name="PrismAppTheme">
...
<!--Add Theme Customisation here-->
</style>
<!--To add customisation to toolbar in SDK's activity add the following style-->
<style name="PrismToolbarTheme" parent="ThemeOverlay.AppCompat.Dark.ActionBar" >
<item name="android:background">@drawable/invoid_button_bg</item>
</style>
<!--To add customisation to buttons in SDK add the following style-->
<style name="PrismButtonTheme" parent="@android:style/Widget.Button">
<item name="android:textColor">@android:color/white</item>
<item name="android:shadowColor">#FF000000</item>
<item name="android:shadowDx">0</item>
<item name="android:shadowDy">-1</item>
<item name="android:shadowRadius">0.2</item>
<item name="android:background">@color/black</item>
<item name="android:textSize">14sp</item>
<item name="android:textStyle">bold</item>
</style>
Error message show to the user can be customized by defining following strings in your strings.xml file
<!--Error message shown in case of OfflineAadhaarHelper.UIDAI_ERROR-->
<string name="invoid_uidai_error">Server down, please try after some time</string>
<!--Error message shown in case of OfflineAadhaarHelper.INVOID_AUTH_ERROR-->
<string name="invoid_auth_error">Not authorized</string>
<!--Error message shown in case of OfflineAadhaarHelper.INTERNET_ERROR-->
<string name="invoid_check_internet_error">Please check your internet connection</string>
Code Customisations
PrismCustomisation.Builder().toolBarTitle("YOUR_TITLE").hideToolbar(false).setLogoDrawable(R.drawable.your_logo).mainPageTitle("<Your Aadhaar Entry title>").otpPageTitle("<Your OTP Title>").build()
To customise the color of the button of the SDK UI override the following color in your colors.xml file.
<color name="bureau_button_bg">#FFCA20</color>
Updated about 2 months ago