Document Capture - SelphID
This component requires a minimum iOS 9 version
Introduction
This component is responsible for the capture and analysis of identity documents, allowing structured information to be extracted and processed images of the document to be obtained.
Its main features are:
Internal camera and permissions management.
Guided assistance for capturing the front and back of the document.
Automatic data extraction using OCR.
Obtaining processed images of the document and associated elements (face, signature, etc.).
High level of configuration: countries, languages, types and document models.
For a basic SDK integration, see the section Simplified Launch. This page details the specific information for using this component.
Dependencies
To avoid conflicts and compatibility issues, if the project contains old versions of Facephi libraries (Widgets), these must be removed completely before installing the components of SDK Mobile.
CocoaPods
Facephi libraries are distributed remotely through dependency managers. The dependencies mandatory dependencies that must have been installed previously (by adding them to the project's Podfile) are:
pod 'FPHISDKMainComponent', '~> $VERSION'To install the component SelphID, add the corresponding dependency in the
Podfileof the project.
Swift Package Manager (SPM)
If you use SPM, make sure the SDK's mandatory dependencies are already installed.
To install the component SelphID, include it in the project's modules.
Permissions
In the client application where the components will be integrated, it is necessary to include the following element in the file Info.plist:
Available controllers
Controller
Description
SelphIDController
Main document recognition controller
Simplified Launch
Once the SDK has been initialized and a new operation created, the component can be launched using any of its available controllers, depending on the required functionality.
Result reception
The launch result is returned in an object SdkResult, which contains:
selphIDResult.finishStatusselphIDResult.errorTypeselphIDResult.data
Receiving errors
finishStatus: Indicates whether the operation completed successfully. Possible values:
errorType: Widget-specific errors.
On iOS, errorType it is an ErrorType from the SDK. In a timeout, the Swift enum can be .SDK_TIMEOUT, .SELPHID_TIMEOUT(UIImage?, UIImage?) or, if interpolated directly, show names like SDK_TIMEOUT or SELPHID_TIMEOUT. On iOS there is no TIMEOUT case without a prefix.
To serialize the error, use:
This returns SPD_TIMEOUT whether the enum is SDK_TIMEOUT as SELPHID_TIMEOUT.
Timeout behavior
In a timeout, the result has:
finishStatus:STATUS_ERRORdata:nil(aSelphIDResult)errorType:.SDK_TIMEOUTor.SELPHID_TIMEOUT(UIImage?, UIImage?)
The case SELPHID_TIMEOUT keeps, when available, the raw document images captured before the timeout (rawFrontDocument and rawBackDocument of the widget). That information does not form part of data is neither returned as rawFrontDocument / rawBackDocument of the success result; it can only be read on iOS by means of pattern matching on errorType:
If the timeout arrives as SDK_TIMEOUT, does not include raw images. If it arrives as SELPHID_TIMEOUT, the associated images may be nil when the timeout occurs through the widget's error path (FWMETimeout) instead of the delegate captureTimeout().
For native iOS integrations, the serialized value should be treated as SPD_TIMEOUT (includes both SDK_TIMEOUT as SELPHID_TIMEOUT of the enum).
On iOS, properties such as timeoutDiagnostic or captureProgress does not are included in the SdkResult error object. The component uses captureProgress internally to display the diagnostic screen message when showDiagnostic is active.
If showDiagnostic is enabled, the callback output is not invoked at the moment of the timeout: the diagnostic screen is shown first and the result is delivered when Close is pressed. With showDiagnostic disabled, the callback runs immediately.
The following list includes errors from the cross-platform contract; some do not occur on iOS (for example, SPD_MOVE_FAIL).
SPD_APPLICATION_CONTEXT_ERROR: The required application context is null.
SPD_BAD_EXTRACTOR_CONFIGURATION_ERROR: Widget: Incorrect extractor configuration
SPD_CAMERA_PERMISSION_DENIED: The user has denied the permissions.
SPD_CANCEL_BY_USER: The user has canceled the process.
SPD_CANCEL_LAUNCH: A general SDK cancellation has been performed.
SPD_COMPONENT_LICENSE_ERROR: The component license is not correct.
SPD_CONTROL_NOT_INITIALIZATED_ERROR: Widget: Initialization error
SPD_EMPTY_LICENSE: The license String is empty.
SPD_EXTRACTION_LICENSE_ERROR: Widget: License error
SPD_HARDWARE_ERROR: Widget: Hardware error
SPD_INITIALIZATION_ERROR: Initialization error.
SPD_MOVE_FAIL: The user has not moved as specified in the process.
SPD_NO_DATA_ERROR: The input data is null.
SPD_OPERATION_NOT_CREATED: There is no operation in progress.
SPD_RESOURCES_NOT_FOUND: The resources zip was not found
SPD_SETTINGS_PERMISSION_ERROR: Widget: Permissions error
SPD_TIMEOUT: Timeout in the process (
SDK_TIMEOUTorSELPHID_TIMEOUTof the enum).SPD_UNEXPECTED_CAPTURE_ERROR: Widget: Capture error
SPD_UNKNOWN_ERROR: Unknown error
SPD_WIDGET_RESULT_DATA_ERROR: Error in the widget's output data
Receiving successful execution - data
The content of the field data depends on the component. In the case of SelphID, the following fields are returned:
frontDocument / tokenFrontDocument
The processed, cleaned, and edge-cropped front image of the document and its corresponding token.
backDocument / tokenBackDocument
The processed, cleaned, and edge-cropped back image of the document and its associated token.
faceImage / tokenFaceImage
The face image found in the document, if any, and its associated token.
documentCaptured
This property indicates the document model that has been captured when a search is performed in SMSearch mode. This way the application can know which model, among all allowed ones, has been detected.
matchingSidesScore
This property returns a calculation of the similarity of the data read between the front and back of the document. The calculation is performed by checking the similarity between the common fields read on both sides. The result of the calculation will be a value between 0.0 and 1.0 in case there are common fields in the document. The higher the value, the more similar the compared data are. If the calculation returns -1.0, it means the document does not contain common fields or information from both sides is not yet available.
captureProgress property
This property returns the state the capture process was in when the widget finished successfully (STATUS_OK). In a timeout, data es nil and this value is not included in the SdkResult of the error callback. These are the possible values:
0: In the Front reading, the widget finished without being able to detect anything. Generally when no document is placed.
1: In the Front reading, the widget finished having partially detected a document. In this case some of the expected elements were detected, but not all of the necessary ones.
2: In the Front reading, the widget finished having completed the detection of all the document elements. If the widget ends in this state it is because the OCR analysis could not be completed successfully.
3: In the Front reading, the widget finished having analyzed and extracted all the OCR from the document. This is the state a correct Front reading of a document would end in.
The states from 4 to 7 are exactly the same, except that they refer to the result of the process when the back is analyzed.
ocrResults
This dictionary contains all the data detected in the document. The keys of each field are coded in such a way that the key itself contains information about where the value was obtained. Thus, for example, the key Front/MRZ/DocumentNumber indicates the value of DocumentNumber that was read on the Front of the document and in the MRZ region. These keys depend on the captured document and therefore will be different between different countries and document models. The dictionary also contains keys with more generic names that do not carry location-related information. These keys contain the most complete data of all those read for that field.
These keys are the following:
FirstName: The value associated with this key contains the user's first name.
LastName: The value associated with this key contains the user's last name.
DateOfBirth: The value associated with this key contains the date of birth detected on the document.
Gender: The value associated with this key contains the user's sex detected on the document.
Nationality: The value associated with this key contains the user's nationality detected on the document.
DocumentNumber: The value associated with this key contains the document number.
DateOfExpiry: The value associated with this key contains the document expiration date.
Issuer: The value associated with this key contains the document issuer.
DateofIssue: The value associated with this key contains the document issue date.
PlaceOfBirth: The value associated with this key contains the user's place of birth.
Address: The value associated with this key contains the address detected on the document.
Additionally, keys from the results object itself are added to make searching easier:
DocumentCaptured: Value of the document model that has been captured according to the model .xml. Corresponds to the documentCaptured property.
MatchingSidesScore: Value indicating the correspondence between the read sides of the document. Corresponds to the matchingSidesScore property.
countryCaptured
Document country.
documentTypeCaptured
Document type. Corresponds to those in section 5.1.10.
encodedDataImages
Available only with flag encodedDataFocusEnabled active, in MBSDR flavor and resource zip version > 1.41.4. Array of images extracted by the barcode reader.
tokenEncodedDataImages
Available only with flag encodedDataFocusEnabled active, in MBSDR flavor and resource zip version > 1.41.4. Array of tokenized images extracted by the barcode reader.
personalData
Reduced set of data obtained from the user:
issuer
documentNumber
issueDate
expiryDate
name
surname
fullName
gender
birthDate
birthPlace
nationality
address
nfcKey
numSupport
mrz
Advanced information
Document selector - OPTIONAL
showDocumentSelector
Document selector view activation. It will be shown as soon as the controller is launched.
enabledCountries
List of countries in ISO2 that will appear in the selector. If its value is null or does not contain valid values, all those available by the SDK will be shown.
enabledDocumentTypes
List of document types that will appear in the document type selector. If its value is null or contains no values, all those available by the SDK will be shown.
Advanced configuration
The component is configured through an object SelphIDConfigurationData.
debug
Activation of the component's debug mode.
resourcesPath
Sets the path where the widget resource file is located. This file contains both graphic resources and localization resources. This path must be specified relative to the main application's ‘Resources’ folder.
wizardMode
Indicates whether the widget is configured to capture both sides (front and back) of the document one after the other. In this mode the widget would only be launched once and after finishing capturing the front, it would continue with the back immediately.
showResultAfterCapture
Indicates whether to show or not a screen with the captured image of the document after the analysis process. On this screen, the user is given the option to repeat the capture process if the image obtained from the document were not correct.
showTutorial
Indicates whether the widget activates the tutorial screen. In this view, how the capture is performed is explained intuitively.
tutorialOnly
Indicates whether the widget should be launched only to show the tutorial.
scanMode
Indicates the OCR scanning mode of the documents. Depending on the choice, several types of documents or one specific one will be scanned and searched. This mode can be of three types:
SelphIDScanMode.MODE_GENERIC: The generic mode that allows scanning any type of document regardless of the country or document type. The result of this mode is not as accurate as the following ones, but it allows several standard documents to be scanned.
SelphIDScanMode.MODE_SEARCH: The search mode will allow using a whitelist and blacklist, and will search the documents that meet those conditions. These conditions are specified in the "specificData" variable. This way, the search can be performed narrowing down the number of templates, making the search much more precise than in the generic case.
SelphIDScanMode.MODE_SPECIFIC: Search for a specific document. These conditions are specified in the "specificData" property shown below.
SpecificData
This property allows defining which documents will be scanned during the process, if the scanning mode (scanMode) is declared as SMSearch or SMSpecific.
An example configuration that allows scanning all documents of Spanish nationality would be the following:
tokenImageQuality
Indicates the amount of quality desired in the tokenized images. Value between 0 and 1.
DocumentType
The allowed values are the following:
SelphIDDocumentType.ID_CARD: The widget is configured to capture identity documents.
SelphIDDocumentType.PASSPORT: The widget is configured to capture passports.
SelphIDDocumentType.DRIVERS_LICENSE: The widget is configured to capture driving licenses.
SelphIDDocumentType.FOREIGN_CARD: The widget is configured to capture foreign documents.
SelphIDDocumentType.CUSTOM: The widget is configured to capture other types of documents that do not correspond to any of the previous categories.
DocumentSide
The allowed values are the following:
SelphIDDocumentSide.FRONT: The widget is configured to capture the front side of the document.
SelphIDDocumentSide.BACK: The widget is configured to capture the back side of the document.
SelphIDDocumentSide.ALL: The widget is configured to capture both sides of the document.
Timeout
It is an enumeration that defines the timeout for capturing one side of the document. It has 3 possible values:
SelphIDTimeout.SHORT: 15 seconds.
SelphIDTimeout.MEDIUM: 20 seconds.
SelphIDTimeout.LONG: 25 seconds.
SelphIDTimeout.VERY_LONG: 60 seconds.
videoFilename
Sets the absolute path of the file name in which a video of the capture process will be recorded. The application is responsible for requesting the necessary permissions from the phone in case that path requires additional permissions. The widget, by default, will not perform any recording process unless a file path is specified through this method.
DocumentModels
This property allows, through an XML-formatted string, configuring the document modeling that the widget will try to capture. The definition of this modeling is found, by default, in a model .xml located in the resource .zip. With this property, an application can update the document models on the fly.
Note: This property does not alter the contents of the resource file.
generateRawImages
This property configures the widget to return the full camera image used to capture the document. These images are returned in the properties rawFrontDocument and rawBackDocument of the object results respectively.
tokenPreviousCaptureData
When document capture is done in 2 calls, this property allows passing a dictionary with the previous capture information. In this way the widget can intelligently combine the results of both readings and thus return the combined information from both captures. It also allows the widget to calculate a degree of similarity between the data from both sides.
If the capture of both sides of the document is done in a single call, this is not necessary since the widget does this internally.
translationsContent
This advanced property allows, through an XML-formatted string, configuring the translation of the literals shown during the process.
Note: This property does not alter the contents of the resource file.
viewsContent
This advanced property allows, through an XML-formatted string, configuring the widget views.
Note: This property does not alter the contents of the resource file.
showDiagnostic
Show diagnostic screens at the end of the process
showPreviousTip
Shows a screen before capture starts with information about the process to be performed and a button to launch it.
vibrationEnabled
Indicates whether vibration feedback is desired when the process ends.
animateDismiss
Indicates whether the SDK dismissal is animated when the process ends. Available from 2.8.1.
encodedDataFocusEnabled
Activates barcode reading mode when reading is difficult. Only available in the MBSDR flavor and with the resource zip in a version greater than > 1.41.4
Component customization
Aside from the changes that can be made at the SDK level (which are explained in the SDK Customization document), this specific component allows its interface to be modified.
Colors
The component, in addition to the existing standard colors in the general customization section, has two specific colors for the selector view:
sdkSelectorBackgroundColor: This is the color used for the selection view background. Do not confuse it with sdkBackgroundColor.
sdkCardBackgroundColor: This is the color used for the background of the selection "cards".
Images
The component, in addition to the existing standard images in the general customization section, has specific images for the selector view. The list can be seen by accessing the R.Image.
Texts
The texts can be customized by overwriting the corresponding keys in Localizable.strings.
Keys with the suffix _alt are used for accessibility (VoiceOver).
Example of text modification START for es:
You need to go to the file Localizable.strings in the folder es.lproj (if this folder does not exist, it will need to be created).
"selphid_component_tip_button_message"="EMPEZAR";
If a key is not defined, the default value will be used.
selphid_component_tutorial_message_1
Look for a background with good contrast.
selphid_component_tutorial_message_2
Place the document inside the frame.
selphid_component_tutorial_message_3
Avoid reflections that make the document difficult to read.
selphid_component_tip_message
Focus your document inside the frame. The photo will be taken automatically.
selphid_component_tip_title
Document photo
selphid_component_tip_button
START
selphid_component_tip_close_button_alt
BACK
selphid_component_tip_button_alt
Start document capture
selphid_component_tip_anim_id_alt
Place your identity document horizontally, and point your phone vertically.
selphid_component_tip_anim_passport_alt
Animation of a mobile phone taking a picture of a passport. The document appears horizontally, open on the page where the photo appears. The mobile phone is in vertical orientation. A frame appears on the phone screen. When the passport page fits inside the frame, the application takes a photo.
selphid_component_tip_anim_driving_alt
Animation of a mobile phone taking a picture of a driving license. The document appears horizontally, and the mobile phone is in vertical orientation. A frame appears on the phone screen. When the document fits inside the frame, the application takes a photo.
selphid_component_tutorial_1_anim_id_alt
Place your identity document horizontally, and point your phone vertically.
selphid_component_tutorial_2_anim_id_alt
Place the document on a surface with a color different from the document.
selphid_component_tutorial_3_anim_id_alt
There are reflections on the document.
selphid_component_tutorial_1_anim_pass_alt
A white passport is shown on a white background. The edges of the document are not clearly distinguishable. Through an animation, the background changes color.
selphid_component_tutorial_2_anim_pass_alt
A mobile phone takes a picture of a passport. The document appears horizontally, and the mobile phone is in vertical orientation. A frame appears on the phone screen. When the document fits inside the frame, the application takes a photo.
selphid_component_tutorial_3_anim_pass_alt
A passport, seen from the front. When it is tilted, reflections appear on the document.
selphid_component_tutorial_1_anim_driving_alt
A white driving license is shown on a white background. The edges of the document are not clearly distinguishable. Through an animation, the background changes color.
selphid_component_tutorial_2_anim_driving_alt
A mobile phone takes a picture of a driving license. The document appears horizontally, and the mobile phone is in vertical orientation. A frame appears on the phone screen. When the document fits inside the frame, the application takes a photo.
selphid_component_tutorial_3_anim_driving_alt
A driving license, seen from the front. When it is tilted, reflections appear on the document.
selphid_component_tip_health_alt
Animation of a mobile phone taking a picture of a health card. The document appears horizontally, and the mobile phone is in vertical orientation. A frame appears on the phone screen. When the document fits inside the frame, the application takes a photo.
selphid_component_tutorial_1_anim_health_alt
A white health card is shown on a white background. The edges of the document are not clearly distinguishable. Through an animation, the background changes color.
selphid_component_tutorial_2_anim_health_alt
A mobile phone takes a photo of a health card. The document appears horizontally, and the phone is in a vertical position. A frame appears on the phone screen. When the document fits inside the frame, the app takes a photo.
selphid_component_tutorial_3_anim_health_alt
A health card, seen from the front. When you tilt it, reflections appear on the document.
selphid_component_tip_custom_alt
selphid_component_tutorial_1_anim_custom_alt
selphid_component_tutorial_2_anim_custom_alt
selphid_component_tutorial_3_anim_custom_alt
selphid_component_timeout_title
Time's up
selphid_component_timeout_front_desc
Check that the front of the document is within the frame and the data are visible.
selphid_component_timeout_back_desc
Check that the back of the document is within the frame and the data are visible.
selphid_component_timeout_desc
Check that the document is within the frame and the data are visible.
selphid_selector_title
Complete your Onboarding
selphid_selector_country_label
Which country is your document from?
selphid_selector_country_search_label
Choose a country
selphid_selector_country_search_placeholder
Search for a country
selphid_selector_country_no_results
No results
selphid_selector_document_label
Which document will you use?
selphid_selector_document_dialog_title
Choose the document
selphid_selector_continue
CONTINUE
selphid_selector_type_id_card
Identity document
selphid_selector_type_passport
Passport
selphid_selector_type_drivers_license
Driver's License
selphid_selector_type_foreign_card
Residence card
selphid_selector_type_credit_card
Credit card
selphid_selector_type_custom
Custom
selphid_selector_type_visa
Visa
selphid_selector_exit_alert_finish
Finish
selphid_selector_exit_alert_question
Are you sure you want to finish the process?
selphid_selector_exit_alert_accept
Accept
selphid_selector_exit_alert_cancel
Cancel
Animations
The animations for the previous tip and tutorials are Lottie (.json).
To replace them:
Add the file to the folder
Resources.Keep exactly the same file name.
If they are not replaced, the default animations will be shown.
selphid_anim_tip_id_male
Animation for the previous tip for the identity document
selphid_anim_tip_pass_male
Animation for the previous tip for the passport
selphid_anim_tip_driver_male
Animation for the previous tip for the Driver's License
selphid_anim_tuto_id_1
First animation of the identity document tutorial
selphid_anim_tuto_id_2
Second animation of the identity document tutorial
selphid_anim_tuto_id_3
Third animation of the identity document tutorial
selphid_anim_tuto_pass_1
First animation of the passport tutorial
selphid_anim_tuto_pass_2
Second animation of the passport tutorial
selphid_anim_tuto_pass_3
Third animation of the passport tutorial
selphid_anim_tuto_driving_1
First animation of the Driver's License tutorial
selphid_anim_tuto_driving_2
Second animation of the Driver's License tutorial
selphid_anim_tuto_driving_3
Third animation of the Driver's License tutorial
selphid_anim_tuto_custom_1
First animation of the tutorial for a customized document
selphid_anim_tuto_custom_2
Second animation of the tutorial for a customized document
selphid_anim_tuto_custom_3
Third animation of the tutorial for a customized document
Last updated