ScanEngine

The entry point of the Scantrust Processing is the ScanEngine, this class does all the heavy lifting, setting up the camera and the preview (view finder) view, running the image processing on the incoming frames and reporting the various outcomes.

Setup

The ScanEngine class provides easy way to setup and start the camera with preview view, receive scan feedback and scan session update.

To get started with ScanEngine, you need to extend the ScanEngineViewController class for your view controller along with two delegates.

Swift

import ScantrustSDK

class ViewController: ScanEngineViewController, ScanEngineFeedbackReceiverProtocol, AuthenticationSessionEndedDelegateProtocol {

Objective-C

#import <ScantrustSDK/ScanEngine.h>

@interface ViewContorller : ScanEngineViewController

In viewDidLoad() method, setup scan engine with delegates like below.

Swift

import ScantrustSDK

class ViewController: ScanEngineViewController, ScanEngineFeedbackReceiverProtocol, AuthenticationSessionEndedDelegateProtocol {

  private var scanEngine: ScanEngine?

  override func viewDidLoad() {
    super.viewDidLoad()
    if scanEngine != nil {
        return
    }

    scanEngine = ScanEngine(endSesionDelegate: self, feedbackReceiver: self)
    // Considering you have UIView called overlayView setup in storyboard/XIB or in code
    scanEngine?.previewView = overlayView
  }

}

Objective-C

#import <ScantrustSDK/ScanEngine.h>

@interface ViewContorller() <ScanEngineFeedbackReceiverProtocol, AuthenticationSessionEndedDelegateProtocol> {
    ScanEngine* _scanEngine:
}

@implementation ViewController
#pragma mark - View life cycle methods
- (void)viewDidLoad {
    [super viewDidLoad];
    if (_scanEngine) {
        return;
    }
    _scanEngine = [[ScanEngine alloc] initWithEndSesionDelegate:self feedbackReceiver:self];
    // Considering you have UIView called preview setup in storyboard/XIB or in code
    [_scanEngine setPreviewView:_previewView];
}
@end

Here is what you are doing.

• Create a private variable to setup the scan engine.
• In viewDidLoad method initialize the scan engine with delegates.
• Setup a preview view to show the camera preview. SDK does provides PreviewView to setup the camera preview in Storyboard or create a new instance. You can also extend OverlaidPreview or PreviewView to provide your own view.

PreviewView

SDK provides a basic PreviewView a subclass of UIView to represent the camera preview and extendes from UIView Which hold the preview layer to customize and view the camera frames. You can also extend PreviewView to provide your own view by using extraSetup.

For default usage of PreviewView, you can use the OverlaidPreview class to setup the camera preview in Storyboard or create a new instance.

PreviewView has 4 different states based on camera zoom level which is represented by PreviewViewState enum. It also provides a method to notify when the preview state changes. The PreviewViewState can be any one of the following.

• PreviewViewStateZoomedOut: The camera is zoomed out and the preview is shown with 1x zoom.
• PreviewViewStateZoomedIn: The camera is zoomed in and the preview is shown with default zoom factor.
• PreviewViewStates_Zooming: The camera is zooming in.
• PreviewViewStates_Undefined: Initial state of the preview view.

Scanner Handling

The ScanEngine provides following method to control the camera and it is up to the user to determine when to start and stop the camera or processing. But in general the camera is started in the viewWillAppear() method and stopped on viewWillDisappear()

The scanning process is started by calling start method from ScanEngine. This method will start the camera frame processing.

Swift

override func viewWillAppear(_ animated: Bool) {
    super.viewWillAppear(animated)
    scanEngine?.reset()
    scanEngine?.start()
}

override func viewWillDisappear(_ animated: Bool) {
    super.viewWillDisappear(animated)
    scanEngine?.stopAuthenticationSession()
}

Objective-C

- (void)viewDidAppear:(BOOL)animated {
    [super viewDidAppear:animated];
    if (_scanEngine) {
      [_scanEngine reset];
      [_scanEngine start];
    }
}

- (void)viewWillDisappear:(BOOL)animated {
    [super viewWillDisappear:animated];
    if (_scanEngine) {
      [_scanEngine stop];
    }
}

Public Methods	Description
- (void)start;	Starts the underlying camera object, its preview and starts the Scantrust frame processing.
- (void)stop;	stops the preview and stops the Scantrust frame processing.
- (void)reset;	Resets the Scantrust frame processing. Should be used when the frame processing has been paused. Note: this will not have an impact on the camera or its preview, but will restart the response flow.
- (void)turnTorchOnOff:(BOOL)turnOn;	Turns the torch on or off depending on the value of turnOn.

Delegates

The session results or feedbacks of scan sessions are organized as follows and provided as delegate methods

Authentication Session Ended Delegate

AuthenticationSessionEndedDelegateProtocol helps to receive the session end result. It can be defined as below.

AuthenticationSessionEndedDelegate Method	Description
- (void)authenticationSessionEndedCandidateFound:(AuthenticationScanCandidate*) candidate	called when a candidate ready for authentication has been found (called after frameAnalysedWithResult)
- (void)authenticationSessionEndedTimeOut:(AuthenticationScanCandidate*) bestCandidate	called when the authentication session timed out (no scan with a good enough quality has been found) the best candidate is provided
- (void)authenticationSessionEndedTimeOutWithoutCandidate:(BasicScanCandidate*) content	called when the authentication session timed out (no scans have been found at all) the content is provided
- (void)authenticationSessionEndedError	called when an error occurred during the auth process preventing the session to continue (no parameters
- (void)authenticationSessionEndedCodeNotFound:(BasicScanCandidate*) content	called when the extended id of the code doesn't exist on the system
- (void)authenticationSessionEndedNoAuthCode:(BasicScanCandidate*) content	called when a code with no authentication feature belonging to Scantrust is read
- (void)authenticationSessionEndedThirdPartyContent: (NSString*) content	called when a code that is not a scantrust secure code (e.g. third party or ID only) is read

ScanEngine Feedback Receiver

Define the states of the individual scans and reported via ScanEngineFeedbackReceiverProtocol.

| Scan Feedback | Description | | --------------------------------- | ------------------------------------------------------------------------------------------------------------- | --- | | -(void)frameOk | The code belongs to Scantrust and all the constraints are met | | -(void)codeIsTooSmall; | A code belonging to Scantrust has been detected, but the minimum size constraint has failed | | -(void)codeHasGlare | A code belonging to Scantrust has been detected, but has been classified as too blurry | | | -(void)secureGraphicIsNotInFrame; | A hybrid code belonging to Scantrust has been detected, but the external fingerprint zone is not in the frame |