NFC / Reading Flow

The "NFC/Reading Flow" is essentially the same as the "Enrollment Flow," with the only difference being the initial step. Instead of automatically scanning a document using the phone's camera, the process begins with the NFC/Reading step. To proceed, you must provide the necessary data to unlock the chip. Only one document can be processed at a time. Additional features, such as facial recognition and background checks, can be enabled just as they are in the "Enrollment Flow."

In order to use our SDK you need an authorization token. Please check our API "Authorisation" in this regard.

The following method should be called when the application is initiated:

UqudoSDK.init(applicationContext)

The Uqudo SDK provides a builder class to initiate the "NFC / Reading Flow". See the example below:

try {
   val uqudoIntent = UqudoBuilder.Reading()
            .setToken(token)
            .setDocumentType(DocumentType.UAE_ID)
            .enableFacialRecognition()
            .enableBackgroundCheck(
                BackgroundCheckConfigurationBuilder()
                    .skipView()
                    .build()
            )
            .setDocumentNumber("111111111")
            .setDateOfBirth("1980-08-25")
            .setDateOfExpiry("2022-03-06")
            .build(this)
        startActivityForResult(uqudoIntent, 101)
} catch( e: Exception ){
    ...
}

Reading Builder Configuration

Configuration options provided in the Uqudo Reading Builder are:

Property	Type	Optional	Default	Description
setToken(token)	String	No	null	See Authorisation
setNonce(nonce)	String (max size 64 chars)	Yes	null	Nonce provided by the customer mobile application when the SDK is initiated. It is useful to make sure the process has been initiated by the customer mobile application. It should be generated server side.
setSessionId(sessionId)	String (UUID v4)	Yes	Auto generated	Note: make sure to create always a new session id when you trigger the SDK flow
disableSecureWindow()	None	Yes	false	Whether to allow users to take screenshots and capture screen recording or not.
enableFacialRecognition()	None	Yes	None	Enable facial recognition with a default configuration, see Facial Recognition Configuration.
enableFacialRecognition(configuration)	FacialRecognitionSpecification	Yes	None	Enable facial recognition with a custom configuration, see Facial Recognition Configuration.
enableBackgroundCheck(configuration)	BackgroundCheckSpecification	Yes	None	Enable background check with a custom configuration, see Background Check Configuration.
setDocumentType(document)	Document	No	None	Set the document type. Please refer to the Scan API for supported Document Types.
returnDataForIncompleteSession()	None	Yes	false	When enabled, if the user or the SDK drops the session before completion, the SDK will return the partial data together with the SessionStatus object (see Handling the Result). Please note that you can expect some data only if the user passes at least the reading step
setDocumentNumber(documentNumber)	String	No	None	Set the document number used to unlock the chip
setDateOfBirth(dateOfBirth)	String	No	None	Set the date of birth used to unlock the chip. The format must be "yyyy-MM-dd"
setDateOfExpirty(dateOfExpiry)	String	No	None	Set the date of expirty used to unlock the chip. The format must be "yyyy-MM-dd"
setMRZ(mrz)	String	Yes	None	Set the MRZ. TD1 and TD3 MRZ type are supported. Every MRZ line must be separated by a new line char. If the MRZ is set, it takes priority and the other information are ignored.

Facial Recognition Configuration

By default the facial recognition is disabled. You need to enable Facial Recognition explicitly. See the example below:

...
        .enableFacialRecognition()

Facial Recognition configuration options available:

Property	Type	Optional	Default	Description
setMaxAttempts(maxAttempts)	Int	Yes	3	Set the max failed facial recognition attempts before dropping the session. Note: only values between 1 and 3 are taken into consideration.
allowClosedEyes()	None	Yes	False	Allows to have closed eyes during facial recognition.
enableOneToNVerification()	None	Yes	False	Once activated, following a successful facial recognition (confirming liveness and matching the face), the system initiates a search for the user's selfie within your tenant. If the selfie is not found, it is added, and the indexed facial features are stored in the database. The SDK result includes a unique ID in the face object, along with an indication of whether there was a match with a previously onboarded selfie. It's essential to store this unique ID in your system alongside the user's record, facilitating future searches for users with the same ID. Please be aware that this option requires a specific permission, otherwise, it will be disregarded
enableActiveLiveness(disableLivenessGesture)	LivenessGesture	Yes	Not enabled	Enable active liveness when performing facial recognition. There are three gestures: LivenessGesture.FACE_MOVE LivenessGesture.FACE_TILT LivenessGesture.FACE_TURN Every gesture has two actions associated resulting in a total of six possible actions (move closer, move further, tilt right, tilt left, turn right, turn left). During verification, the SDK will randomly prompt the user to perform one of these actions to continue. The configuration allows you to disable one gesture type, reducing the pool to four actions. Warning: We recommend enabling this feature only if required for regulatory or compliance purposes, as it may significantly impact user conversion rates.

Background Check Configuration

Note: This feature requires an additional permission and must be explicitly requested

By default the Background Check is disabled. You need to enable Background Check explicitly. See the example below:

...
        .enableBackgroundCheck(
             BackgroundCheckConfigurationBuilder()
               .skipView()
               .build()
         )

Background Check configuration options available:

Property	Type	Optional	Default	Description
disableConsent()	None	Yes	false	Disable consent option for the user
setBackgroundCheckType(type)	BackgroundCheckType	Yes	RDC	Sets the background check type
enableMonitoring()	None	Yes	false	Enable continuous monitoring
skipView()	None	Yes	false	If enabled, the step will be skipped, and the SDK will trigger the background check without any user interaction.

Handling Exceptions

The Uqudo SDK will throw certain exceptions which need to be handled by the application. The Exceptions are:

1. IllegalStateException - e.g. enabling the "NFC / Reading Flow" for a document that doesn’t support it or because facial recognition is enabled and the documcent doesn't support it or because of some required configuration missing

Handling the Result

The enrollment result will be available to the application in the calling Activity’s onActivityResult method:

...
override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
   super.onActivityResult(requestCode, resultCode, data)
   if (resultCode == Activity.RESULT_OK) {
       val result = data?.getStringExtra("data")
   } else if (resultCode == Activity.RESULT_CANCELED) {
       if (data != null) {
         val sessionStatus = data.getParcelableExtra("key_session_status") as SessionStatus
         println("Enrollment failed due to ${sessionStatus.sessionStatusCode.message} at ${sessionStatus.sessionTask.name()}")
       }
   }
}

If the resultCode is equals to Activity.RESULT_OK you can find the SDK result in the data attribute. The string is the JWS, see "SDK result" for details.

If the resultCode is equals to Activity.RESULT_CANCELED you can find the SessionStatus object result in the data attribute under the key “key_session_status”. The SessionStatus contains the following properties:

sessionStatusCode as SessionStatusCode enum that contains the following error codes:

1. USER_CANCEL = User canceled the enrollment process

2. SESSION_EXPIRED = Session expired or not found

3. UNEXPECTED_ERROR = Something went wrong. In the message the details of the error

4. SESSION_INVALIDATED_READING_INVALID_DOCUMENT = Session gets invalidated because the digital signature validation fails after reading the data in the chip

5. SESSION_INVALIDATED_CHIP_VALIDATION_FAILED = Session gets invalidated because chip authentication fails (e.g. chip authentication for passports)

6. SESSION_INVALIDATED_READING_AUTHENTICATION_FAILED = Session gets invalidated because the information provided to unlock the chip are incorrect

7. SESSION_INVALIDATED_FACE_RECOGNITION_TOO_MANY_ATTEMPTS = Session gets invalidated because of too many failed facial recognition attempts

8. SESSION_INVALIDATED_CAMERA_NOT_AVAILABLE = Session gets invalidated because the camera is not available

9. SESSION_INVALIDATED_CAMERA_PERMISSION_NOT_GRANTED = Session gets invalidated because the end user denied camera permission

sessionTask as SessionTask enum that contains the following codes:

1. READING = The NFC reading task

2. FACE = The facial recognition task

3. BACKGROUND_CHECK = The background check task (only if skipView() is not enabled)

data as String that contains the JWS object with the partial data of an incomplete KYC session. Returning the partial data for an incomplete KYC session is disabled by default, please see the related option in the Reading Builder Configuration for details.