iOS Advanced SDK

This set of components is intended to provide a bridge between our complete SDK integration and rolling your own solution. The power of these components lies in their ease of use and the extreme degree of customization they allow for. While these components alone aren’t enough to complete a transaction, they will ensure the assets your customers created are of the highest quality possible, before sharing them with Berbix.

*This feature is in early release.

🚧

Does your integration require custom UI?

If you'd prefer to simplify the integration, we provide a full featured integration that should be simpler to integrate. This document focuses on advanced use cases that cannot be covered by our existing SDK.

Permissions

As a quick aside, we'll be using the Media Capture APIs on iOS, and those require additional authorization. You'll want to be sure you've completed the basic steps outlined in Requesting Authorization for Media Capture on iOS before integrating this toolkit. There are a few features included to assist with permissions, but you must ensure you have modified your Info.plist correctly to make use of this functionality.

Getting Started

❗️

This documentation assumes you are familiar with the Berbix API-Only verification flow. If you have not yet reviewed our API-Only Integration Guide, please do so now.

Use of these components all begins with the CameraSession class. Simply create an instance of this class, often in a UIViewController subclass, and configure it for the mode you intend to use.

let session = CameraSession()
session.configureFor(mode: .selfie)

The available modes are .selfie, .document, .barcodeOnly and a fourth .application that will configure the camera normally, but without creating any of the complex session processors mentioned above. We can verify the mode was set correctly like so:

if session.currentMode == .application {
    // Add your application specific views or logic
}

Adding the view to the hierarchy

With the session created and configured appropriately, we can make use of the sessionView property of our CameraSession. This property returns an instance of CameraPreview that we can use to display a real-time preview of the content from the camera.

While this step may differ depending on the integration context that you have chosen, the basic steps are to add this sessionView as a subview of another view in our hierarchy, assuming we're inside of a UIViewController that might look something like this

override func viewDidLoad() {
    view.addSubview(session.sessionView)
}

You can proceed with your typically layout configuration from this point, Auto-Layout Constraints, a layout framework, etc.

Detecting Events

Depending on the mode we've configured, we'll likely want to add a few handlers for events that may occur. We've provided a few typealias that should make working with these events a bit easier.

/// This block will be called for each frame that a barcode is detected.
///
/// - CGRect: The bounding rect of the barcode in the space of `sessionView`
/// - String: The decoded barcode data
public typealias BarcodeDetectedBlock = (CGRect, String) -> Void

/// This block will be called for each frame that a face is detected.
///
/// - CGRect: The bounding rect of the face in the space of `sessionView`
/// - CGFloat: The yaw of the face in radians. With 0 being directly facing the camera
public typealias FaceDetectedBlock = (CGRect, CGFloat) -> Void
  
/// This block will be called when a document containing text has been
/// detected and the session type is set to `.document`.
///
/// - CGRect: The bounding rect of the document in the space of `sessionView`
public typealias DocumentDetectedBlock = (CGRect) -> Void
  
/// This block will be called in response to a call to `capturePhoto`
///
/// - AVCapturePhotoOutput: The result of the call to `capturePhoto`
public typealias PhotoTakenBlock = (AVCapturePhoto) -> Void

Each of these typealias corresponds to a public var on the CameraSession instance. This means you can easily get a callback when a document is detected in any part of the frame:

session.onDocumentDetected = (documentBounds) -> {
    print("Detected document at \(documentBounds).")
}

Starting a Session

With the session configured and the view placed in our hierarchy we can actually begin a session.

session.start()

Capturing a Photo

Of course detecting all these events isn't much use unless we can also capture the frame that corresponds to that event. From within any of the callbacks described above, you may ask the CameraSession to create a high-resolution image by simply calling session.capturePhoto(). The result of this capture will be passed to the block defined by onPhotoTaken in the CameraSession instance.

Stopping a Session

Once you've made use of the components and you'd like to clean up, you can simply call stop on the CameraSession and it will clean up resources appropriately. In a UIViewController subclass you might integrate it like this:

override func viewWillDisappear(_ animated: Bool) {
    session.stop()
}