For the complete documentation index, see llms.txt. This page is also available as Markdown.

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 Podfile of 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.finishStatus

  • selphIDResult.errorType

  • selphIDResult.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_ERROR

  • data: nil (a SelphIDResult)

  • errorType: .SDK_TIMEOUT or .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_TIMEOUT or SELPHID_TIMEOUT of 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.

Name
Value

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.

Name
Use

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