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

Document Capture - SelphID

This component requires a minimum iOS9 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, document types and 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), they must be removed completely before installing the components of SDK Mobile.

CocoaPods

  • Facephi libraries are distributed remotely through dependency managers. The dependencies required that must have been installed beforehand (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 required dependencies are installed beforehand.

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 started and a new operation has been 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

Error handling

finishStatus: Indicates whether the operation has completed successfully. Possible values:

errorType: Widget-specific errors.

In iOS, errorType is a ErrorType of 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. In iOS there is no case TIMEOUT without a prefix.

To serialize the error, use:

This returns SPD_TIMEOUT whether the enum is SDK_TIMEOUT and SELPHID_TIMEOUT.

Timeout behavior

In a Timeout, the result has:

  • finishStatus: STATUS_ERROR

  • data: nil (no SelphIDResult)

  • errorType: .SDK_TIMEOUT or .SELPHID_TIMEOUT(UIImage?, UIImage?)

The case SELPHID_TIMEOUT retains, when available, the raw document images captured before the timeout (rawFrontDocument and rawBackDocument of the widget). That information do not is part of data and is not returned as rawFrontDocument / rawBackDocument of the success result; it can only be read in iOS using pattern matching on errorType:

If the Timeout comes as SDK_TIMEOUT, it does not include raw images. If it comes as SELPHID_TIMEOUT, the associated images can be nil when the Timeout occurs through the widget 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 and SELPHID_TIMEOUT of the enum).

In iOS, properties such as timeoutDiagnostic or captureProgress do not are included in the SdkResult error. The component uses captureProgress internally to show the diagnostic screen message when showDiagnostic is active.

If showDiagnostic is active, 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 is executed immediately.

The following list includes cross-platform contract errors; some do not occur in 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 cancellation of the SDK has been performed.

  • SPD_COMPONENT_LICENSE_ERROR: The component License is incorrect.

  • 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 are 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 output data

Successful execution reception - data

The content of the field data depends on the component. In the case of SelphID, the following fields are returned:

frontDocument / tokenFrontDocument

The front image of the document, processed, cleaned, and cropped by the edges, and its corresponding token.

backDocument / tokenBackDocument

The back image of the document, processed, cleaned, and cropped by the edges, 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 was captured when a search is performed in SMSearch mode. This allows the application to know which model, among all the allowed ones, was 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 if there are common fields in the document. The higher the value, the more similar the compared data are. If the calculation returns -1.0, the document does not contain common fields or information from both sides is not yet available.

Property captureProgress

This property returns the state in which the capture process was when the widget finished successfully (STATUS_OK). In a Timeout, data is nil and this value is not included in the SdkResult from the error callback. These are the possible values:

  • 0: In the Front reading, the widget finished without having detected anything. Usually 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 could be detected, but not all the necessary ones.

  • 2: In the Front reading, the widget finished having completed detection of all the document elements. If the widget ends in this state, it is because 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 in which a correct Front reading of a document would end.

The states from 4 to 7 are exactly the same, only they refer to the process result when the back is analyzed.

ocrResults

This dictionary contains all the data detected on the document. The keys of each field are encoded so that the key itself contains information about where the value was obtained from. Thus, for example, the Front/MRZ/DocumentNumber key indicates the value of the 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 across different countries and document models. The dictionary also contains keys with more generic names that do not include location 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 in the document.

  • Gender: The value associated with this key contains the user's sex detected in the document.

  • Nationality: The value associated with this key contains the user's nationality detected in the document.

  • DocumentNumber: The value associated with this key contains the document number.

  • DateOfExpiry: The value associated with this key contains the document expiry 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 in the document.

Additionally, keys of the results object itself are added to make searching easier:

  • DocumentCaptured: Value of the document model that was 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

Country of the document.

documentTypeCaptured

Document type. Corresponds to those in section 5.1.10.

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

Activation of the document selector view. It will be presented 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 does not contain values, all those available by the SDK will be shown.

Advanced configuration

The component is configured through an object SelphIDConfigurationData.

debug

Enables the component debug mode.

resourcesPath

Sets the path where the widget resource file is located. This file contains both the graphic resources and the localization resources. This path must be specified relative to the ‘Resources’ folder of the main application.

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 capturing the front, it would continue with the back.

showResultAfterCapture

Indicates whether to show 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 is not correct.

showTutorial

Indicates whether the widget activates the tutorial screen. This view explains intuitively how the capture is performed.

tutorialOnly

Indicates whether the widget should be launched only to show the tutorial.

scanMode

Indicates the OCR scanning mode for documents. Depending on the choice, several types of documents or one specific document will be scanned and searched. This mode can be of three types:

  • SelphIDScanMode.MODE_GENERIC: The generic mode allows scanning any type of document regardless of country or document type. The result of this mode is not as accurate as the following ones, but it allows scanning several standard documents.

  • SelphIDScanMode.MODE_SEARCH: The search mode will allow using a whitelist and blacklist, and will search in the documents that meet these conditions. These conditions are indicated in the "specificData" variable. This way, the search can be narrowed by limiting 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 indicated in the "specificData" property shown below.

SpecificData

This property allows you to define which documents will be scanned during the process, if the scan mode (scanMode) is set to SMSearch or SMSpecific.

An example configuration that allows scanning all Spanish nationality documents would be the following:

tokenImageQuality

Indicates the amount of quality wanted in the tokenized images. Value between 0 and 1.

DocumentType

The permitted 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 permitted 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 enumerated type 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 where 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. By default, the widget 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 models that the widget will try to capture. The definition of these models is, by default, in an .xml models file found in the resources .zip. With this property, an application can update the document models on the fly.

Note: This property does not alter the contents of the resources file.

generateRawImages

This property configures the widget to return the complete 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 performed 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 reads and thus return the combined information from both captures. It also allows the widget to calculate a degree of similarity between the data on both sides.

In the case where the capture of both sides of the document is done in a single call, this is not necessary since the widget performs this process 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 resources file.

viewsContent

This advanced property allows the widget views to be configured using a string in xml format.

Note: This property does not alter the contents of the resources file.

showDiagnostic

Show diagnostic screens at the end of the process

showPreviousTip

Displays a screen before starting the capture with information about the process to be carried out and a button to start it.

vibrationEnabled

Indicates whether vibration feedback is desired when the process ends.

animateDismiss

Indicates whether the SDK closure is animated when the process ends. Available from 2.8.1.

Component Customization

Apart 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 standard colors existing in the general customization section, has two specific colors for the selector view:

  • sdkSelectorBackgroundColor: It is the color used for the background of the selection view. Do not confuse it with sdkBackgroundColor.

  • sdkCardBackgroundColor: It is the color used for the background of the selection cards.

Images

The component, in addition to the standard images existing in the general customization section, has specific images for the selector view. The list can be seen by accessing the enumeration R.Image.

Texts

The texts can be customized by overriding the corresponding keys in Localizable.strings.

Keys with the suffix _alt are used for accessibility (VoiceOver).

Example of text modification START for is:

You must go to the file Localizable.strings in the folder es.lproj (if this folder does not exist, it must 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 glare that makes 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 photo of a passport. The document appears horizontally, open on the page showing the photo. The phone is in a vertical position. 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 photo of a driving license. 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 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 photo of a passport. 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 application takes a photo.

selphid_component_tutorial_3_anim_pass_alt

A passport, seen from the front. When 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 photo of a driving license. 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 application takes a photo.

selphid_component_tutorial_3_anim_driving_alt

A driving license, seen from the front. When tilted, reflections appear on the document.

selphid_component_tip_health_alt

Animation of a mobile phone taking 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 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 application takes a photo.

selphid_component_tutorial_3_anim_health_alt

A health card, seen from the front. When tilted, 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

Timeout exceeded

selphid_component_timeout_front_desc

Check that the front of the document is inside the frame and the data is visible.

selphid_component_timeout_back_desc

Check that the back of the document is inside the frame and the data is visible.

selphid_component_timeout_desc

Check that the document is inside the frame and the data is 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 tip and tutorial animations are Lottie (.json).

To replace them:

  • Add the file in the folder Resources.

  • Keep exactly the same file name.

If they are not replaced, the default animations will be shown.

Name
Usage

selphid_anim_tip_id_male

Animation for the prior tip for the identity document

selphid_anim_tip_pass_male

Animation for the prior tip for the passport

selphid_anim_tip_driver_male

Animation for the prior tip for the driving license

selphid_anim_tuto_id_1

First tutorial animation for the identity document

selphid_anim_tuto_id_2

Second tutorial animation for the identity document

selphid_anim_tuto_id_3

Third tutorial animation for the identity document

selphid_anim_tuto_pass_1

First tutorial animation for the passport

selphid_anim_tuto_pass_2

Second tutorial animation for the passport

selphid_anim_tuto_pass_3

Third tutorial animation for the passport

selphid_anim_tuto_driving_1

First tutorial animation for the driving license

selphid_anim_tuto_driving_2

Second tutorial animation for the driving license

selphid_anim_tuto_driving_3

Third tutorial animation for the driving license

selphid_anim_tuto_custom_1

First tutorial animation for a customized document

selphid_anim_tuto_custom_2

Second tutorial animation for a customized document

selphid_anim_tuto_custom_3

Third tutorial animation for a customized document

PreviousFace Capture with IAD - SelphiNextFingerprint Capture - Phingers

Last updated