SelphID Component
0. SDK Mobile baseline requirementsβ
SDK Mobile is a set of libraries (Components) that offer a series of functionalities and services, allowing their integration into a Mobile application in a simple and fully scalable way. Certain components must be installed depending on the use case required. Its high level of modularity allows other new components to be added in the future without affecting those already integrated into the project.
For more information on the base configuration, go to the Getting Started section.
1. Introductionβ
The Component dealt with in the current document is called SelphID Component. It is in charge of capturing documents and the subsequent extraction and analysis of their data. Its main functionalities are the following:
-
Internal management of cameras.
-
Permits management.
-
Assistant in the processes of capturing the front and back of the document. Extraction of the information contained in the document.
-
Obtain the images of the back and reverse side of the document, as well as other images included in the document: user's face, user's signature, etc.
-
High level of configuration: different countries, languages, document types...
1.1 Minimum requirementsβ
The minimum iOS SDK version required is as follows:
Minimum iOS version: 13
2. Integration of the componentβ
β οΈ Before integrating this component, it is recommended to read the documentation related to Initial Integration and follow the instructions given in that document.
This section will explain step by step how to integrate the current component into an existing project.
2.1. Dependencies required for integrationβ
In order to avoid conflicts and compatibility problems, in case you want to install the component in a project containing an old version of the Facephi libraries. of the Facephi libraries (Widgets), these must be completely removed before the installation of the components. completely before the installation of the components of the SDKMobile components.
Cocoapodsβ
- Currently FacePhi libraries are distributed remotely through different dependency managers, in this case Cocoapods. The mandatory dependencies that must have been previously installed (adding them in the Podfile file of the project) are:
pod 'FPHISDKMainComponent', '~> 2.3.0'
- To install the SelphID component, the following entry must be included in the application Podfile:
pod 'FPHISDKSelphIDComponent', '~> 2.3.0'
-
Once the dependencies are installed, the different functionalities of the component can be used.
-
In case of development with XCode15 a post-installation script must be included:
SPMβ
- The mandatory dependencies that must have been previously installed are:
//HTTPS
https://github.com/facephi-clienters/SDK-SdkPackage-SPM.git
//SSH
git@github.com:facephi-clienters/SDK-SdkPackage-SPM.git
- To install the SelphID component, it must be included in the project modules:
//HTTPS
https://github.com/facephi-clienters/SDK-SelphidComponentLight.git
//SSH
git@github.com:facephi-clienters/SDK-SelphidComponentLight.git
2.2 Permissions and configurationsβ
In the client application where the components are going to be integrated it is necessary to incorporate the following elements in the Info.plist file.
It is necessary to allow the use of the camera (Privacy - Camera Usage Description).
3. Start new operationβ
In order to generate the associated information correctly in the platform, the newOperation command must be executed first.
βΉοΈ This command must have been executed before launch.
To learn more about how to start a new operation, it is recommended to consult the Start a new operation documentation, which details and explains what this process consists of.
4. Available controllersβ
Controller | Description |
SelphIDController | Document recognition main controller |
5. Component configurationβ
Once initialized, a SelphIDConfigurationData object must be created and passed as a parameter to the SDKController during component launch to configure the current component.
The following section will show the fields part of this class and what each is used for.
5.1 Class SelphIDConfigurationDataβ
5.1.1 Basic Configurationβ
ResourcesPathβ
This is the name of the resource bundle that contains all the elements of the interface
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 when it finishes capturing the front, it would continue with the back.
ShowResultAfterCaptureβ
Indicates whether or not to show a screen with the captured image of the document after the analysis process. This screen gives the user the possibility to repeat the capture process if the image obtained from the document is not correct.
ShowTutorialβ
This property allows to show the tutorial prior to the capture process.
ScanModeβ
Specifies the OCR scanning mode of the documents. Depending on the choice, several types of documents or a 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 independent of country or document type. The output of this mode is not as accurate as the following but it allows to scan several standard documents.
-
SelphIDScanMode.MODE_SPECIFIC: The search mode will allow to use a whitelist and blacklist, and will search the documents that meet these conditions. These conditions are indicated in the variable "specificData". This allows the search to be performed by narrowing the number of templates, and making the search much more refined than in the generic case.
-
SelphIDScanMode.MODE_SEARCH: Search for a specific document. These conditions are indicated in the "specificData" property shown below.
SpecificDataβ
This property allows to define which documents will be scanned during the process, in case of declaring the scan mode (scanMode) to SMSearch or SMSpecific.
An example configuration allowing to scan all documents of Spanish nationality would be the following:
// Search mode definition
conf.scanMode = SelphIDScanMode.MODE_SEARCH
conf.specificData = βES|<ALL>β // CΓ³digo ISO de EspaΓ±a (ES)
DocumentTypeβ
The allowed values are as follows:
-
SelphIDDocumentType.ID_CARD: The widget is configured to perform ID document capture.
-
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 fall into any of the above categories.
ShowDiagnosticβ
If set to true, when an error or lack of permissions occurs, the sdk will display a screen with the error returned by the widget.
5.1.2 Advanced configurationβ
Debugβ
When this attribute is set to true, the number of traces is increased and technical information is displayed on the screen.
Once the development is finished, it must be set to false.
TutorialOnlyβ
This property allows to show only the tutorial, without launching later the capture process.
TokenImageQualityβ
It indicates the quality of the JPEG that is generated and then tokenized, its default and recommended value is "0.5". Its result is merely informative, its use is not recommended for authentication.
Localeβ
It is a String that allows to change the locale and language of the widget. Examples of values it can have are the following:
-
"es" for Spanish.
-
en" for English.
-
fr" for French.
In short, it will depend on the name that appears in the strings.xml file of the language you want to select (strings-es.xml
, strings-en.xml
, strings-fr.xml
).
In the resources zip, which is located inside the strings folder, you can add the strings-xx.xml
files corresponding to each localization you need to incorporate in the widget.
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 enumerated that defines the timeout of the capture of one side of the document. It has 3 possible values:
-
SelphIDTimeout.SHORT: 15 seconds.
-
SelphIDTimeout.MEDIUM: 20 seconds.
-
SelphIDTimeout.LONG: 25 seconds.
GenerateRawImagesβ
This property configures the widget to return the full image from the camera that was used to capture the document. These images are returned in the rawFrontDocument
and rawBackDocument
properties of the results
object respectively.
TranslationsContentβ
This property supports an xml where you provide translations to the messages that are defined in the widget
ViewsContentβ
This property supports an xml where you provide modifications to the widget appearance, colors, proportions... that are defined.
DocumentModelsβ
This property allows, by means of a string in xml format, to configure the modeling of the documents that the widget will try to capture. The definition of this modeling is contained, by default, in a .xml of models that is in the .zip of resources. This property allows an application to update, in hot, the modeling of the documents.
Note: This property does not alter the content of the resource file.
5.1.3 Other parametersβ
VideoFilenameβ
Sets the absolute path to the filename 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. The widget, by default, will not perform any recording process unless a file path is specified using this method.
TokenPreviousCaptureDataβ
When the document capture is performed in 2 calls, this property allows to pass a dictionary with the information from the previous capture. This way the widget can combine the results of both reads in a smart way and thus return the combined information from both captures. It also allows the widget to calculate a degree of similarity of the data from both sides.
In case both sides of the document are captured in a single call this is not necessary as the widget internally does this process.
vibrationEnabledβ
If true, vibration is enabled on errors and if the widget response is OK, the following is true
6. Using the componentβ
Once the component has been started and a new operation has been created (Section 3), the SDK components can be launched. There are two ways to launch the component:
- [WITH TRACKING] This call allows to launch the functionality of the component, but internal events will be tracked to the tracking server:
let controller = SelphIDController(data: selphIDConfigurationData, output: { sdkResult in
// Do whatever with the result
...
}, viewController: viewController)
SDKController.shared.launch(controller: controller)
- [WITHOUT TRACKING] This call allows to launch the functionality of the component, but no event will be tracked to the tracking server:
let controller = SelphIDController(data: selphIDConfigurationData, output: { sdkResult in
// Do whatever with the result
...
}, viewController: viewController)
SDKController.shared.launchMethod(controller: controller)
The launch method must be used by default. This method allows tracking if your component is enabled and will not be used when it is disabled (or the component is not installed).
On the other hand, the launchMethod method covers a particular case in which the integrator has tracking installed and activated but, in a certain flow within the application does not want to track information. In this case, this method is used to prevent this information from being sent to the platform.
7. Receipt of the resultβ
The controllers will return the required information in SdkResult format. More details in the Result Return section.
7.1. Receiving errorsβ
finishStatus: Which will tell us if the operation has finished successfully. Possible values:
FinishStatus.STATUS_OK
FinishStatus.STATUS_ERROR
data: It will have the response data of the executed component function. The fields included in this component are specified in section 7.2.
errorType: Widget's own errors
public enum ErrorType: Equatable, Error {
//COMMON - BASIC
case NO_ERROR
case UNKNOWN_ERROR
case OTHER(String)
//COMMON - REQUIREMENTS
case NO_DATA_ERROR
case NO_OPERATION_CREATED_ERROR
case NETWORK_CONNECTION
//COMMON - PERMISSIONS
case CAMERA_PERMISSION_DENIED
case MIC_PERMISSION_DENIED
case LOCATION_PERMISSION_DENIED
case STORAGE_PERMISSION_DENIED
//COMMON - USER'S INTERACTION
case CANCEL_BY_USER
case TIMEOUT
//COMMON - LICENSE ERROR
case LICENSE_CHECKER_ERROR(String)
case MISSING_COMPONENT_LICENSE_DATA
}
The OTHER case can contain these values:
public enum SelphIDError: String {
case RESOURCES_FILE_NOT_FOUND
case COULD_NOT_CREATE_WIDGET_INSTANCE
case CONSUMED_BY_LICENSE_ERROR
}
7.2. Receiving successful execution - dataβ
The data field is variable and will depend on which component the result was returned. In the case of this component, the fields returned are as follows: