> 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). # Identity 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 permission 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 **mandatory** dependencies that must have been installed previously (by adding them to the project's Podfile file) are: ```swift pod 'FPHISDKMainComponent', '~> $VERSION' ``` * To install the **SelphID**component, 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 mandatory dependencies are previously installed. ```swift //HTTPS https://github.com/facephi-clienters/SDK-SdkPackage-SPM.git //SSH git@github.com:facephi-clienters/SDK-SdkPackage-SPM.git ``` To install the **SelphID**, include it in the project 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 **Info.plist**: ``` Camera use must be allowed (Privacy - Camera Usage Description) ``` ## Available controllers | **Controller** | **Description** | | ----------------- | ------------------------------------ | | SelphIDController | Main document recognition controller | *** ## Simplified Launch Once the SDK has been 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) ``` *** ## Receiving the result The launch result is returned in an object `SdkResult`, which contains: * `selphIDResult.finishStatus` * `selphIDResult.errorType` * `selphIDResult.data` *** ### Error handling *finishStatus*: It will tell us whether the operation has finished correctly. Possible values: ```swift FinishStatus.STATUS_OK FinishStatus.STATUS_ERROR ``` *errorType*: Widget-specific errors. In iOS, `errorType` is an `ErrorType` of the SDK. In a Timeout, the Swift enum can be `.SDK_TIMEOUT`, `.SELPHID_TIMEOUT(UIImage?, UIImage?)` or, if interpolated directly, display names such as `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` (it does not return a `SelphIDResult`) * `errorType`: `.SDK_TIMEOUT` or `.SELPHID_TIMEOUT(UIImage?, UIImage?)` The case `SELPHID_TIMEOUT` preserves, when available, the raw images of the document captured before the Timeout (`rawFrontDocument` and `rawBackDocument` of the widget). That information **do not** is part of `data` nor is it returned as `rawFrontDocument` / `rawBackDocument` part of the successful result; it can only be read in iOS through pattern matching on `errorType`: ```swift if case .SELPHID_TIMEOUT(let frontRaw, let backRaw) = sdkResult.errorType { // frontRaw, backRaw: UIImage? (can be 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 is triggered 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 type. The component uses `captureProgress` internally to show the diagnostic screen message when `showDiagnostic` is active. If `showDiagnostic` is active, the `output` callback 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 errors from the cross-platform contract; 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 made. * 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 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: Permission 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 response - 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 that has been 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 way the application can know which model, out of all the allowed ones, was detected. **matchingSidesScore** This property returns a similarity calculation 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, it means that 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` 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 were detected, but not all the necessary ones. * **2**: In the Front reading, the Widget finished having completed detection of all the elements of the document. 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 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 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 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 DocumentNumber value that was read on the Front of the document and in the MRZ region. These keys depend on the captured document and therefore will differ between 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 among all those read for that field. These keys are as follows: * **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 names. * **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's 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 in the document. Additionally, keys from the results object itself are added to make searching easier: * **DocumentCaptured**: Value of the document model that was captured according to the .xml of models. Corresponds to the documentCaptured property. * **MatchingSidesScore**: Value indicating the match between the read sides of the document. Corresponds to the matchingSidesScore property. **countryCaptured** Country of the document. **documentTypeCaptured** Document type. It 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 ISO2 countries that will appear in the selector. If its value is null or does not contain valid values, all those available in 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 in the SDK will be shown. ### Advanced configuration The component is configured through an object `SelphIDConfigurationData`. **debug** Activates 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 application's ‘Resources’ folder. **wizardMode** Indicates whether the Widget is configured to capture both parts (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 immediately with the back. **showResultAfterCapture** Indicates whether or not 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 is to be launched only to show the tutorial. **scanMode** Indicates the OCR scan mode of the 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 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 a whitelist and blacklist, and will search the documents that meet those conditions. These conditions are indicated in the variable "specificData". This mode allows searching by narrowing 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 property "specificData" shown below. **SpecificData** This property lets you define which documents will be scanned during the process, if the scan mode (scanMode) is set to SMSearch or SMSpecific. An example of a configuration that allows scanning all documents of Spanish nationality 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 you want to receive in the tokenized images. Value between 0 and 1. **DocumentType** The permitted values are as follows: * **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 driver's 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 as follows: * **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 capture timeout for 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 filename 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. 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 modeling that the Widget will try to capture. The definition of this modeling is found by default in an .xml model file that is 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 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 a dictionary with the previous capture information to be passed. In this way the Widget can combine the results of both reads intelligently 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 capture of both sides of the document is done in a single call, this is not necessary since the Widget does 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 via an XML-formatted string. Note: This property does not alter the contents of the resources file. **showDiagnostic** Show diagnostic screens at the end of the process **showPreviousTip** Shows a screen before capture launch with information about the process to be performed and a launch button. **vibrationEnabled** Indicates whether vibration feedback is desired when the process finishes. **animateDismiss** Indicates whether the SDK closes with animation when the process finishes. 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 existing standard colors in the [general customization section](/docs.facephi-en/sdks/sdk-mobile/ios-sdk/personalizacion.md), 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](/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 `R.Image`. #### Texts The texts can be customized by overriding the corresponding keys in `Localizable.strings`. The keys with suffix `_alt` are used for accessibility (VoiceOver). Example of text modification **START** for `is`: You need to 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 picture of a passport. The document appears horizontally, open on the page where the photo appears. The phone is in vertical position. A frame appears on the phone screen. When the passport page fits within the frame, the application takes a picture. | | `selphid_component_tip_anim_driving_alt` | Animation of a mobile phone taking a picture of a driver's license. The document appears horizontally, and the phone is in vertical position. A frame appears on the phone screen. When the document fits within the frame, the application takes a picture. | | `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 document edges 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 phone is in vertical position. A frame appears on the phone screen. When the document fits within the frame, the application takes a picture. | | `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 driver's license is shown on a white background. The document edges 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 driver's license. The document appears horizontally, and the phone is in vertical position. A frame appears on the phone screen. When the document fits within the frame, the application takes a picture. | | `selphid_component_tutorial_3_anim_driving_alt` | A driver's license, seen from the front. When 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 phone is in vertical position. A frame appears on the phone screen. When the document fits within the frame, the application takes a picture. | | `selphid_component_tutorial_1_anim_health_alt` | A white health card is shown on a white background. The document edges are not clearly distinguishable. Through an animation, the background changes color. | | `selphid_component_tutorial_2_anim_health_alt` | A mobile phone takes a picture of a health card. The document appears horizontally, and the phone is in vertical position. A frame appears on the phone screen. When the document fits within the frame, the application takes a picture. | | `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` | Time exceeded | | `selphid_component_timeout_front_desc` | Check that the front of the document is inside the frame and the data are visible. | | `selphid_component_timeout_back_desc` | Check that the back of the document is inside the frame and the data are visible. | | `selphid_component_timeout_desc` | Check that the document is inside 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 previous 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.
NameUse
selphid_anim_tip_id_maleAnimation for the previous tip of the Identity document
selphid_anim_tip_pass_maleAnimation for the previous tip of the Passport
selphid_anim_tip_driver_maleAnimation for the previous tip of the driver's license
selphid_anim_tuto_id_1First animation of the Identity document tutorial
selphid_anim_tuto_id_2Second animation of the Identity document tutorial
selphid_anim_tuto_id_3Third animation of the Identity document tutorial
selphid_anim_tuto_pass_1First animation of the Passport tutorial
selphid_anim_tuto_pass_2Second animation of the Passport tutorial
selphid_anim_tuto_pass_3Third animation of the Passport tutorial
selphid_anim_tuto_driving_1First animation of the driver's license tutorial
selphid_anim_tuto_driving_2Second animation of the driver's license tutorial
selphid_anim_tuto_driving_3Third animation of the driver's license tutorial
selphid_anim_tuto_custom_1First animation of the tutorial for a custom document
selphid_anim_tuto_custom_2Second animation of the tutorial for a custom document
selphid_anim_tuto_custom_3Third animation of the tutorial for a custom document