Mobbeel for developers

Mobbeel for developers

  • MobbScan
  • MobbID
  • MobbSign
  • Clients
  • FAQ

›Customization

MobbScan iOS

  • Welcome to the MobbScan SDK
  • SDK size

Configure SDK

  • Configure the iOS SDK

Migration Guides

  • Migration to 2.26.0
  • Migration to 2.19.0
  • Migration to 2.18.0
  • Migration to 2.17.0
  • Migration to 2.16.0

Getting Started

  • Initalize API
  • Scanning a document with MobbScan
  • Performing Face Matching
  • Adding a video step
  • Record a video while user scans the document
  • Getting the verification result
  • Scanning documents with NFC
  • Detect and scan MRZ
  • Detect and scan a PDF417
  • Add fields to validations in agent portal
  • Error Handling

Additional Configuration

  • MobbScan Configuration

Customization

  • Customize Detection Views
  • Customize Feedback Messages
  • Customize Unattended Process

Reference

  • Changelog

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:

PropertyTypeDefault ValueDescription
MSThemeKeyDocumentOverlayColorString#00000080Color of the overlay view (RGB/RGBA)
MSThemeKeyDocumentFrameLineWidthNumber4Line width of the detection box
MSThemeKeyDocumentFrameDefaultColorString#FFFFFFDefault color of the detection box line (RGB)
MSThemeKeyDocumentFrameDetectingStateColorString#A5DB30Color of the detection box line displayed when documents are being detected
MSThemeKeyDocumentTextColorString#FFFFFFFeedback messages font color (RGB)
MSThemeKeyDocumentTextSizeNumber14Feedback messages font size
MSThemeKeyDocumentCancelButtonColorString#FFFFFFCancel button color (RGB)
MSThemeKeyMRZDetectedTextColorString#A5DB30Color of the MRZ text when detected
MSThemeKeyStatusBarAutoBooleantrueWhether or not the status bar style should be updated based on background color (*)
MSThemeKeyStatusBarStyleStringlightStatus 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:

    ValueDescription
    NOT_DETECTEDNo document is detected
    SEARCHING_DOCUMENTThe detector is looking for a document
    DETECTED_HOLD_ONA document has been detected
    OUT_OF_OVERLAY_BOUNDSThe document is placed outside of the detection box bounds
    TOO_FARThe document is placed too far from the detection box bounds
    TOO_DARKAmbient light is too dim
    OVEREXPOSED_IMAGEAmbient light is too bright
    TOO_SPARKLYReflections or sparkles were detected on the image
    TOO_BLURREDThe image is out of focus
    BAD_DOCUMENT_TD1_FRONTThe detected document is not a valid front side for TD1 document type
    BAD_DOCUMENT_TD1_BACKThe detected document is not a valid back side for TD1 document type
    BAD_DOCUMENT_TD2The detected document is not valid as TD2 document type
    BAD_DOCUMENT_TD3The detected document is not valid as TD3 document type
  • MobbScanDetectionFeedbackResultData will contain the following data:

    PropertyDescription
    mrzThe 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:

PropertyTypeDefault ValueDescription
MSThemeKeyFaceOverlayColorString#000000Color of the overlay layer (RGB)
MSThemeKeyFaceOverlayAlphaNumber0.75Transparency of the overlay layer
MSThemeKeyFaceAnimationLineColorString#FFFFFFColor of the shape strokes of the animations (RGB)
MSThemeKeyFaceTextColorString#FFFFFFColor of the text messages (RGB/RGBA)
MSThemeKeyFaceTextBackgroundColorString#00000000Background color of the text messages (RGB/RGBA)
MSThemeKeyFaceTextShadowColorString#00000077Color of the text shadow (RGB/RGBA)
MSThemeKeyFaceTextShadowOffsetArray[2,2]Size of the text shadow
MSThemeKeyFaceCancelButtonColorString#FFFFFFColor 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:

    ValueDescription
    NOT_DETECTEDNo face is detected
    DETECTING_FACEThe system is looking for a face
    DETECTEDA face has been detected
    TOO_DARKAmbient light is too dim
    OVEREXPOSED_IMAGEAmbient light is too bright
    TOO_BLURREDThe image is out of focus
    TOO_FARThe user is too far from the camera and their face is too small
    OUT_OF_OVERLAY_BOUNDSThe user's face is not placed within the frame
    MOUTH_OCCLUSIONThe 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_STARTEDThe video recording just started (only for video modes)
    VIDEO_FINISHEDThe video recording just finished (only for video modes)
    RANDOM_MOVEMENT_STARTEDThe random movement just started (only for LIVENESS_VIDEO_PASSIVE_WITH_RANDOM_MOVEMENT)
    RANDOM_MOVEMENT_FINISHEDThe 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:

    PropertyDescription
    progressThe progress of the detection
    detectedFaceBoundsThe 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.

← MobbScan ConfigurationCustomize Feedback Messages →
  • Overview
  • Document Detection View
    • Customize Default View
    • Full Customization
  • MRZ Detection View
    • Customize Default View
    • Full Customization
  • Face Detection View
    • Customize Default View
    • Full Customization
Mobbeel for developers
Product Documentation
MobbIDMobbScanMobbSign
Connect
LinkedInFacebookX
More
FAQContact Us
Mobbeel Solutions SL
Copyright © 2025 Mobbeel Solutions SL