DocumentDetector

Supported documents
Currently, the documents supported on iOS are:
Document.RG_FRONT, // front of the ID, where the picture is
Document.RG_BACK, // back of the ID, where the data is
Document.RG_FULL, // open ID, showing both the front and the back
Document.CNH_FRONT, // the front of the CNH, where the picture is
Document.CNH_BACK, // the back of the CNH, where the signature is
Document.CNH_FULL, // open CNH, showing both the front and the back
Document.CRLV, // CRLV
Document.RNE_FRONT, // the front of the RNE and RNM, the part with the data
Document.RNE_BACK, // back of the RNE and RNM, the part with the picture
Document.PASSPORT, // Passport
Document.CTPS_FRONT, // front of the CTPS
Document.CTPS_BACK, // Back of the CTPS
Document.OTHERS, // other identification documents in general, such as RNE, Military ID, OAB, and CRLV
Document.ANY; // allows sending any capture
Required permissions
In the info.plist file, add the permissions below:
Permission
Reason
Required?
Privacy - Camera Usage Description
To capture the document photo(s)
No, only required in camera capture stream
Privacy - Photo Library Usage Description
To perform the gallery opening.
No, required only in the upload stream
NSPhotoLibraryUsageDescription
Utilization
First, instantiate an object of type DocumentDetectorSdk:
let documentDetector = DocumentDetectorSdk.Builder(mobileToken: "mobileToken")
    // see table bellow
    .build()
DocumentDetectorSdk.Builder
Parameter
Required?
String mobileToken
Usage token associated with your CAF account
Yes
.setDocumentDetectorFlow(flow :[DocumentDetectorStep])
Sets the document capture flow, as explained here​
Yes
.setPeopleId(peopleId: String?)
Identifier of the user for the purpose of identifying a fraudulent profile
No, only used for analytics​
.setAnalyticsSettings(useAnalytics: Bool)
Enables/disables data collection for analytics​
No, the default is true
.setPopupSettings(show: Bool)
Change the setting of the inflated popups before each document
No, the default is true
.setDetectionSettings(detectionThreshold : Float)
Changes the default document detection setting, the frame confidence threshold (from 0.0 to 1.0, where 1.0 indicates that the SDK will only accept the document with a perfect frame)
No. The default is 0.91
.setQualitySettings(verifyQuality: Bool, qualityThreshold: Double?)
Changes the default setting for verifying the quality of the captures, indicating whether you want to perform this verification (takes about 2 seconds) and the quality threshold for these photos can be set (value from 1.0 to 5.0). In addition, the SDK will return the URL of the image in the variable DocumentDetectorResult.Capture.ImageUrl. Be careful, if you decide to check the quality in this parameter and there is a connection failure while sending the images, the SDK will terminate with an internet error.
No. The default is true and 1.8, respectively
.setLayout(layout: DocumentDetectorLayout)
Changes the document masks from success, failure, and normal.
It also allows you to change the sound and cancel buttons at the top of the screen. See the example.
No
.setColorTheme(color: UIColor)
Change the color of the sound and cancel buttons that are at the top of the screen. Also change the color of the popup buttons, inflated before each document.
No
.enableSound(enableSound: Bool)
Enables/disables sounds and the sound icon in the SDK
No, the default is true
.showStepLabel(show: Bool)
Show/hide the lower middle label (which contains the document name)
No, the default is true
.showStatusLabel(show: Bool)
Show/hide the central label (which contains the status)
No, the default is true
.setNetworkSettings(requestTimeout:TimeInterval)
Change the default network settings
No. The default is 60 (seconds)
.setLuminositySensorSettings(message: String?, luminosityThreshold :Float?)
Change the default settings of the luminosity sensor. The threshold of this sensor is a number ranging from negative to positive.
No. The default is "Environment too dark" and -3, respectively
.setOrientationSensorSettings(message: String?, orientationThreshold: Double?)
Change the default settings of the orientation sensor. The threshold of this sensor is the acceleration of the device
No. The default is "Cell phone is not horizontal" and 0.3, respectively
.setStabilitySensorSettings(message: String?, stabilityThreshold: Double?)
Changes the default settings of the stability sensor. The threshold of this sensor is in the range of the last two accelerations collected from the device.
No. The default is "Keep the phone still" and 0.3, respectively
.setProxySettings(proxySettings: ProxySettings?)
Sets the proxy settings, as explained here​
No. The default is null
.showPreview(_ show: Bool, title: String?, subtitle: String?, confirmLabel: String?, retryLabel: String?)
Enables/disables the capture preview. If show has true, after each capture, the SDK provides a screen for the user to approve or make the capture again. For the remaining parameters, enter nil to use the default value or a String for a custom text.
No. The default is false
.setMessageSettings(waitMessage: String?, fitTheDocumentMessage: String?, verifyingQualityMessage: String?, lowQualityDocumentMessage: String?, uploadingImageMessage: String?)
Allows customizing messages displayed in the "status" balloon during the capture and analysis process.
No. The pattern is this​
.setCompressSettings(compressionQuality: CGFloat)
Allows you to set the quality in the compression process. By default, all captures are compressed. The method expects values between 0 and 1.0 as parameters, 1.0 being the best quality compression (recommended).
No. The default is 1.0
.setGetImageUrlExpireTime(expireTime: Time)
Allows you to customize the expiration time of the imageUrl. The method takes as a parameter the enum Time with the available times.
No. The default is Time.DEFAULT
.setManualCaptureSettings(enable: Bool, time: TimeInterval)
Enables/disables manual capture. The time parameter sets the time for the capture mode to be enabled.
No. The default is disabled
.enableMultiLanguage(_ enable: Bool)
Enables/disables multi-language support.
No. The default is enabled
.setGetImageUrlExpireTime(expireTime: String)
Sets how long the image URL will last on the server until it is expired. Expect to receive a time interval between "30m" to "30d".
Examples:
setGetImageUrlExpireTime("30m"): To set minutes only
setGetImageUrlExpireTime("24h"): To set only hour(s)
setGetImageUrlExpireTime("1h 10m"): To set hour(s) and minute(s)
setGetImageUrlExpireTime("10d"): To set day(s)
No. The default is 3h
.setMask(type: MaskType)
Sets the type of mask used in the captures. There are three types:
.standard, with the dotted pattern in the document format;
.empty, which removes the mask entirely.
No. The default is .standard
.setCurrentStepDoneDelay(currentStepDoneDelay: TimeInterval)
Delay the activity after the completion of each step. This method can be used to display a success message on the screen itself after the capture, for example.
No. The default is false
.setUploadSettings(UploadSettings uploadSettings)
Sets the settings for uploading documents. By enabling this option, the SDK flow will prompt the user to upload the document files instead of capturing them with the device's camera. This option also includes document quality checks.
No. By default this option is disabled, here is how to set it.
.setResolutionSettings(resolution: Resolution)
Allows you to set the capture resolution. The method takes a parameter a Resolution, which has the following options:
No. The default is hd1280x720
.setAllowedPassportCountriesList(passportList: [CountryCodes])
Enables the option to allow passports from only a certain issuing country, or, a list of countries. See the complete list at: ISO 3166-1 alpha-3​
Example:
.setAllowedPassportList(passportList: [CountryCodes.BRA])
No. Passports issued by any country are accepted by default.
Resolution
Description
low
Specifies appropriate capture settings for output video and audio bit rates suitable for 3G sharing
medium
Specifies the appropriate capture settings for the output video and audio bitrates suitable for sharing over WiFi
high
Specifies appropriate capture settings for high-quality video and audio output
photo
Specifies appropriate capture settings for high-resolution photo quality output
inputPriority
Specifies appropriate capture settings for high-resolution photo quality output
hd1280x720
Specifies the appropriate capture settings for video output at 720p quality (1280 x 720 pixels)
hd1920x1080
Capture settings suitable for 1080p (1920 x 1080 pixels) quality video output
hd4K3840x2160
Capture settings suitable for 2160p (3840 x 2160 pixels) quality video output
DocumentDetectorStep
To create a capture flow, you will need to create an array of DocumentDetectorStep, where each element will be a capture step. To construct each DocumentDetectorStep object, you can enter the following elements:
Parameter
Required?
document: Document
Identifies which document you want to capture in the respective step
Yes
stepLabel: String?
Text to be displayed at the bottom of the layout
No. There is a pattern per Document Type
illustration: UIImage?
Illustration to be shown in the popup before the capture
No. There is a pattern per Document Type
audio: URL?
Audio to be played at the beginning of the step Example.
No. There is a pattern per Document Type
MessageSettings
Attribute
Default Value
waitMessage: String
Message displayed when SDK is in the process of opening
"Aguarde..."
fitTheDocumentMessage: String
Message advising to fit the document to the mask
"Encaixe o documento na marcação"
verifyingQualityMessage: String
Message displayed when the SDK makes a request to the backend, verifying quality
"Verificando qualidade…"
lowQualityDocumentMessage: String
Message displayed when the quality of the capture fails
"Ops, não foi possível ler as informações. Por favor, tente novamente"
uploadingImageMessage: String
Message displayed when there is no quality check and the capture is being saved on the servers
"Enviando imagem…"
popupDocumentSubtitleMessage: String
Text displayed in the step initialization popup
"Posicione o documento em uma mesa, centralize-o na marcação e aguarde a captura automática."
After creating the DocumentDetector object, start the DocumentDetectorController by passing this object as a parameter in the constructor:
let scannerVC = DocumentDetectorController(documentDetector: documentDetector)
scannerVC.documentDetectorDelegate = self
present(scannerVC, animated: true, completion: nil)
UploadSettings
To activate the document upload functionality it is necessary to instantiate an object of type UploadSettings() and set its parameters:
Parameter
Required?
enable
Enables/disables this feature.
No. The default is true
compress
Enables/disables file compression before uploading.
No. The default is true
fileFormats
Defines the file format(s) that will be accepted for upload.
No. By default .PDF , .JPEG and .PNG are accepted
maximumFileSize
Sets the maximum KB limit of the file to upload.
No. The default limit is 20000 KB (20MB).
Currently, the supported file formats are:
public enum FileFormat: String {
    case png
    case jpeg
    case pdf
}
Getting the result
To get the result, you must implement the DocumentDetectorControllerDelegate delegate in your controller:
class YouController: UIViewController, DocumentDetectorControllerDelegate{
    
    // MARK: - Document Detection Delegates
    
    func documentDetectionController(_ scanner: DocumentDetectorController, didFinishWithResults results: DocumentDetectorResult) {
        //Called when the process was successfully executed
        //The result variable contains the data obtained
    }
    
    func documentDetectionControllerDidCancel(_ scanner: DocumentDetectorController) {
        // Called when the user cancel
    }
    
    func documentDetectionController(_ scanner: DocumentDetectorController, didFailWithError error: DocumentDetectorFailure) {
        //Called when the process terminate with an error
        //The error variable contains info about error
    }
}
DocumentDetectorResult
Parameter
Can it be null?
captures:[Capture]
The array with the respective captures of the parameterized documents
Yes, in case of error
type: String
The class of the read document stream. This parameter is useful in an integration with our OCR route. The existing types are: ["blank", "cnh", "cnh_new", "generic", "rg", "rg_new", "rne", "rnm", "ctps", "passport, crlv, crlv_new"]
Yes, in case of error
trackingId: String?
Identifier of this run on our servers. If possible, save this field and send it along to our API. This way we will have more data about how the user behaved during the execution
Yes, if the user sets useAnalytics = false or the analytics calls do not work
Capture
Parameter
Can it be null?
image: UIImage
Document image
No
imageUrl :String
URL of the document on CAF's server. If you want this URL, keep enabled the parameter that checks the image quality
Yes, if you choose not to check the image quality
scannedLabel :String
Label of the respective document within the following possibilities: ["blank", "cnh_back", "cnh_front", "cnh_full", "new_cnh_back", "new_cnh_front", "new_cnh_full", "crlv", "crlv_new", "generic", "rg_back", "rg_front", "rg_full", "rg_new_back", "rg_new_front", "rg_new_full", "rne_back", "rne_front", "rnm_back", "rnm_front", "ctps_back", "ctps_front", "passport"]
No
quality :Double
Quality inferred by the document quality algorithm, when enabled. Varies between 1.0 and 5.0
May be 0, if the SDK does not check for quality
lensFacing: Int
Defines the face of the camera that was used. Use DocumentDetectorResult.LENS_FACING_FRONT or DocumentDetectorResult.LENS_FACING_FRONT to validate.
No
DocumentDetectorFailure
Superclass that leads to the SDK shutdown. To find out what the reason was, find out which object class has the **isKindOfClass() ** method, equivalent to instanceof in Java and is in Dart:
isKindOfClass()
Description
Exemple
InvalidTokenReason
The token entered is not valid for the corresponding product
Parameterize "test123" as token in the SDK builder
PermissionReason
You are missing some mandatory permission to run the SDK
Start DocumentDetector without camera permission granted
NetworkReason
Internet connection failure
User was without internet during facematch in FaceAuthenticator
ServerReason
When an SDK request receives a status code of failure
In theory, it shouldn't happen. If it does, let us know!
StorageReason
There is no space on the user device's internal storage
When there is no space on the internal storage while capturing the document photo
Examples
Customizing the Layout
You can customize the layout by creating an object of type DocumentDetectorLayout and passing it as a parameter in DocumentDetectorBuilder:
let layout = DocumentDetectorLayout()
​
layout.changeMaskImages(
    greenMask: UIImage(named: "my_green_mask"),
    whiteMask: UIImage(named: "my_white_mask"),
    redMask: UIImage(named: "my_red_mask"))
​
layout.changeSoundImages(soundOn: UIImage(named: "my_sound_on_image"),
                        soundOff: UIImage(named: "my_sound_off_image"))
                        
layout.closeImage = UIImage(named: "my_close_image")
layout.buttonSize = CGFloat(50)
layout.buttonContentMode = .scaleAspectFill
​
layout.setFont = UIImage(named: "my_font")
​
let documentDetectorConfiguration = DocumentDetectorBuilder(apiToken: "API_TOKEN")
    .setDocumentDetectorFlow(flow: DocumentDetectorBuilder.RG_FLOW)
    .setLayout(layout: layout)
    .build()
How to get the URL of an audio
let bundle = Bundle.init(for: type(of: self))
let audioURL = URL(fileURLWithPath: bundle.path(forResource: "my_audio_file", ofType: "mp3")!)

Last modified 2mo ago

Permission	Reason	Required?
`Privacy - Camera Usage Description`	To capture the document photo(s)	No, only required in camera capture stream
`Privacy - Photo Library Usage Description`	To perform the gallery opening.	No, required only in the upload stream

Parameter	Required?
`String mobileToken` Usage token associated with your CAF account	Yes
`.setDocumentDetectorFlow(flow :[DocumentDetectorStep])` Sets the document capture flow, as explained here	Yes
`.setPeopleId(peopleId: String?)` Identifier of the user for the purpose of identifying a fraudulent profile	No, only used for analytics
`.setAnalyticsSettings(useAnalytics: Bool)` Enables/disables data collection for analytics	No, the default is `true`
`.setPopupSettings(show: Bool)` Change the setting of the inflated popups before each document	No, the default is `true`
`.setDetectionSettings(detectionThreshold : Float)` Changes the default document detection setting, the frame confidence threshold (from 0.0 to 1.0, where 1.0 indicates that the SDK will only accept the document with a perfect frame)	No. The default is 0.91
`.setQualitySettings(verifyQuality: Bool, qualityThreshold: Double?)` Changes the default setting for verifying the quality of the captures, indicating whether you want to perform this verification (takes about 2 seconds) and the quality threshold for these photos can be set (value from 1.0 to 5.0). In addition, the SDK will return the URL of the image in the variable `DocumentDetectorResult.Capture.ImageUrl`. Be careful, if you decide to check the quality in this parameter and there is a connection failure while sending the images, the SDK will terminate with an internet error.	No. The default is true and 1.8, respectively
`.setLayout(layout: DocumentDetectorLayout)` Changes the document masks from success, failure, and normal. It also allows you to change the sound and cancel buttons at the top of the screen. See the example.	No
`.setColorTheme(color: UIColor)` Change the color of the sound and cancel buttons that are at the top of the screen. Also change the color of the popup buttons, inflated before each document.	No
`.enableSound(enableSound: Bool)` Enables/disables sounds and the sound icon in the SDK	No, the default is `true`
`.showStepLabel(show: Bool)` Show/hide the lower middle label (which contains the document name)	No, the default is `true`
`.showStatusLabel(show: Bool)` Show/hide the central label (which contains the status)	No, the default is `true`
`.setNetworkSettings(requestTimeout:TimeInterval)` Change the default network settings	No. The default is 60 (seconds)
`.setLuminositySensorSettings(message: String?, luminosityThreshold :Float?)` Change the default settings of the luminosity sensor. The threshold of this sensor is a number ranging from negative to positive.	No. The default is "Environment too dark" and -3, respectively
`.setOrientationSensorSettings(message: String?, orientationThreshold: Double?)` Change the default settings of the orientation sensor. The threshold of this sensor is the acceleration of the device	No. The default is "Cell phone is not horizontal" and 0.3, respectively
`.setStabilitySensorSettings(message: String?, stabilityThreshold: Double?)` Changes the default settings of the stability sensor. The threshold of this sensor is in the range of the last two accelerations collected from the device.	No. The default is "Keep the phone still" and 0.3, respectively
`.setProxySettings(proxySettings: ProxySettings?)` Sets the proxy settings, as explained here	No. The default is `null`
`.showPreview(_ show: Bool, title: String?, subtitle: String?, confirmLabel: String?, retryLabel: String?)` Enables/disables the capture preview. If `show` has `true`, after each capture, the SDK provides a screen for the user to approve or make the capture again. For the remaining parameters, enter `nil` to use the default value or a String for a custom text.	No. The default is `false`
`.setMessageSettings(waitMessage: String?, fitTheDocumentMessage: String?, verifyingQualityMessage: String?, lowQualityDocumentMessage: String?, uploadingImageMessage: String?)` Allows customizing messages displayed in the "status" balloon during the capture and analysis process.	No. The pattern is this
`.setCompressSettings(compressionQuality: CGFloat)` Allows you to set the quality in the compression process. By default, all captures are compressed. The method expects values between 0 and 1.0 as parameters, 1.0 being the best quality compression (recommended).	No. The default is 1.0
`.setGetImageUrlExpireTime(expireTime: Time)` Allows you to customize the expiration time of the `imageUrl`. The method takes as a parameter the enum `Time` with the available times.	No. The default is `Time.DEFAULT`
`.setManualCaptureSettings(enable: Bool, time: TimeInterval)` Enables/disables manual capture. The time parameter sets the `time` for the capture mode to be enabled.	No. The default is disabled
`.enableMultiLanguage(_ enable: Bool)` Enables/disables multi-language support.	No. The default is enabled
`.setGetImageUrlExpireTime(expireTime: String)` Sets how long the image URL will last on the server until it is expired. Expect to receive a time interval between "30m" to "30d". Examples: `setGetImageUrlExpireTime("30m")`: To set minutes only `setGetImageUrlExpireTime("24h")`: To set only hour(s) `setGetImageUrlExpireTime("1h 10m")`: To set hour(s) and minute(s) `setGetImageUrlExpireTime("10d")`: To set day(s)	No. The default is `3h`
`.setMask(type: MaskType)` Sets the type of mask used in the captures. There are three types: `.``standard`, with the dotted pattern in the document format; `.``empty`, which removes the mask entirely.	No. The default is `.standard`
`.setCurrentStepDoneDelay(currentStepDoneDelay: TimeInterval)` Delay the activity after the completion of each step. This method can be used to display a success message on the screen itself after the capture, for example.	No. The default is `false`
`.setUploadSettings(UploadSettings uploadSettings)` Sets the settings for uploading documents. By enabling this option, the SDK flow will prompt the user to upload the document files instead of capturing them with the device's camera. This option also includes document quality checks.	No. By default this option is disabled, here is how to set it.
`.setResolutionSettings(resolution: Resolution)` Allows you to set the capture resolution. The method takes a parameter a Resolution, which has the following options:	No. The default is `hd1280x720`
`.setAllowedPassportCountriesList(passportList: [CountryCodes])` Enables the option to allow passports from only a certain issuing country, or, a list of countries. See the complete list at: ISO 3166-1 alpha-3 Example: `.setAllowedPassportList(passportList: [CountryCodes.BRA])`	No. Passports issued by any country are accepted by default.

Resolution	Description
`low`	Specifies appropriate capture settings for output video and audio bit rates suitable for 3G sharing
`medium`	Specifies the appropriate capture settings for the output video and audio bitrates suitable for sharing over WiFi
`high`	Specifies appropriate capture settings for high-quality video and audio output
`photo`	Specifies appropriate capture settings for high-resolution photo quality output
`inputPriority`	Specifies appropriate capture settings for high-resolution photo quality output
`hd1280x720`	Specifies the appropriate capture settings for video output at 720p quality (1280 x 720 pixels)
`hd1920x1080`	Capture settings suitable for 1080p (1920 x 1080 pixels) quality video output
`hd4K3840x2160`	Capture settings suitable for 2160p (3840 x 2160 pixels) quality video output

Parameter	Required?
document: Document Identifies which document you want to capture in the respective step	Yes
stepLabel: String? Text to be displayed at the bottom of the layout	No. There is a pattern per `Document` Type
illustration: UIImage? Illustration to be shown in the popup before the capture	No. There is a pattern per `Document` Type
audio: URL? Audio to be played at the beginning of the step Example.	No. There is a pattern per `Document` Type

Attribute	Default Value
`waitMessage: String` Message displayed when SDK is in the process of opening	"Aguarde..."
`fitTheDocumentMessage: String` Message advising to fit the document to the mask	"Encaixe o documento na marcação"
`verifyingQualityMessage: String` Message displayed when the SDK makes a request to the backend, verifying quality	"Verificando qualidade…"
`lowQualityDocumentMessage: String` Message displayed when the quality of the capture fails	"Ops, não foi possível ler as informações. Por favor, tente novamente"
`uploadingImageMessage: String` Message displayed when there is no quality check and the capture is being saved on the servers	"Enviando imagem…"
`popupDocumentSubtitleMessage: String` Text displayed in the step initialization popup	"Posicione o documento em uma mesa, centralize-o na marcação e aguarde a captura automática."

Parameter	Required?
`enable` Enables/disables this feature.	No. The default is `true`
`compress` Enables/disables file compression before uploading.	No. The default is `true`
`fileFormats` Defines the file format(s) that will be accepted for upload.	No. By default .PDF , .JPEG and .PNG are accepted
`maximumFileSize` Sets the maximum KB limit of the file to upload.	No. The default limit is 20000 KB (20MB).

Parameter	Can it be null?
`captures:[Capture]` The array with the respective captures of the parameterized documents	Yes, in case of error
type: String The class of the read document stream. This parameter is useful in an integration with our OCR route. The existing types are: `["blank", "cnh", "cnh_new", "generic", "rg", "rg_new", "rne", "rnm", "ctps", "passport, crlv, crlv_new"]`	Yes, in case of error
trackingId: String? Identifier of this run on our servers. If possible, save this field and send it along to our API. This way we will have more data about how the user behaved during the execution	Yes, if the user sets `useAnalytics = false` or the analytics calls do not work

Parameter	Can it be null?
`image: UIImage` Document image	No
`imageUrl :String` URL of the document on CAF's server. If you want this URL, keep enabled the parameter that checks the image quality	Yes, if you choose not to check the image quality
`scannedLabel :String` Label of the respective document within the following possibilities: `["blank", "cnh_back", "cnh_front", "cnh_full", "new_cnh_back", "new_cnh_front", "new_cnh_full", "crlv", "crlv_new", "generic", "rg_back", "rg_front", "rg_full", "rg_new_back", "rg_new_front", "rg_new_full", "rne_back", "rne_front", "rnm_back", "rnm_front", "ctps_back", "ctps_front", "passport"]`	No
`quality :Double` Quality inferred by the document quality algorithm, when enabled. Varies between 1.0 and 5.0	May be 0, if the SDK does not check for quality
`lensFacing: Int` Defines the face of the camera that was used. Use `DocumentDetectorResult.LENS_FACING_FRONT` or `DocumentDetectorResult.LENS_FACING_FRONT` to validate.	No

isKindOfClass()	Description	Exemple
`InvalidTokenReason`	The token entered is not valid for the corresponding product	Parameterize "test123" as token in the SDK builder
`PermissionReason`	You are missing some mandatory permission to run the SDK	Start DocumentDetector without camera permission granted
`NetworkReason`	Internet connection failure	User was without internet during facematch in FaceAuthenticator
`ServerReason`	When an SDK request receives a status code of failure	In theory, it shouldn't happen. If it does, let us know!
`StorageReason`	There is no space on the user device's internal storage	When there is no space on the internal storage while capturing the document photo