Skip to content

ilyashvedikov/vouched-ios

 
 

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

82 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Vouched

Version License Platform

Run Example

Clone this repo and change directory to example

git clone https://github.com/vouched/vouched-ios

cd vouched-ios/Example

Then, follow steps listed on the example README

Prerequisites

  • An account with Vouched
  • Your Vouched Public Key

Install

Add the package to your existing project's Podfile

pod 'Vouched', 'VOUCHED_VERSION'

Getting Started

This section will provide a step-by-step to understand the Vouched SDK through the Example.

Note:  There are two options to run verification process flow:
- Use Camera Helper to obtain capture results. See corresponding details for VouchedCameraHelper. 
- Use raw API to perform all the checks.
  1. Get familiar with Vouched

  2. Run the Example

    • Go through the verification process but stop after each step and take a look at the logs. Particularly understand the Job data from each step.
    print(job)
  3. Modify the SampleBufferDelegate

    • Locate the captureOutput in each Controller and make modifications.

      • Add custom logic to display data or control the navigation
    • Locate the Vouched detectors and add logging

      • cardDetect?.detect(sampleBuffer)
      • barCodeDetect?.detect(sampleBuffer, cameraPosition: .back)
      • faceDetect?.detect(sampleBuffer)
  4. Tweak AVCapture settings Better images lead to better results from Vouched AI

  5. You are ready to integrate Vouched SDK into your app

Reference

VouchedCameraHelper

This class is introduced to make it easier for developers to integrate VouchedSDK and provide the optimal photography. The helper takes care of configuring the capture session, input, and output.

Initialize

You can initialize the helper by specifying a Detector that you wish to use. Note how some of the controllers have a convenience method configureHelper(_ detector: Detector.Type) to simplify the configuration of the helper.

let helper = VouchedCameraHelper(with detector: Detector.Type, helperOptions: VouchedCameraHelperOptions, detectionOptions: [VouchedDetectionOptions], in: UIView)
Observe Results

There are two helper methods that serve as delegates to obtain capturing results

func withCapture(delegate: @escaping ((CaptureResult) -> Void)) -> VouchedCameraHelper
Parameter Type Nullable
Closure(CaptureResult ) false
func observeBoundingBox(observer: @escaping ((BoundingBox) -> Void)) -> VouchedCameraHelper
Parameter Type Nullable
Closure(BoundingBox) false
Run

In order to start capturing, put the following code:

helper.startCapture()

Once the results are ready to process/submit, stop capturing:

helper.stopCapture()
Usage

Typical usage is as following:

let helper = VouchedCameraHelper(with: .id,
                                 detectionOptions: [.cardDetect(CardDetectOptionsBuilder().withEnableDistanceCheck(false).build())],
                                 in: previewContainer)?
    .withCapture(delegate: { (result) in
        switch result {
        case .empty:
            ...
        case .id(let result):
            ...
        default:
            break
        }
    })

VouchedDetectionManager

This class is introduced to help guide the ID verification modes by processing job results returned by the Vouched API service, and generating the appropriate modes that are needed to complete ID verification. This is particularly important if you are verifying identities in countries where some of the information needed for verification is on the back side of the ID, the detection manager will prompt the user to turn the card around to capture that information.

Initialize
    let helper: VouchedCameraHelper
    let session: VouchedSession
    let config = VouchedDetectionManagerConfig(session: session)
    let callbacks = DetectionCallbacks
    config.callbacks = callbacks
    let detectionMgr = VouchedDetectionManager(helper: helper, config: config)

See CardDetectOptions for details

Run

In order to start detection, put the following code:

    detectionMgr.startDetection()

If there is a need to capture additional info the following closure will be called :

    let callbacks = DetectionCallbacks { change in
        let alert = UIAlertController(title: nil, message: "Turn ID card over to backside", preferredStyle: .alert)
        let ok = UIAlertAction(title: "OK", style: .default, handler: { _ in
            change.completion(true)
        })
        alert.addAction(ok)
        self.present(alert, animated: true)
    }

Once the detection process is finished and there is a Job result the following closure will be called:

    let callbacks: DetectionCallbacks
    callbacks.detectionComplete = { result in
        switch result {
        case .success(let job):
                print("\(job)")
        case .failure(let err):
            print("Error: \(err)")
        }

Examine the extension IdViewControllerV2 : VouchedDetectionManager in the example app to see how this mechanism can be implemented.

VouchedSession

This class handles a user's Vouched session. It takes care of the API calls. Use one instance for the duration of a user's verification session.

Initialize
let session = VouchedSession(apiKey: "PUBLIC_KEY", groupId: "GROUP_ID")
Parameter Type Nullable
String false
String true
Initializing with a token
let session = VouchedSession(apiKey: "PUBLIC_KEY", groupId: "GROUP_ID", sessionParameters: VouchedSessionParameters(token: "TOKEN"))
POST Front Id image
let job = try session.postFrontId(detectedCard: detectedCard, details: details)
Parameter Type Nullable
CardDetectResult false
Params true

Returns - Job

POST Selfie image
let job = try session.postFace(detectedFace: detectedFace)
Parameter Type Nullable
FaceDetectResult false

Returns - Job

POST confirm verification
let job = try session.postConfirm()

Returns - Job

POST re-verification
let job = try session.postReverify(jobID: String, userPhoto: String)

Returns - Job

Parameter Type Nullable
jobID false
userPhoto (base64 encoded string) false

CardDetect

This class handles detecting an ID (cards and passports) and performing necessary steps to ensure image is Step.postable.

Initialize
let cardDetect = CardDetect(options: CardDetectOptionsBuilder().withEnableDistanceCheck(true).build())
Parameter Type Nullable
CardDetectOptions false
Process Image
let detectedCard = cardDetect?.detect(sampleBuffer)
Parameter Type Nullable
CVImageBuffer false

Returns - CardDetectResult

FaceDetect

This class handles detecting a face and performing necessary steps to ensure image is Step.postable.

Initialize
let faceDetect = FaceDetect(options: FaceDetectOptionsBuilder().withLivenessMode(.distance).build())
Parameter Type Nullable
FaceDetectOptions false
Process Image
let detectedFace = faceDetect?.detect(sampleBuffer)
Parameter Type Nullable
CVImageBuffer false

Returns - FaceDetectResult

Types

BoundingBox

The bounding box of detected ID card for the output from Card Detection.

public struct BoundingBox {
    public let box: CGRect?
    public let imageSize: CGSize
}
CardDetectResult

The output from Card Detection and used to submit an ID.

struct CardDetectResult {
    public let image: String?
    public let distanceImage: String?
    public let step: Step
    public let instruction: Instruction
    public let boundingBox: CGRect?
}
FaceDetectResult

The output from Face Detection and used to submit a Selfie.

struct FaceDetectResult {
    public let image: String?
    public let distanceImage: String?
    public let step: Step
    public let instruction: Instruction
}
Params

The parameters that are used to submit a Job.

struct Params: Codable{
    var firstName: String?
    var lastName: String?
    var email: String?
    var phone: String?
    var birthDate: String?
    var properties: [Property]?
    var idPhoto: String?
    var userPhoto: String?
    var idDistancePhoto: String?
    var userDistancePhoto: String?
}
CardDetectOptions

The options for Card Detection.

class CardDetectOptionsBuilder {
    public func withEnableDistanceCheck(_ enableDistanceCheck: Bool) -> CardDetectOptionsBuilder { ... }
    public func withEnhanceInfoExtraction(_ enhanceInfoExtraction: Bool) -> CardDetectOptionsBuilder
    
    public func build() -> CardDetectOptions { ... }
}

The VouchedDetectionManager can increase your verification abilities by recognizing additional sources of information based on the ID that your user submits. You can enable this behavior by using .withEnhanceInfoExtraction(true) when setting

FaceDetectOptions

The options for Face Detection.

class FaceDetectOptionsBuilder {
    public func withLivenessMode(_ livenessMode: LivenessMode) -> FaceDetectOptionsBuilder { ... }

    public func build() -> FaceDetectOptions { ... }
}
RetryableError

An enum to provide an optional baseline of Verification Error(s) for a given Job.

enum RetryableError: String {
    case invalidIdPhotoError
    case blurryIdPhotoError
    case glareIdPhotoError
    case invalidUserPhotoError
}
VouchedCameraMode

An enum to provide mode for VouchedCameraHelper

public enum VouchedCameraMode {
    case id
    case barcode(String, DetectorOptions)
    case selfie
}
VouchedCameraHelperOptions

List of options to alter image processing for VouchedCameraHelper

public struct VouchedCameraHelperOptions {
    public static var usePhotoCapture: VouchedCameraHelperOptions
    public static var cropIdImage: VouchedCameraHelperOptions
}
VouchedDetectionOptions

An enum to provide settings for ID/Selfie detection for VouchedCameraHelper

public enum VouchedDetectionOptions {
    case cardDetect(CardDetectOptions)
    case faceDetect(FaceDetectOptions)
}
Parameter Type Nullable
CardDetectOptions false
FaceDetectOptions false
CaptureResult

An enum to deliver detection results

public enum CaptureResult {
    case empty
    case id(DetectionResult)
    case selfie(DetectionResult)
    case barcode(DetectionResult)
}
Parameter Type Nullable
DetectionResult false
DetectionResult

Generic protocol, used to submit detection results

public protocol DetectionResult {
    func params() throws -> Params
}

Debugging/Logging

Configure VouchedLogger to the destination and level desired. If not configured, VouchedLogger defaults to .none and .error

VouchedLogger.shared.configure(destination: .xcode, level: .debug)

Destinations - where the log output is written

  • .xcode (Xcode output)
  • .console (Console app via os_log)
  • .none

Levels - the severity of the log

  • .debug
  • .info
  • .error

The level is inclusive of more severe logs. i.e - .debug will also log .info and .error

License

Vouched is available under the Apache License 2.0 license. See the LICENSE file for more info.

About

No description, website, or topics provided.

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published

Languages

  • Swift 96.2%
  • Ruby 3.8%