Android v2.x.x Full

OVERVIEW

TrustVision SDK is an android SDK for TrustVision Engine. This document is for Clients who use the SDK v2.x.x that including connections with server. It provides these features:

Full flow (Id and selfie capturing, Id and selfie matching, liveness checking, tampering checking, OCR)
Capture ID and Selfie.
ID and selfie matching.
Liveness checking.
OCR and also QR scanner.

Specifications

Gradle Version 6.5
Tested with Gradle Plugin for Android Studio - version 4.1.1
minSdkVersion 21
targetSdkVersion 30

Integration Steps

1. Adding the SDK to your project

Get library file tv_sdk.zip, extract and put all files into a folder in android project. Example: folder ${project.rootDir}/repo

app
root
repo
    +--com
        +--trustvision
            +--tv_api_sdk
                +--2.0.x
                    +--tv_api_sdk-2.x.x.aar
                    +--tv_api_sdk-2.x.x.pom
                maven-metadata.xml
            +--tv_core_sdk
            +--tv_sdk
...

Add the following set of lines to the Project (top-level) build.gradle

Groovy

repositories {
    maven { url "https://maven.google.com" }
    maven { url "path/to/tvsdk/folder" }
    ...
}

Add the following set of lines to your app/build.gradle

Groovy

android {
    ...
    aaptOptions {
        noCompress "tflite"
    }
}

dependencies {
    implementation fileTree(dir: 'libs', include: ['*.jar'])
    implementation('com.trustvision:tv_sdk:2.x.x@aar') {
    transitive = true
}
testImplementation 'junit:junit:4.12'

}

2. Initialize SDK

To initialize the SDK, add the following lines to your app, and it needs to be completed successfully before calling any other SDK functionalities.

For example, you can add it to the onCreate method of the application class.

Java

@Override
protected void onCreate(@Nullable Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    TrustVisionSDK.init(this, appKey, appSecret, new TrustVisionSDK.TVInitializeListener() {
        @Override
        public void onInitSuccess() {
            List<TVCardType> cards = TrustVisionSDK.getCardTypes();
        }

        @Override
        public void onInitError() {

        }
    });
}

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

Java

List<TVCardType> cards = TrustVisionSDK.getCardTypes();

Please note: The SDK requires Camera permissions to capture images. Camera permissions will be handled by the SDK if not already handled by the app.

where:

referenceID: Nullable. The referenceID is optional. referenceID can be a phone number or an opaque string that can be used for correlating API calls to TrustVision from host app.
channelName: Nullable. The channelName is optional. channelName can be any string which is used to identify the running app.

3. Transaction (India market only)

3.1. Start transaction

Start transaction should be called when start new user journey.

It needs to be completed successfully before calling Selfie/ID card capturing or Face Matching.

Java

TrustVisionSDK.startTransaction(referenceID, channelName new TVTransactionCallback() {
    @Override
    public void onError(TVDetectionError error) {

    }

    @Override
    public void onSuccess(TVTransactionData transactionData) {
        HomeActivity.this.transactionID = transactionData.getTransactionId();
        HomeActivity.this.channelId = transactionData.getChannelId();
    }
});

where

transactionData: Object of type TVTransactionData.

3.2. End transaction

End transaction should be called when ending a user journey

4. Start the SDK

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

4.0. Full flow

4.0.1. Set config parameters

Java

TVSDKConfiguration.Builder builder = new TVSDKConfiguration.Builder()
.setActionMode(TVActionMode.FULL)
.setLivenessMode(TVLivenessMode.PASSIVE)
.setEnableSound(true)
.setEnableTiltChecking(true)
.setCardType(selectedCard)
.setCardSide(TVSDKConfiguration.TVCardSide.FRONT)
.setReadBothSide(false)
.setEnableReadCardInfo(false)
.setEnableIDSanityCheck(true)
.setEnableSelfieSanityCheck(true)
.setSkipConfirmScreen(false);

TVIDConfiguration configuration = builder.build();

Options:

setActionMode: TVActionMode. Action mode
setCardType: TVCardType. List of supported cards can be found by List<TVCardType> cards = TrustVisionSDK.getCardTypes();
setCardSide: TVCardSide. Card side to capture
setReadBothSide boolean. If true then the sdk will capture both side if possible; otherwise, then the card side defined in cardSide will be used
setEnableSound: Bool. Sound should be played or not
setEnableTiltChecking: Bool. Check if the phone is paralize to the ground before taking the id card photo or not
setEnableIDSanityCheck: Bool. Check sanity of the id card photo or not
setEnableSelfieSanityCheck: Bool. Check sanity of the selfie photo or not
setEnableDetectIdCardTampering: Bool. Check id card tampering or not
setLivenessMode: TVLivenessMode. Liveness verification mode
setCameraOption: TVCameraOption. Camera mode
setIdCardDefaultCameraSide: TVDefaultCameraSide. Default camera side for id card
setLivenessCheckDefaultCameraSide: TVDefaultCameraSide. Default camera side for liveness check
setSkipConfirmScreen: boolean. Control whether the SDK should skip the confirmation screen.

4.0.2. Start full flow activity from configuration

Java

TrustVisionActivity.startTrustVisionSDK(context, configuration, new TVIDCapturingCallBack() {
    @Override
    public void onError(TVDetectionError error) {

    }

    @Override
    public void onSuccess(TVDetectionResult result) {

    }

    @Override
    public void onCanceled() {

    }
});

where:

context: is the context of the current Activity being displayed
configuration: the configuration would like to pass to full flow activity
callback: is an object of type TVCapturingCallBack . It is an interface that has 3 method
- onSuccess method that will be called in case success. The onSuccess method has one parameter.
  - result : TVDetectionResult. Use all public methods to get result details
- onError: ErrorCallback
- onCanceled: 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

Java

TVIDConfiguration.Builder builder = new TVIDConfiguration.Builder()
.setCardType(selectedCard)
.setBackside(false)
.setEnableReadCardInfo(false)
.setEnableSanityCheck(true)
TVIDConfiguration configuration = builder.build();

Options:

setCardType: TVCardType. List of supported cards can be found by List<TVCardType> cards = TrustVisionSDK.getCardTypes();
setCardSide: TVCardSide. Card side
setEnableSound: Bool. Sound should be played or not
setEnableTiltChecking: Bool. Check if the phone is paralize to the ground before taking the id card photo or not
setEnableSanityCheck: Bool. Check sanity of the id card photo or not

4.1.2. Start id capturing activity from configuration

Java

TrustVisionActivity.startIDCapturing(context, languageCode, configuration, new TVIDCapturingCallBack() {
    @Override
    public void onError(TVDetectionError error) {

    }

    @Override
    public void onSuccess(TVDetectionResult result) {

    }

    @Override
    public void onCanceled() {

    }
});

where:

context: is the context of the current Activity being displayed
languageCode: the code of the language that will show on UI and it's also the language of the sound that will guide user. Currently support Vietnamese (vi) and English (en)
configuration: the configuration would like to pass to id capturing activity
callback: is an object of type TVCapturingCallBack . It is an interface that has 3 method
- onSuccess method that will be called in case success. The onSuccess method has one parameter.
  - result : TVDetectionResult. Use the following methods:
    - getCardInfoResult()
    - getFrontCardImage()
    - getBackCardImage()
- onError: ErrorCallback
- onCanceled: CancellationCallback

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

Java

TVSelfieConfiguration.Builder builder = new TVSelfieConfiguration.Builder()
.setCameraOption(TVSDKConfiguration.TVCameraOption.FRONT)
.setEnableSound(false)
.requireSanity(true)
.setLivenessMode(TVLivenessMode.PASSIVE);

Options:

setCameraOption: TVCameraOption. Camera mode
setEnableSound: Bool. Sound should be played or not
setLivenessMode: TVLivenessMode. Liveness verification mode
setEnableSanityCheck: Bool. Check selfie image sanity or not

4.2.2. Start selfie capturing activity from configuration

Java

TrustVisionActivity.startSelfieCapturing(context, languageCode, builder.build(), new TVCapturingCallBack() {
    @Override
    public void onError(TVDetectionError error) {

    }

    @Override
    public void onSuccess(TVDetectionResult result) {

    }

    @Override
    public void onCanceled() {

    }
});

where:

context: is the context of the current Activity being displayed
languageCode: the code of the language that will show on UI and it's also the language of the sound that will guide user. Currently support Vietnamese (vi) and English (en)
configuration: the configuration would like to pass to selfie capturing activity
callback: is an object of type TVCapturingCallBack . It is an interface that has 3 method
- onSuccess method that will be called in case success. The onSuccess method has one parameter.
  - result : TVDetectionResult. Use the following methods:
    - getLivenessResult()
    - getSelfieSanityResult()
    - getSelfieImages()
- onError: ErrorCallback
- onCanceled: CancellationCallback

4.3. VKYC (Coming soon)

The vkyc activity will allow user to capture video, upload selfie image, verify sanity, and checking otp by speech-to-text technology.

4.3.1. Set config parameters

Java

TVVkycConfiguration.Builder builder = new TVVkycConfiguration.Builder()

4.3.2. Start vkyc activity from configuration

Java

TrustVisionActivity.startVkyc(context, builder.build(), new TVCapturingCallBack() {
    @Override
    public void onError(TVDetectionError error) {

    }

    @Override
    public void onSuccess(TVDetectionResult result) {

    }

    @Override
    public void onCanceled() {

    }
});

where:

context: is the context of the current Activity being displayed
configuration: the configuration would like to pass to self-vkyc activity
callback: is an object of type TVCapturingCallBack . It is an interface that has 3 method
- onSuccess method that will be called in case success. The onSuccess method has one parameter.
  - result : TVDetectionResult. Use the following methods:
    - getGpsLocation()
    - getIpLocation()
    - getVkycTimestamp()
    - getVkycOverallResult()
    - getFaceCompareResult()
    - getCardInfoResult()
    - getSelfieImage()
    - getSelfieSanityResult()
    - getIdSanityResult()
    - getFrontCardImage()
    - getSelfieVideoId()
    - getSelfieVideoUrl()
    - getOtp()
    - getOtpResult()
- onError: ErrorCallback
- onCanceled: CancellationCallback

4.4. Self-VKYC

The self-vkyc activity will allow user to capture video, upload selfie image, verify sanity, and checking otp by speech-to-text technology.

4.4.1. Set config parameters

Java

TVSelfVkycConfiguration.Builder builder = new TVSelfVkycConfiguration.Builder()
    .setCameraOption(TVSDKConfiguration.TVCameraOption.FRONT)
    .setEnableSound(false)
    .setEnableSanityCheck(false)
    .setEnableVerticalChecking(false);

Options:

setCameraOption: TVCameraOption. Camera mode
setEnableSound: Bool. Sound should be played or not.
setEnableSanityCheck: Bool. The sanity verification should enable or not. (white background check)
setEnableVerticalChecking: If set to true, app will check if the phone is vertical before taking the photo

4.4.2. Start self-vkyc activity from configuration

Java

TrustVisionActivity.startSelfVkyc(context, builder.build(), new TVCapturingCallBack() {
    @Override
    public void onError(TVDetectionError error) {

    }

    @Override
    public void onSuccess(TVDetectionResult result) {

    }

    @Override
    public void onCanceled() {

    }
});

where:

context: is the context of the current Activity being displayed
configuration: the configuration would like to pass to self-vkyc activity
callback: is an object of type TVCapturingCallBack . It is an interface that has 3 method
- onSuccess method that will be called in case success. The onSuccess method has one parameter.
  - result : TVDetectionResult. Use the following methods:
    - getGpsLocation()
    - getIpLocation()
    - getSelfVkycTimestamp()
    - getSelfieSanityResult()
    - getSelfieImageId()
    - getSelfieVideoId()
    - getSelfieImageUrl()
    - getSelfieVideoUrl()
    - getOtp()
    - getSpeechToTextOtpResults()
    - getOtpResult()
- onError: ErrorCallback
- onCanceled: CancellationCallback

4.5. 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

4.5.1. Send face-matching request

Java

TrustVisionSDK.faceMatching(imageId1, imageId2, new TVCapturingCallBack() {
    @Override
    public void onError(TVDetectionError error) {
        Log.d("", error.getDetailErrorCode() + ":" + error.getDetailErrorDescription();
    }

    @Override
    public void onSuccess(TVDetectionResult result) {
        TVCompareFacesResult faceMatchingResult = result.getFaceCompareResult();

        // check response
        switch faceMatchingResult.getMatchResult() {
            case TVCompareFacesResult.MatchResult.MATCHED:
            case TVCompareFacesResult.MatchResult.UNSURE:
            case TVCompareFacesResult.MatchResult.UNMATCHED:
        }
    }

    @Override
   public void onCanceled() {

   }
});

where:

imageId1: Nullable. The image id got from selfie capturing
imageId2: Nullable. The image id got from front side ID capturing
callback: is an object of type TVCapturingCallBack . It is an interface that has 3 method
- onSuccess method that will be called in case success. The onSuccess method has one parameter.
  - result : TVDetectionResult . Use the following methods:
    - getFaceCompareResult()
- onError: ErrorCallback
- onCanceled: CancellationCallback

4.6. Id card sanity checking error handling

Java

// [FlowStartingFunc]: startTrustVisionSDK, startIdCapturing

TrustVisionActivity.[FlowStartingFunc](..., builder.build(), new TVCapturingCallBack() {
    @Override
    public void onError(TVDetectionError error) {

    }

    @Override
    public void onSuccess(TVDetectionResult result) {
        // ID CARD SANITY RESULT
        TVSanityResult idSanity = result.getIdSanityResult();
        if (idSanity != null && !idSanity.isGood()) {
            String error = idSanity.getError();
            switch (error) {
                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
                case "photo_not_qualified":
                    // Image is blurry or not clear
                case "no_card_or_incomplete_card":
                    // the captured image may contain a part of the card or no card at all
                case "nocard_or_multicard_image":
                    // the captured image may contain several cards or no card at all
            }
        }
    }
});

4.7. Selfie sanity checking error handling

Java

// [FlowStartingFunc]: startTrustVisionSDK, startSelfieCapturing

TrustVisionActivity.[FlowStartingFunc](..., builder.build(), new TVCapturingCallBack() {
    @Override
    public void onError(TVDetectionError error) {

    }

    @Override
    public void onSuccess(TVDetectionResult result) {
        // PORTRAIT SANITY RESULT
        TVSanityResult selfieSanity = result.getSelfieSanityResult()
        if (selfieSanity != null && !selfieSanity.isGood()) {
            String error = selfieSanity.getError();
            switch (error) {
                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

            }
        }
    }
});

4.8. API Error handling:

Java

// [FlowStartingFunc]: newCameraViewController, startIdCapturing, startSelfieCapturing, faceMatching

TrustVisionActivity.[FlowStartingFunc](..., builder.build(), new TVCapturingCallBack() {
    @Override
    public void onError(TVDetectionError error) {
        String message = error.getDetailErrorCode() + ":" + error.getErrorDescription();
        Log.d("", message);
        showToast(message);

        ///////////////////////////////////////
        // ERROR HANDLER
        int code = error.getErrorCode();
        String detailErrorCode = error.getDetailErrorCode();
        String description = error.getErrorDescription();

        switch code {
            case TVDetectionError.DETECTION_ERROR_AUTHENTICATION_MISSING:
                // Access key or secret is missing. Make sure the SDK is initialized
            case TVDetectionError.DETECTION_ERROR_PERMISSION_MISSING:
                // No camera permission.
            case TVDetectionError.DETECTION_ERROR_CAMERA_ERROR:
                // The camera can't be opened.
            case TVDetectionError.DETECTION_ERROR_SDK_INTERNAL:
                // The SDK has an unexpected error.
            case TVDetectionError.DETECTION_ERROR_API_ERROR:
                // API errors
                switch (detailErrorCode.toLowerCase()) {
                    // Connection errors
                    case "timeout_error":
                        // Network timeout. Poor internet connection.
                    case "network_error":
                        // Network error. No internet connection

                    // ID card OCR & Tampering 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 multi cards are detected
                    case "no_card_or_incomplete_card":
                        // the captured image may contain a part of the card or no card at all

                    // Liveness check and face 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 that are responsed from Server
                    case "access_denied_exception":
                        // You are not authorized to perform the action.
                    case "request_time_too_skewed":
                        // The X-TV-Timestamp header is expired or the current timestamp on device is not correct, need to be updated
                    case "invalid_parameter_exception":
                        // Input parameter violates a constraint.
                    case "image_too_large_exception":
                        // The input image size exceeds the allowed limit (15MB).
                    case "invalid_image_format_exception":
                        // The provided image format is not supported (JPG/PNG)
                    case "rate_limit_exception":
                        // The number of requests exceeded your throughput limit.
                    case "internal_server_error":
                        // Some unexpected error occurs while processing the request
                }
        }
    }

    @Override
    public void onSuccess(TVDetectionResult result) {

    }
});

API Interface

1. TVLivenessResult

Method	Type	description
`isLive`	Boolean	Determines whether the selfie is live or not
`getScore()`	float	The score from 0 to 1

2. TVCardInfoResult

Method	Type	description
`getInfos`	`List<Info>`	List of information are extracted from the ID card

Info

Method	Type	description
`getField`	String	Name of field example name, address...
`getValue()`	String	The value of each field

3. TVSanityResult

Method	Type	description
`isGood()`	Boolean	Determines whether the selfie or id quality is good or not
`getScore()`	float	The score from 0 to 1
`getError()`	String	If the quality is not good, the error will be `Image too blur`, `Not white background`, `Image too bright`, `Image too dark`

4. TVCompareFacesResult

Method	Type	description
`getMatchResult()`	MatchResult	An enum `MATCHED`, `UNMATCHED`, `UNSURE`
`getScore()`	float	The score from 0 to 1
`getError()`	String	If the quality is not good, the error will be `Image too blur`, `Not white background`, `Image too bright`, `Image too dark`

5. TVDetectionResult

Method	Type	description
`getSelfieImages()`	List<`SelfieImage`>	List of images that each item contains the bitmap of the selfie image and its ID got from server after uploaded
`getSelfieSanityResult()`	TVSanityResult	Result of selfie sanity verification if present
`getLivenessResult()`	TVLivenessResult	Result of liveness verification if present
`getFaceCompareResult()`	TVCompareFacesResult	Result of face matching if present
`getCardInfoResult()`	TVCardInfoResult	Result of ID extracting if present
`getIdSanityResult()`	TVSanityResult	Result of id sanity verification if present
`getFrontCardImage()`	TVImageClass	Contains bitmap of the front image and its ID got from server after uploaded
`getBackCardImage()`	TVImageClass	Contains bitmap of the back image and its ID got from server after uploaded
`getError()`	TVDetectionError	The error found when doing any detection

The below results are for VKYC (coming soon)

Method	Type	description
`getGpsLocation()`	Location	GPS Location where user do self-vkyc
`getIpLocation()`	Location	If GPS is not enabled or GPS permission is not granted to the application, use this api to get the location information based on IP address
`getSelfVkycTimestamp()`	String	Timestamp at the time user do self-vkyc
`getVkycTimestamp()`	String	Timestamp at the time user do vkyc
`getOtp()`	String	Otp generated
`getSpeechToTextOtpResults()`	[String]	Array of texts parse from user speech
`getOtpResult()`	Bool	True for passed and false for failed. True if the otp value matched one of the speech to text results
`getVkycOverallResult()`	Bool	True for approved, False for rejected

6. SelfieImage

- **getGestureType**: the gesture type of the selfie image.
- **getFrontalImage**: the frontal image of the selfie image.
- **getGestureImage**: the gesture image of the selfie image.

7. TVImageClass

Method	Type	description
`getLabel()`	String	Label of the Image class.
`getImage()`	Bitmap	Captured Bitmap

8. TVDetectionError

Method	Type	description
`getDetailErrorCode`	String	Error code
`getDetailErrorDescription()`	String	Error description

9. TVTransactionData

Method	Type	description
`getTransactionId()`	String	transaction id
`getChannelId()`	String	channel id

10. 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

11. TVActionMode (Enum)

TVActionMode.FACE_MATCHING
TVActionMode.FULL
TVActionMode.LIVENESS
TVActionMode.READ_CARD_INFO_ONE_SIDE
TVActionMode.READ_CARD_INFO_TWO_SIDE

12. 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 such as turn left, right, up, smile, open mouth...

13. TVDefaultCameraSide (Enum)

TVDefaultCameraSide.FRONT
TVDefaultCameraSide.BACK

14. ErrorCallback (Callback)

Will be called in case failed. Parameters:

error: TVDetectionError.
- getDetailErrorCode: the specific error code.
- getDetailErrorDescription: the human-readable error description can be show to end user

15. CancellationCallback (Callback)

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

PreviousAndroid v2.0.x UI Only NextAndroid v1.x.x Full

.css-9x8bsw{-webkit-text-decoration:none;text-decoration:none;}.css-9x8bsw:hover{-webkit-text-decoration:underline;text-decoration:underline;}Android v2.x.x Full

Android v2.x.x Full