> For the complete documentation index, see [llms.txt](https://docs.facephi.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.facephi.com/docs.facephi-en/sdks/sdk-mobile/ios-sdk/modulos/captura-de-documentos.md). # Document Capture - SelphID ## 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](/docs.facephi-en/sdks/sdk-mobile/ios-sdk/inicializacion/lanzamiento-simplificado.md). 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: ```swift pod 'FPHISDKMainComponent', '~> $VERSION' ``` * To install the component **SelphID**, add the corresponding dependency in the `Podfile` of the project. ```swift pod 'FPHISDKSelphIDComponent', '~> $VERSION' ``` ### Swift Package Manager (SPM) If you use **SPM**, make sure the SDK's required dependencies are installed beforehand. ```swift //HTTPS https://github.com/facephi-clienters/SDK-SdkPackage-SPM.git //SSH git@github.com:facephi-clienters/SDK-SdkPackage-SPM.git ``` To install the component **SelphID**, include it in the project's modules. 
//HTTPS
https://github.com/facephi-clienters/SDK-SelphidComponentLight.git
//SSH
git@github.com:facephi-clienters/SDK-SelphidComponentLight.git
*** ## Permissions In the client application where the components will be integrated, it is necessary to include the following element in the file **Info.plist**: ``` Camera usage must be allowed (Privacy - Camera Usage Description) ``` ## 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. ```swift let controller = SelphIDController(data: selphIDConfigurationData, output: { sdkResult in // Do whatever with the result ... }, viewController: viewController) SDKController.shared.launch(controller: controller) ``` *** ## 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: ```swift FinishStatus.STATUS_OK FinishStatus.STATUS_ERROR ``` *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: ```swift sdkResult.errorType.toString(addComponentPrefix: "SPD_") ``` 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`: ```swift if case .SELPHID_TIMEOUT(let frontRaw, let backRaw) = sdkResult.errorType { // frontRaw, backRaw: UIImage? (pueden ser nil) } ``` 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: ``` Front_Detection_None = 0 Front_Detection_Uncertain = 1 Front_Detection_Completed = 2 Front_Document_Analyzed = 3 Back_Detection_None = 4 Back_Detection_Uncertain = 5 Back_Detection_Completed = 6 Back_Document_Analyzed = 7 ``` * **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: ```swift // Search mode definition conf.scanMode = SelphIDScanMode.MODE_SEARCH conf.specificData = “ES|” // ISO code for Spain (ES) ``` **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](/docs.facephi-en/sdks/sdk-mobile/ios-sdk/personalizacion.md), 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](/docs.facephi-en/sdks/sdk-mobile/ios-sdk/personalizacion.md), 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.
NameUsage
selphid_anim_tip_id_maleAnimation for the prior tip for the identity document
selphid_anim_tip_pass_maleAnimation for the prior tip for the passport
selphid_anim_tip_driver_maleAnimation for the prior tip for the driving license
selphid_anim_tuto_id_1First tutorial animation for the identity document
selphid_anim_tuto_id_2Second tutorial animation for the identity document
selphid_anim_tuto_id_3Third tutorial animation for the identity document
selphid_anim_tuto_pass_1First tutorial animation for the passport
selphid_anim_tuto_pass_2Second tutorial animation for the passport
selphid_anim_tuto_pass_3Third tutorial animation for the passport
selphid_anim_tuto_driving_1First tutorial animation for the driving license
selphid_anim_tuto_driving_2Second tutorial animation for the driving license
selphid_anim_tuto_driving_3Third tutorial animation for the driving license
selphid_anim_tuto_custom_1First tutorial animation for a customized document
selphid_anim_tuto_custom_2Second tutorial animation for a customized document
selphid_anim_tuto_custom_3Third tutorial animation for a customized document