• About TrustVision
  • Android SDK
  • Flutter SDK
  • React Native SDK
  • Web SDK
  • API Client Libraries
  • eKYC Platform
  • Integration Case Studies
  • TS eKYC/FA App
TrustVision API Documentation

iOS 1.x.x Full

OVERVIEW

TrustVision SDK is an android SDK for TrustVision Engine. It provides these features:

  • Start full flow
  • Capture ID and Selfie.
  • ID and selfie matching.
  • Liveness checking.
  • OCR and also QR scanner.

Specifications

  • Xcode version 10.2+
  • target iOS version 11+
  • swift version: 5

Integration Steps

1. Adding the SDK to your project

  • Add required frameworks to project under Frameworks, Libraries, and Embedded Content with embed mode is set to Do Not Embed
    • TrustVIsionSDK.framework
    • TrustVisionAPI.framework
  • Add TrustVisionSDK.bundle bundle to Copy Bundle Resources
alt text
  • Add google services json file to project

    • GoogleService-Info.plist
  • Add key to info.plist:

    <key>NSCameraUsageDescription</key>
    <string>Open camera</string>
    

2. Initialize SDK

To initialize the SDK, add the following line to your app before calling any other SDK . For example, you can add it to the viewDidLoad method of the application class.

swift
    override func viewDidLoad() {
        super.viewDidLoad()

        TrustVisionSdk.initialize(
                accessKeyId: accessKey,
                accessKeySecret: secretKey,
                isForced: false,
                success: {

                }, failure: { (error) in

        })
    }

After the SDK is initalized, use this method to get list supported ID.

swift
do {
    let cardTypes: [TSCardType] = try TrustVisionSdk.getCardTypes()
} catch error {

}

3. Start transaction (India market only)

Start transaction should be called when start new user journey.

swift
TrustVisionSdk.startTransaction(
        referenceID: referenceID,
        success: { (transactionId) in

        }, failure: { (error) in

})

where:

  • referenceID: Nullable. The referenceID is optional

4. Start the SDK

The SDK provides some built in Activities example activity to capture id, selfie, liveness...

4.0. Start full flow

4.0.1. Set config parameters
swift
let config = TVSDKConfig.defaultConfig()

Options:

  • cardType: TVCardType. List of supported cards can be found by let cardTypes: [TSCardType] = try TrustVisionSdk.getCardTypes()
  • actionMode: ActionMode. Action mode
  • livenessMode: TVLivenessMode. Liveness mode
  • isEnableSound: Bool. Sound should be played or not
  • isEnableVerifyPortraitSanity: Bool. Check id card sanity or not
  • isEnableVerifyIDSanity: Bool. Check id card sanity or not
  • isIdCardTamperingDetectionEnable: Bool. Check id card tampering or not
  • selfieCameraMode: TVCameraOption. Camera mode
4.0.2. Start flow
swift
let vc = try TrustVisionSdk.newCameraViewController(config: config) { (result, error) in
    print("[SDK result] \(String(describing: result?.description))")
}
self.present(vc, animated: true, completion: nil)

where:

  • config: TVSDKConfig
  • success method that will be called in case success. Parameters:
    • result : TVDetectionResult. Use all fields
  • failure: FailureCallback
  • cancellation: CancellationCallback

4.1. Capture the ID

The id capturing activity will show the camera to capture image, preview the image, upload image and then do OCR. To start the id capturing activity.

4.1.1. Set config parameters

swift
let config: TVIdCardConfiguration = TVIdCardConfig()
config.idCardSide = TVCardSide.front
config.cardType = selectedCardType
confg.isEnableSound = false

Options:

  • cardType: TVCardType. List of supported cards can be found by let cardTypes: [TSCardType] = try TrustVisionSdk.getCardTypes()
  • cardSide: TVCardSide. Card side to capture
  • isEnableSound: Bool. Sound should be played or not
  • isSanityRequired: Bool. Check id card sanity or not
  • isReadBothSide: Bool. If true then the sdk will capture both side if possible; otherwise, then the card side defined in cardSide will be used
  • isIdCardTamperingDetectionEnable: Bool. Check id card tampering or not
4.1.2. Start id capturing from configuration
swift
let vc = TrustVisionSdk.startIdCapturing(configuration: config, success: { (result) in

}, failure: { (error) in

}, cancellation: {
    // sdk is canceled
})

where:

  • configuration: TVIdCardConfiguration
  • success method that will be called in case success. Parameters:
    • result : TVDetectionResult. Use the following fields:
      • cardInfoResult
      • frontIdImageId
      • backIdImageId
      • idCardTamperingResult
      • idSanityResult
      • frontIdImage
      • backIdImage
  • failure: FailureCallback
  • cancellation: CancellationCallback

4.2. Capture the selfie

The selfie capturing activity will show the camera to capture image, preview the image, upload image, verify sanity (blurry, too bright, too dark, not white background...), and verify liveness. To start the selfie capturing activity.

4.2.1. Set config parameters

swift
let config: TVSelfieConfiguration = TVSelfieConfiguration()
config.cameraOption = TVCameraOption.front
confg.isEnableSound = false
config.isSanityRequired = true
config.livenessMode = TVLivenessMode.passive

Options:

  • cameraOption: set the camera mode TVCameraOption.
  • isEnableSound: Sound should be played or not.
  • livenessMode: set the liveness verification mode TVLivenessMode
  • isSanityRequired: The sanity verification should required or not. (white background check)
4.2.2. Start selfie capturing from configuration
swift
let vc = TrustVisionSdk.startSelfieCapturing(configuration: config, success: { (result) in

}, failure: { (error) in

}, cancellation: {
    // sdk is canceled
})

where:

  • configuration: TVSelfieConfiguration

  • success method that will be called in case success. Parameters:

    • result : TVDetectionResult . Use the following fields:

      • livenessResult
      • selfieSanityResult
      • selfieImageId
      • selfieImage
  • failure: FailureCallback

  • cancellation: CancellationCallback

4.3. Face Matching

The face matching does not need an hosted activity, the SDK will send an asynchronous request to server and send back the face-matching response

Send face-matching request

swift
TrustVisionSDK.matchFace(imageId1, imageId2, success: { (result) in

}, failure: { (error) in

})

where:

  • imageId1: Nullable. The image id got from selfie capturing
  • imageId2: Nullable. The image id got from front side ID capturing
  • success method that will be called in case success. The success method has one parameter.
    • result : TVCompareFacesResult
  • failure: FailureCallback

4.4. Id sanity checking error handling

swift
// [FlowStartingFunc]: newCameraViewController, startIdCapturing

let vc = TrustVisionSdk.[FlowStartingFunc](configuration: config, success: { (result) in
    if let sanityError = result.idSanityResult?.error {
        switch sanityError.errorCode {
        case "image_too_blur":
            // Image is too blurry
        case "image_too_dark":
            // Image is too dark
        case "image_too_bright":
            // Image is too bright
        case "image_has_hole":
            // Image has holes
        case "image_has_cut":
            // Images has been cut
        case "image_has_hole_and_cut":
            // Images has holes and has been cut
        }
    }
}, failure: { (error) in
    // errors
}, cancellation: {
    // sdk is canceled
})

4.5. Selfie sanity checking error handling

swift
// [FlowStartingFunc]: newCameraViewController, startSelfieCapturing

let vc = TrustVisionSdk.[FlowStartingFunc](configuration: config, success: { (result) in
    if let sanityError = result.selfieSanityResult?.error {
        switch sanityError.errorCode {
        case "image_too_blur":
            // Image is too blurry
        case "image_too_dark":
            // Image is too dark
        case "image_too_bright":
            // Image is too bright
        case "not_white_background":
            // The background is not white enough
        case "not_qualified":
            // The face is not qualified, could be occluded, covered or having something unusal
        case "image_has_multiple_faces":
            // Image has multiple faces
        case "image_has_no_faces":
            // Image does not have any face
        case "right":
            // Face is looking to the right
        case "left":
            // Face is looking to the left
        case "open_eye,closed_eye":
            // Right eye is closed
        case "closed_eye,open_eye":
            // Left eye is closed
        case "open_eye,sunglasses":
            // Sunglass covers the right eye
        case "sunglasses,open_eye":
            // Sunglass covers the left eye
        case "closed_eye,closed_eye":
            // Both eyes are closed
        case "closed_eye,sunglasses":
            // Left eye is closed, sunglass covers the right eye
        case "sunglasses,closed_eye":
            // Sunglass covers the right eye, right eye is closed
        case "sunglasses,sunglasses":
            // Sunglasses cover both eyes
        }
    }
}, failure: { (error) in
    // errors
}, cancellation: {
    // sdk is canceled
})

4.6. Error Handling

swift
// [FlowStartingFunc]: newCameraViewController, startIdCapturing, startSelfieCapturing, matchFace

let vc = TrustVisionSdk.[FLowStartingFunc](configuration: config, success: { (result) in
    // result
}, failure: { (error) in
    switch error.errorCode {

    // pre-defined errors
    case "authentication_missing_error",
         "network_error",
         "internal_error",
         "timeout_error":

    // server errors
    default:
            switch error.errorCode {

            // Id capturing errors
            case "incorrect_card_type":
                // the input image is not same type with selected card
            case "nocard_or_multicard_image":
                // the input image is no card or multicard detected

            // Selfie capturing and faces matching errors
            case "image_has_no_faces":
                // face not detected in selfie image
            case "image_has_multipe_faces":
                // multiple faces are detected in selfie image

            // Common errors
            case "access_denied_exception":
            case "invalid_parameter_exception":
            case "rate_limit_exception":
            case "internal_server_error":

            }
    }
}, cancellation: {
    // sdk is canceled
})

4.7 QR Scanner

QR scanner is a part of ID capturing. If client settings is enable QR scanner, it would be done on server side. The response is parsed automatically and send back to client object TVCardInfoResult.

API references

1. TVLivenessResult

MethodTypedescription
isLiveBoolDetermines whether the selfie is live or not
scoreFloatThe score from 0 to 1

2. TVCardInfoResult

MethodTypedescription
infos[CardInfo]List of information are extracted from the ID card

CardInfo

MethodTypedescription
fieldStringName of field example name, address...
valueStringThe value of each field

3. TVSanityResult

MethodTypedescription
isGoodBoolDetermines whether the selfie or id quality is good or not
scoreFloatThe score from 0 to 1
errorStringIf the quality is not good, the error will be Image too blur, Not white background, Image too bright, Image too dark

4. TVCompareFacesResult

MethodTypedescription
matchResultMatchResultAn enum matched, unmatched, unsure
scorefloatThe score from 0 to 1

5. TVDetectionResult

MethodTypedescription
livenessResultTVLivenessResultResult of liveness verification if present
faceCompareResultTVCompareFacesResultResult of face matching if present
cardInfoResultTVCardInfoResultResult of ID extracting if present
selfieSanityResultTVSanityResultResult of selfie sanity verification if present
idSanityResultTVSanityResultResult of id sanity verification if present
idFrontImageIdStringImage ID of the front id image got from server after uploaded
idBackImageIdStringImage ID of the back id image got from server after uploaded
selfieImageIdStringImage ID of the selfie image got from server after uploaded

6. TVDetectIdCardTamperingResult

MethodTypedescription
isGoodBoolDetermines whether the id card is tamperred or not
scoreFloatThe score from 0 to 1
errorStringIf the quality is not good, the detailed result will be returned

7. TVDetectionResult

MethodTypedescription
cardTypeTVCardTypeList of supported cards can be found by let cardTypes: [TSCardType] = try TrustVisionSdk.getCardTypes()
actionModeActionModeAction mode
cardInfoResultTVCardInfoResultCard information result
frontIdImageId StringReturn image id of the uploaded front image. Should store somewhere to use other service like face compare
backIdImageId StringReturn image id of the uploaded back image. Should store somewhere to use other service like face compare
frontIdImageUIImageImage of id card's front side
backIdImage UIImageImage of id card's back side
selfieImage UIImageImage of selfie
livenessResult TVLivenessResultLiveness result
selfieSanityResult TVSanityResultSelfie sanity result
selfieImageId StringReturn image id of the uploaded selfie image. Should store somewhere to use other service like face compare
compareImageResult TVCompareFacesResultFaces comparing result
idCardTamperingResult TVDetectIdCardTamperingResultId card tampering check result
idSanityResult TVSanityResultId card sanity result

8. TVCameraOption (Enum)

  • TVCameraOption.front: Use front camera
  • TVCameraOption.back: Use back camera
  • TVCameraOption.both: The screen will have a button to switch between front & back camera

9. TVLivenessMode (Enum)

  • TVLivenessMode.none: no liveness verification. Just capture the selfie and verify sanity.
  • TVLivenessMode.passive: Use texture-based approach.
  • TVLivenessMode.active: Use challenge-response approach. User needs to follow and finish all steps when capturing selfie like turn left, right, up, smile, open mouth...

10. ActionMode (Enum)

  • ActionMode.full
  • ActionMode.faceMatching
  • ActionMode.liveness
  • ActionMode.extractIdInfo

11. FailureCallback (Callback)

Will be called in case failed. Parameters:

  • error: TVError.
    • errorCode: the specific error code.
    • description: the human-readable error description can be show to end user

12. CancellationCallback (Callback)

Will be called in case the sdk is cancelled. No parameters