Links

Enrolment 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 "Enrollment Flow". See the example below:
try {
val authorizationToken = ... // access_token from the API response
val uqudoIntent = UqudoBuilder.Enrollment()
.setToken(authorizationToken)
.add(
DocumentBuilder(applicationContext)
.setDocumentType(DocumentType.PASSPORT)
.enableReading(ReadingConfigurationBuilder()
.forceReadingIfSupported(true)
.build()
)
.build()
)
.enableFacialRecognition()
.build(this)
startActivityForResult(uqudoIntent, 101)
} catch( e: Exception ){
...
}

Uqudo Enrollment Builder Configuration

In order to check if the document type supports the "Enrollment Flow" you can use the following method:
DocumentType.NGA_DL.enrollmentSupported
Configuration options provided in the Uqudo Enrolment builder are:
Property
Type
Optional
Default
Description
setToken(token)
String
No
null
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
Required during the enrolment process using a QR code, see QR code App.
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 the 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.
add(document)
Document
No
none
Add a document to the enrolment process, see Scan Configuration.
setUserIdentifier(uuid)
String (UUID v4)
Yes
none
UUID v4 that represents the user identifier for recurrent usage of the SDK for the same user. This is related to the type of license agreement with Uqudo. Please note that if the UUID v4 is malformed it is simply ignored
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 scanning step
enableLookup()
None
Yes
None
Enable third party lookup (Government database). See the supported documents and the data returned here Lookup object
Note: this feature requires an additional permission and must be explicitly requested
enableLookup(documentTypes)
Variable length argument or Array
Yes
None
Enable third party lookup (Government database) filtered by document type. For instance, if your KYC process includes more than one document, you can decide to perform the lookup only for one single document. See the supported documents and the data returned here Lookup object
Note: this feature requires an additional permission and must be explicitly requested

Scan Configuration

The scanning has some customisation options which can be set using the DocumentBuilder object like below:
DocumentBuilder(applicationContext)
.setDocumentType(documentType)
.disableHelpPage()
.enableReading()
.build()
Below you can find the configuration options available:
Property
Type
Optional
Default
Description
setDocumentType(ddocumentType)
DocumentType
No
None
Document type to scan
disableHelpPage()
None
Yes
false
Disable scanning help page
enableReading()
None
Yes
None
Enable reading for the document, e.g. NFC reading of the chip with default configuration, see Read Configuration.
enableReading(configuration)
ReadingSpecification
Yes
None
Enable reading for the document, e.g. NFC reading of the chip, passing a reading specification object (see below), see Read Configuration.
setFaceScanMinimumMatchLevel(matchLevel)
Int
Yes
None
Defines the minimum match level that the facial recognition has to meet for scanned pictures related to this document. This configuration takes precedence from the global setting in the facial recognition configuration
setFaceReadMinimumMatchLevel(matchLevel)
Int
Yes
None
Defines the minimum match level that the facial recognition has to meet for pictures from the chip (e.g. NFC) related to this document. This configuration takes precedence from the global setting in the facial recognition configuration
disableExpiryValidation()
None
Yes
false
Allows to scan expired documents
enableScanReview(frontSide, backSide)
Boolean, Boolean
Yes
Not enabled
Enable scan review of the document for the front side, back side or both. After scanning the detected document side is presented to the user for review and confirmation
enableUpload()
None
Yes
false
Enable manual upload of the document instead of automatic scanning. The user can choose a single PDF that contains the image of the document. For a two-side document the first picture must be the front side and the second picture the back side.
If enabled, the reading step is automatically disabled
enableAgeVerification(minAge)
Int
Yes
-1 (disabled)
Enable age verification. If the age calculated from the document is not above or equals minAge, the scan fails showing a message to the user accordingly. Min age must be above 0 otherwise is not taken into consideration

Read Configuration

In order to check if the document type supports the reading step (NFC) you can use the following method:
DocumentType.NGA_DL.readingSupported
Note: By default, the reading is disabled, and you have to explicitly enable reading for the document in the DocumentBuilder object.
Note: We strongly recommend to mandate this step as described in Security & Best Practices
In order to configure specific options for the reading part, see the example below:
....
DocumentBuilder(applicationContext)
.setDocumentType(documentType)
.enableReading(
ReadingConfigurationBuilder()
.forceReading(false)
.forceReadingIfSupported(false)
.build()
)
.build()
Reading configuration options available:
Property
Type
Optional
Default
Description
forceReading(value)
Boolean
Yes
false
Force the reading part. Users will not be able to skip the reading part. If the device does not support NFC and forceReading is set to true, the uqudo builder will throw and exception that needs to managed by the application
forceReadingIfSupported(value)
Boolean
Yes
false
Force the reading part only if NFC is supported. Users will not be able to skip the reading part if NFC is supported. Otherwise, the reading part is skipped and the user taken to the next step.
forceReadingTimeout(timeout)
Integer
Yes
-1 (disabled)
Defines the timeout in seconds. If the user isn't able to perform the NFC scanning of the document before the timeout expires, a message is shown accordingly and the user is allowed to skip the NFC step. N.B.: This option is taken into consideration only if any of forceReading and forceReadingIfSupported is set to true
You can also control the app for devices with NFC or not by turning the feature required as true or false in AndroidManifest.xml. By doing so, the app will only be available to devices with NFC if set true
<uses-feature
android:name="android.hardware.nfc"
android:required="true"
tools:node="replace" />

Facial Recognition Configuration

In order to check if the document type supports facial recognition you can use the following method:
DocumentType.NGA_DL.facialRecognitionSupported
Note: By default the facial recognition is disabled. You need to enable Facial Recognition explicitly. See the example below:
...
.enableFacialRecognition(
FacialRecognitionConfigurationBuilder()
.enrollFace()
.setFaceReadMinimumMatchLevel(3)
.setFaceScanMinimumMatchLevel(2)
.build()
)
The above example shows how you can disable the help page on the facial recognition part.
Facial Recognition configuration options available:
Property
Type
Optional
Default
Description
enrollFace()
None
Yes
false
Setting this true, will let you enrol the face so that it can be used for account recovery. More details can be found in Account Recovery
setScanMinimumMatchLevel(matchLevel)
Int
Yes
None
Defines the minimum match level that the facial recognition has to meet for scanned pictures
setReadMinimumMatchLevel(matchLevel)
Int
Yes
None
Defines the minimum match level that the facial recognition has to meet for pictures from the chip (e.g. NFC)
enableAuditTrailImageObfuscation(obfuscationType)
ObfuscationType
Yes
None
Enables audit trail image background obfuscation leaving only the face visible. It can be used when there are privacy concerns related to the background of the selfie taken by the user and shared in the SDK result. There are two types of obfuscations:
  • FILLED: the background is entirely replaced
  • BLURRED: the background is heavily blurred, making sure the objects in the background are not clearly recognizable, but still giving a perception of the environment surrounding the user and therefore still being able to validate the reality of the image. If privacy is a concern, we recommend using this option
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.

Background Check Configuration

Note: This feature requires an additional permission and must be explicitly requested
Note: 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
RDC
enableMonitoring()
None
Yes
false
Enable continuous monitoring. See API documentation for details.
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. 1.
    IllegalStateException - e.g. enabling reading for a document that doesn’t support reading or required configuration missing
  2. 2.
    UnsupportedDeviceException - e.g. on DocumentBuilder().build() if force reading is enabled and the device doesn’t support NFC or on UqudoBuilder.Enrollment().build() if rooted device is not allowed and the device is rooted

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. 1.
    USER_CANCELLED = User canceled the enrollment process
  2. 2.
    SESSION_EXPIRED = Session expired or not found
  3. 3.
    UNEXPECTED_ERROR = Something went wrong. In the message the details of the error
  4. 4.
    SESSION_INVALIDATED_CHIP_VALIDATION_FAILED = Session gets invalidated because the CHIP validation of the card fails and the reading step is forced by configuration
  5. 5.
    SESSION_INVALIDATED_READING_NOT_SUPPORTED = Session gets invalidated because the document doesn’t support reading (e.g. no chip available) and the reading step is forced by configuration
  6. 6.
    SESSION_INVALIDATED_FACE_RECOGNITION_TOO_MANY_ATTEMPTS = Session gets invalidated because of too many failed facial recognition attempts
sessionTask as SessionTask enum that contains the following codes:
  1. 1.
    SCAN = The scanning task
  2. 2.
    READING = The NFC reading task
  3. 3.
    FACE = The facial recognition task
  4. 4.
    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 Enrollment Builder Configuration for details.