Links

Enrolment Flow

In order to use our SDK you need an authorization token. Please check our API "Authorisation" in this regard.
The Uqudo SDK provides a builder class to initiate the "Enrollment Flow". The example below assumes that you have already initialised the SDK:
Objective-C
UQBuilderController *builderController = [UQBuilderController defaultBuilder];
builderController.delegate = self;
builderController.appViewController = self;
//
UQEnrollmentBuilder *enrollmentBuilder = [[UQEnrollmentBuilder alloc] init];
enrollmentBuilder.authorizationToken = authorizationToken;
//
UQFacialRecognitionConfig *frConfig = [[UQFacialRecognitionConfig alloc] init];
frConfig.enableFacialRecognition = YES;
enrollmentBuilder.facialRecognitionConfig = frConfig;
//
UQDocumentConfig *documentConfig = [[UQDocumentConfig alloc] initWithDocumentType:PASSPORT];
//
UQReadingConfig *readingConfig = [[UQReadingConfig alloc] init];
readingConfig.enableReading = YES;
[readingConfig forceReadingIfSupported:YES];
documentConfig.reading = readingConfig;
//
[enrollmentBuilder add:documentConfig];
//
[builderController setEnrollment:enrollmentBuilder];
[builderController performEnrollment];
Swift
let uqudoBuilder = UQBuilderController.defaultBuilder()
uqudoBuilder.delegate = self
uqudoBuilder.appViewController = self
//
let enrollmentBuilder = UQEnrollmentBuilder()
enrollmentBuilder.authorizationToken = authorizationToken
//
let frConfig = UQFacialRecognitionConfig()
frConfig.enableFacialRecognition = true
enrollmentBuilder.facialRecognitionConfig = frConfig
//
let passport = UQDocumentConfig(documentType: PASSPORT.rawValue)
//
let readingConfig = UQReadingConfig()
readingConfig.enableReading = true
readingConfig.forceReadingIfSupported(true)
passport.reading = readingConfig
//
enrollmentBuilder.add(passport)
//
uqudoBuilder.setEnrollment(enrollmentBuilder)
uqudoBuilder.performEnrollment()

Uqudo Enrollment Builder Configuration

In order to check if the document type supports the "Lookup Flow" you can use the following method:
Objective-C
UQDocumentConfig *documentConfig = [[UQDocumentConfig alloc] initWithDocumentType:PASSPORT];
[documentConfig isEnrollmentSupported]
Swift
let documentConfig = UQDocumentConfig(documentType: PASSPORT)
document.isEnrollmentSupported()
Configuration options provided in the Uqudo Enrollment builder are:
Property
Type
Optional
Default
Description
authorizationToken
String
No
null
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
setUserIdentifier(uuid)
String
(UUID v4)
Yes
null
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
enableFacialRecognition
Boolean
Yes
false
Enable facial recognition. See Facial Recognition Configuration for additional configurations
enableBackgroundCheck(isDisableConsent, backgroundCheckType,
monitoring,
skipView)
Boolean, Integer,
Boolean,
Boolean
Yes
None
Enable background check. See Background Check Configuration for details
add(documentConfig)
UQDocumentConfig
No
None
Add document config object. See Document Configuration for details.
returnDataForIncompleteSession
Boolean
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 Session Status Handling). Please note that you can expect some data only if the user passes at least the scanning step
setAppearanceMode
AppearanceMode
No
SYSTEM
Set the appearance mode for the SDK. The following options are available:
  • SYSTEM: the SDK checks the OS setting for light or dark mode
  • LIGHT: force the light mode
  • DARK: force the dark mode
enableLookup()
None
Yes
None
Enable third party lookup (Government database). See the supported documents and the data returned in Lookup Object
Note: this feature requires an additional permission and must be explicitly requested
enableLookup(documentTypes)
Array of document types
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 in in Lookup Object
Note: this feature requires an additional permission and must be explicitly requested

Document Configuration

Objective-C
UQDocumentConfig *passport = [[UQDocumentConfig alloc] initWithDocumentType:PASSPORT];
passport.disableExpiryValidation = YES;
passport.enableAgeVerification = 18;
passport.scan = <Scan Config Object>;
passport.reading = <Reading Config Object>;
Swift
let passport = UQDocumentConfig(documentType: PASSPORT.rawValue)
passport.disableExpiryValidation = true
passport.enableAgeVerification = 18
passport.scan = <Scan Config Object>
passport.reading = <Reading Config Object>
See the options described below:
Property
Type
Optional
Default
Description
disableExpiryValidation
Boolean
Yes
false
Allows to scan expired documents
enableAgeVerification
Int
Yes
-1 (disabled)
Enable age verification. If the age calculated from the document is not above or equals the defined age, the scan fails showing a message to the user accordingly. Age must be above 0 otherwise is not taken into consideration
scan
UQScanConfig
Yes
None
Add scan configuration. See Scan Configuration for details
reading
UQReadingConfig
Yes
None
Add reading configuration. See Read Configuration for details

Scan Configuration

Objective-C
UQScanConfig *scanConfig = [[UQScanConfig alloc] init];
scanConfig.disableHelpPage = YES;
scanConfig.faceMinimumMatchLevel = 2;
[scanConfig enableScanReview:NO backSide:NO];
scanConfig.enableUpload = NO;
Swift
let scanConfig = UQScanConfig()
scanConfig.disableHelpPage = true
scanConfig.faceMinimumMatchLevel = 2
scanConfig.enableScanReview(false, false)
scanConfig.enableUpload = false
See the options described below:
Property
Type
Optional
Default
Description
disableHelpPage
Boolean
Yes
False
Disable scanning help page
faceMinimumMatchLevel
Integer
Yes
None
Defines the minimum match level that the facial recognition has to meet for scanned picture of this specific document
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
Boolean
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

Read Configuration

In order to check if the document type supports the reading step you can use the following method:
Objective-C
UQDocumentConfig *documentConfig = [[UQDocumentConfig alloc] initWithDocumentType:PASSPORT];
[documentConfig isSupportReading]
Swift
let documentConfig = UQDocumentConfig(documentType: PASSPORT)
document.isSupportReading()
Note: By default, the reading is disabled, and you have to explicitly enable the reading for the document in the UQReadingConfig object.
Note: We strongly recommend to mandate this step as described in Security & Best Practices
Objective-C
UQReadingConfig *readingConfig = [[UQReadingConfig alloc] init];
readingConfig.enableReading = YES;
readingConfig.faceMinimumMatchLevel = 3;
[readingConfig forceReading:NO];
[readingConfig forceReadingIfSupported:YES];
readConfig.forceReadingTimeout = -1;
Swift
let readingConfig = UQReadingConfig()
readingConfig.enableReading = true
readingConfig.faceMinimumMatchLevel = 3
readingConfig.forceReading(false)
readingConfig.forceReadingIfSupported(true)
readingConfig.forceReadingTimeout(-1)
See the options described below:
Property
Type
Optional
Default
Description
Property
Type
Optional
Default
Description
enableReading
Boolean
Yes
false
Enable reading for the document, e.g. NFC reading of the chip
faceMinimumMatchLevel
Integer
Yes
None
Defines the minimum match level that the facial recognition has to meet for the picture in the chip for this specific document
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 enrollment builder will throw and exception when you trigger SDK
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, after the Scan user will be moved to the next step.
forceReadingTimeout
Int
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. Note: This option is taken into consideration only if any of forceReading and forceReadingIfSupported is set to true

Facial Recognition Configuration

In order to check if the document type supports the reading step you can use the following method:
Objective-C
UQDocumentConfig *documentConfig = [[UQDocumentConfig alloc] initWithDocumentType:PASSPORT];
[documentConfig isSupportFaceRecognition]
Swift
let documentConfig = UQDocumentConfig(documentType: PASSPORT)
document.isSupportFaceRecognition()
Note: By default the facial recognition is disabled. You will have to enable facial recognition explicitly as per the below example:
Objective-C
UQFacialRecognitionConfig *config = [[UQFacialRecognitionConfig alloc] init];
config.enableFacialRecognition = YES;
config.enrollFace = NO;
config.scanMinimumMatchLevel = 2;
config.readMinimumMatchLevel = 3;
config.maxAttempts = 3;
config.allowClosedEyes = NO;
Swift
let config = UQFacialRecognitionConfig()
config.enableFacialRecognition = true
config.enrollFace = false
config.scanMinimumMatchLevel = 2
config.readMinimumMatchLevel = 3
config.maxAttempts = 3
config.allowClosedEyes = false
Facial Recognition configuration options available:
Property
Type
Optional
Default
Description
enrollFace
Boolean
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 Flow.
scanMinimumMatchLevel
Integer
Yes
None
Defines the minimum match level that the facial recognition has to meet for scanned pictures
readMinimumMatchLevel
Integer
Yes
None
Defines the minimum match level that the facial recognition has to meet for pictures from the chip (e.g. NFC)
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
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
bool
Yes
false
Allows to have closed eyes during facial recognition.

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:
Objective-C
[enrollmentBuilder enableBackgroundCheck:YES type:RDC monitoring:NO skipView:YES];
Swift
enrollmentBuilder.enableBackgroundCheck(true, type: RDC, monitoring: false, skipView: true)
Background Check configuration options available:
Property
Type
Optional
Default
Description
isDisableConsent
Boolean
No
false
Disable consent option for the user
backgroundCheckType
Integer
No
RDC
Sets the background check type
RDC
DOW_JONES
enableMonitoring
Boolean
Yes
false
Enable continuous monitoring. See API documentation for details
skipView
Boolean
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 the "Lookup 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
  2. 2.
    UnsupportedDeviceException - e.g. the device is rooted

Handling the Result

The enrollment result will be available to the builder delegate (the class that initiates the SDK has to extends UQBuilderControllerDelegate) if the operation succeeds and you get the result with the following method. See "SDK result" for the details about the JWS string:
Objective-C
- (void)didEnrollmentCompleteWithInfo:(NSString *)info {}
Swift
func didEnrollmentComplete(withInfo info: String) {}
A failure scenario can be handled with the following method:
Objective-C
- (void)didEnrollmentIncompleteWithStatus:(UQSessionStatus *)status {}
Swift
func didEnrollmentIncomplete(with status: UQSessionStatus) {}
See the details about the UQSessionStatus below.

Session Status Handling

The UQSessionStatus is used to identify the status of the enrollment task. The object contains the following properties:
@property (nonatomic, assign) NSInteger statusCode;
@property (nonatomic, assign) NSInteger statusTask;
@property (nonatomic, strong) NSString *message;
@property (nonatomic, strong) NSString *data;
statusCode contains the following error codes:
  • USER_CANCEL = User cancel the operation
  • SESSION_EXPIRED = Session expired or not found
  • UNEXPECTED_ERROR = Something went wrong. In the message the details of the error
  • SESSION_INVALIDATED_CHIP_VALIDATION_FAILED = Session gets invalidated because the CHIP validation of the card fails, and the reading step is forced by configuration
  • 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
  • SESSION_INVALIDATED_FACE_RECOGNITION_TOO_MANY_ATTEMPTS = Session gets invalidated because of too many failed facial recognition attempts
statusTask contains the following codes:
  • SCAN = The scanning task
  • READING = The NFC reading task
  • FACE = The facial recognition task
  • BACKGROUND_CHECK = The background check task (only if skipView() is not enabled)
message contains the details of the status code
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.
Last modified 1mo ago