Customize Detection Views

Overview

MobbScan SDK can be used out of the box if the UIs that it provides for the detection process suits your needs, but chances are that the default look & feel does not. In that case, you can check this guide to fully customize your views to match your application style.

Document Detection View

Customize Default View

MobbScan offers some default views that may fit your needs. However you also might want to adjust some details. In order to ease simple customization, MobbScan defines some properties that you can override as you prefer. You just need to add a file name ms_theme.plist to your application and start overriding the default values.

The customizable properties are:

Property	Type	Default Value	Description
MSThemeKeyDocumentOverlayColor	String	#00000080	Color of the overlay view (RGB/RGBA)
MSThemeKeyDocumentFrameLineWidth	Number	4	Line width of the detection box
MSThemeKeyDocumentFrameDefaultColor	String	#FFFFFF	Default color of the detection box line (RGB)
MSThemeKeyDocumentFrameDetectingStateColor	String	#A5DB30	Color of the detection box line displayed when documents are being detected
MSThemeKeyDocumentTextColor	String	#FFFFFF	Feedback messages font color (RGB)
MSThemeKeyDocumentTextSize	Number	14	Feedback messages font size
MSThemeKeyDocumentCancelButtonColor	String	#FFFFFF	Cancel button color (RGB)
MSThemeKeyMRZDetectedTextColor	String	#A5DB30	Color of the MRZ text when detected
MSThemeKeyStatusBarAuto	Boolean	true	Whether or not the status bar style should be updated based on background color (*)
MSThemeKeyStatusBarStyle	String	light	Status bar style (light/default). Only relevant if MSThemeStatusBarAuto is false

(*) Dark backgrounds will display light style. Light backgrounds will display default style.

Full Customization

Besides, if you would rather fully customize the document detection view you must use these components:

• Detection track: the component that holds the view where the camera preview will be displayed. On top of the camera preview holder you can add all your view components to build your desired UI.
• Detection box: the area of the screen where the document should be placed to be detected.
• Feedback detection handler: the block code where you will be interpreting the detection status.

Swift

ObjectiveC

...
// declare a detection track reference
var detectionTrack: MobbScanDocumentDetectionTrack
...
// configure the custom view
detectionTrack = MobbScanDocumentDetectionTrack()
detectionTrack.cameraViewContainer = yourCustomView
MobbScanAPI.getInstance().documentDetectionTrack = detectionTrack
// configure the detection box
let detectionBox = CGRect(x: boxX, y: boxY, width: boxWidth, height: boxHeight)
MobbScanAPI.getInstance().setDocumentDetectionBoxCoordinates(detectionBox, forScreenWidth: screenWith, andScreenHeight: screenHeight)
// configure the feedback listener
MobbScanAPI.getInstance().documentDetectionFeedback = { (state, data, error) in
    // process feedback messages as you desire
}
...
// do not forget to invoke detection track lifecycle methods, typically as follow
override func viewDidAppear(_ animated: Bool) {
    super.viewDidAppear(animated)
    detectionTrack.onResume()
}
override func viewWillDisappear(_ animated: Bool) {
    detectionTrack.onPause()
    super.viewWillDisappear(animated)
}

...
// declare a detection track reference
@property (nonatomic, strong) MobbScanDocumentDetectionTrack *detectionTrack;
...
// configure the camera preview holder
self.detectionTrack = [MobbScanDocumentDetectionTrack new];
self.detectionTrack.cameraViewContainer = yourCustomView;
[[MobbScanAPI getInstance] setDocumentDetectionTrack:self.detectionTrack];
// configure the detection box
CGRect detectionBox = CGRectMake(boxX, boxY, boxWidth, boxHeight);
[[MobbScanAPI getInstance] setDocumentDetectionBoxCoordinates:detectionBox forScreenWidth:screenWidth andScreenHeight:screenHeight];
// configure the feedback listener
[[MobbScanAPI getInstance] setDocumentDetectionFeedback:^(MobbScanDetectionFeedbackResult result, MobbScanDetectionFeedbackResultData * _Nullable resultData, NSError * _Nullable error) {
  // process feedback messages as you desire
}];
...
// do not forget to invoke detection track lifecycle methods, typically as follow
- (void) viewDidAppear:(BOOL)animated {
    [super viewDidAppear:animated];
    [self.detectionTrack onResume];
}
- (void) viewWillDisappear:(BOOL)animated {
    [self.detectionTrack onPause];
    [super viewWillDisappear:animated];
}

Warning!
When you use your own view you are in charge of its lifecycle, so it is important that you call the detection track methods to handle the camera resource properly or you will face unexpected issues.

Additionally, you can set this optional parameter:

• Detection orientation: whether you will be using a portrait or landscape screen. Default value is landscape but you can use either AVCaptureVideoOrientationPortrait or AVCaptureVideoOrientationLandscapeRight.

Swift

ObjectiveC

MobbScanAPI.getInstance().setDetectionOrientation(AVCaptureVideoOrientation.portrait)

[[MobbScanAPI getInstance] setDetectionOrientation:AVCaptureVideoOrientationPortrait];

Warning!
Please be sure that you configure those components before launching the document detection process.

Document Detection Feedback Handling

As long as the detection process is alive, MobbScanDocumentDetectionFeedback will be invoked many times to provide you with information about its status. This info is presented by these parameters:

• MobbScanDetectionFeedbackResult is the result of the detection. Possible values are:

  Value	Description
  NOT_DETECTED	No document is detected
  SEARCHING_DOCUMENT	The detector is looking for a document
  DETECTED_HOLD_ON	A document has been detected
  OUT_OF_OVERLAY_BOUNDS	The document is placed outside of the detection box bounds
  TOO_FAR	The document is placed too far from the detection box bounds
  TOO_DARK	Ambient light is too dim
  OVEREXPOSED_IMAGE	Ambient light is too bright
  TOO_SPARKLY	Reflections or sparkles were detected on the image
  TOO_BLURRED	The image is out of focus
  BAD_DOCUMENT_TD1_FRONT	The detected document is not a valid front side for TD1 document type
  BAD_DOCUMENT_TD1_BACK	The detected document is not a valid back side for TD1 document type
  BAD_DOCUMENT_TD2	The detected document is not valid as TD2 document type
  BAD_DOCUMENT_TD3	The detected document is not valid as TD3 document type

• MobbScanDetectionFeedbackResultData will contain the following data:

  Property	Description
  mrz	The detected MRZ (only for MRZ detection flow)

• NSError: usually will be nil unless something went wrong.

MRZ Detection View

Customize Default View

All the explanations in this previous section also applies here.

Full Customization

The MRZ view full customization process is very similar to the previous one. You will need to follow these steps:

1. Create an instance of MobbScanDocumentDetectionTrack and set the view you want to use to display the camera preview. After creating this, let the MobbScan API know that you have your own detection track by setting its property documentDetectionTrack.
2. Provide the area of the view where you expect the user to place the document's MRZ.
3. Finally, you will configure a MobbScanDocumentDetectionFeedback block or closure in MobbScanAPI to receive detection feedback messages from MobbScanAPI so that you can update your view as desired.

Swift

ObjectiveC

...
// declare a detection track reference
var detectionTrack: MobbScanDocumentDetectionTrack
...
// configure the custom view
detectionTrack = MobbScanDocumentDetectionTrack()
detectionTrack.cameraViewContainer = yourCustomView
MobbScanAPI.getInstance().detectionTrack = detectionTrack
// configure the mrz detection box
let mrzBox = CGRect(x: boxX, y: boxY, width: boxWidth, height: boxHeight)
MobbScanAPI.getInstance().setMRZDetectionCoordenates(mrzBox, forScreenWidth: screenWith, andScreenHeight: screenHeight)
// configure the feedback listener
MobbScanAPI.getInstance().documentDetectionFeedback = { (state, data) in
    // process feedback messages as you desire
}
...
// do not forget to invoke detection track lifecycle methods, typically as follow
override func viewDidAppear(_ animated: Bool) {
    super.viewDidAppear(animated)
    detectionTrack.onResume()
}
override func viewWillDisappear(_ animated: Bool) {
    detectionTrack.onPause()
    super.viewWillDisappear(animated)
}

...
// declare a detection track reference
@property (nonatomic, strong) MobbScanDocumentDetectionTrack *detectionTrack;
...
// configure the camera preview holder
self.detectionTrack = [MobbScanDocumentDetectionTrack new];
self.detectionTrack.cameraViewContainer = yourCustomView;
[[MobbScanAPI getInstance] setDocumentDetectionTrack:self.detectionTrack];
// configure the detection box
CGRect mrzBox = CGRectMake(boxX, boxY, boxWidth, boxHeight);
[[MobbScanAPI getInstance] setMRZDetectionCoordenates: mrzBox forScreenWidth:screenWidth andScreenHeight:screenHeight];
// configure the feedback listener
[[MobbScanAPI getInstance] setDocumentDetectionFeedback:^(MobbScanDetectionFeedbackResult result, MobbScanDetectionFeedbackResultData * _Nullable resultData, NSError * _Nullable error) {
  // process feedback messages as you desire
}];
...
// do not forget to invoke detection track lifecycle methods, typically as follow
- (void) viewDidAppear:(BOOL)animated {
    [super viewDidAppear:animated];
    [self.detectionTrack onResume];
}
- (void) viewWillDisappear:(BOOL)animated {
    [self.detectionTrack onPause];
    [super viewWillDisappear:animated];
}

Face Detection View

Customize Default View

Chances are that you like how the default UI looks but you would like to slightly modify it just to match your brand colors. You can achieve this by overriding its properties. You only need to add a file named ms_theme.plist to your project and adjust the values as it suits you best.

These are the properties that your file may contains:

Property	Type	Default Value	Description
MSThemeKeyFaceOverlayColor	String	#000000	Color of the overlay layer (RGB)
MSThemeKeyFaceOverlayAlpha	Number	0.75	Transparency of the overlay layer
MSThemeKeyFaceAnimationLineColor	String	#FFFFFF	Color of the shape strokes of the animations (RGB)
MSThemeKeyFaceTextColor	String	#FFFFFF	Color of the text messages (RGB/RGBA)
MSThemeKeyFaceTextBackgroundColor	String	#00000000	Background color of the text messages (RGB/RGBA)
MSThemeKeyFaceTextShadowColor	String	#00000077	Color of the text shadow (RGB/RGBA)
MSThemeKeyFaceTextShadowOffset	Array	[2,2]	Size of the text shadow
MSThemeKeyFaceCancelButtonColor	String	#FFFFFF	Color of the Cancel button (RGB/RGBA)

Full Customization

In case you want to modify the user interface of the face validation process so it fits your application look and feel, you should follow these indications.

Note: If you want to customize feedback messages, you should check this section

In order to achieve this customization you need to add some configuration previous to the validation method call:

1. First of all you will need to create an instance of MSDetectionTrack and set the view you want to use to display the camera preview. After creating this, let MobbScanAPI know that you have your own detection track.
2. MobbScan checks the position of the user's face to improve the quality of the captured picture, so you must provide the area of the view where you expect the user's face to be placed.
3. Finally, you will configure a MSFaceDetectionFeedback in MobbScan API that is a listener of the feedback messages so that you can update your view as you desire.

Swift

ObjectiveC

...
// declare a detection track reference
var detectionTrack: MSDetectionTrack
...
// 1. configure the custom view
detectionTrack = MSDetectionTrack()
detectionTrack.cameraViewContainer = yourCustomView
MobbScanAPI.getInstance().detectionTrack = detectionTrack
// 2. configure the detection box
MobbScanAPI.getInstance().detectionBox = CGRect(x: boxX, y: boxY, width: boxWidth, height: boxHeight)
// 3. configure the feedback listener
MobbScanAPI.getInstance().faceDetectionFeedback = { (state, data) in
    // process feedback messages as you desire
}
...
// do not forget to invoke detection track lifecycle methods, typically as follow
override func viewDidAppear(_ animated: Bool) {
    super.viewDidAppear(animated)
    detectionTrack.onResume()
}
override func viewWillDisappear(_ animated: Bool) {
    detectionTrack.onPause()
    super.viewWillDisappear(animated)
}

...
// declare a detection track reference
@property (nonatomic, strong) MSDetectionTrack *detectionTrack;
...
// 1. configure the custom view
self.detectionTrack = [MSDetectionTrack new];
self.detectionTrack.cameraViewContainer = yourCustomView;
[MobbScanAPI getInstance].detectionTrack = self.detectionTrack;
// 2. configure the detection box
[MobbScanAPI getInstance].detectionBox = CGRectMake(boxX, boxY, boxWidth, boxHeight);
// 3. configure the feedback listener
[MobbScanAPI getInstance].faceDetectionFeedback = ^(MSFaceDetectionFeedbackState state, MSFaceDetectionFeedbackData * _Nullable data) {
    // process feedback messages as you desire
};
...
// do not forget to invoke detection track lifecycle methods, typically as follow
- (void) viewDidAppear:(BOOL)animated {
    [super viewDidAppear:animated];
    [self.detectionTrack onStart];
}
- (void) viewWillDisappear:(BOOL)animated {
    [self.detectionTrack onPause];
    [super viewWillDisappear:animated];
}

Warning: When you use your own view you are in charge of its lifecycle so it is important that you call the detection track methods to handle the camera resource properly or you will face unexpected issues.

Face Detection Feedback Handling

MSFaceDetectionFeedback will be invoked many times along the face detection process receiving the following two parameters:

• MSFaceDetectionFeedbackState is the result of the detection. Possible values are:

  Value	Description
  NOT_DETECTED	No face is detected
  DETECTING_FACE	The system is looking for a face
  DETECTED	A face has been detected
  TOO_DARK	Ambient light is too dim
  OVEREXPOSED_IMAGE	Ambient light is too bright
  TOO_BLURRED	The image is out of focus
  TOO_FAR	The user is too far from the camera and their face is too small
  OUT_OF_OVERLAY_BOUNDS	The user's face is not placed within the frame
  MOUTH_OCCLUSION	The user's mouth seems to be obstructed (probably by a health mask)
  READY_TO_RECORD*	The system is ready to start recording the video (only for video modes)
  VIDEO_STARTED	The video recording just started (only for video modes)
  VIDEO_FINISHED	The video recording just finished (only for video modes)
  RANDOM_MOVEMENT_STARTED	The random movement just started (only for LIVENESS_VIDEO_PASSIVE_WITH_RANDOM_MOVEMENT)
  RANDOM_MOVEMENT_FINISHED	The random movement just finished (only for LIVENESS_VIDEO_PASSIVE_WITH_RANDOM_MOVEMENT)

  * READY_TO_RECORD will be notified when the system is happy with the detected face (good conditions). It can be used to display an animation or countdown while the instructions to move the head are displayed. After 5 seconds, the VIDEO_STARTED status will be notified for the LIVENESS_VIDEO_HEAD_MOVEMENT mode, whereas it will be notified immediately for the LIVENESS_VIDEO_PASSIVE and LIVENESS_VIDEO_PASSIVE_WITH_RANDOM_MOVEMENT modes, as the user is not required to do any further interaction.

• MSFaceDetectionFeedbackData will contain the following data:

  Property	Description
  progress	The progress of the detection
  detectedFaceBounds	The bounds within the face was detected

This information will allow you to build your own user interface on top of the view you set as the camera preview holder by adding animations, labels or whatever you need to guide the user through this process.