Android v2.0.x UI Only

OVERVIEW

TrustVision SDK is the android SDK for TrustVision Engine. This document is for Clients who only use the UI of the SDK. It provides these features:

• Capture ID and Selfie.
• Liveness checking.

Specifications

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

Example Project

• Please refer to the sample project provided in the Example to get an understanding of the implementation process.

TrustVisionSDK.init(jsonConfigurationByServer, languageCode);

• Build and run the example app

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

repositories {
    maven { url "https://maven.google.com" }
    maven { url "https://jitpack.io" } // from SDK v2.0.0.20 and above
    maven { url "path/to/tvsdk/folder" }
    ...
}

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

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 and config SDK

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

@Override
protected void onCreate(@Nullable Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    TrustVisionSDK.init(jsonConfigurationByServer, languageCode);
}

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:

• jsonConfigurationByServer: String. The jsonConfigurationByServer is optional but recommended. It's the setting specialized for each client from TS server. It's the response json string get by API https://ekyc.trustingsocial.com/api-reference/customer-api/#get-client-settings. When it's null or unmatched with the expected type then the default setting in the SDK will be used.
• languageCode: String the code of the language that will show and sound to user. E.g Vietnamese (vi), English (en).

2.1. Config

2.1.0 Language code

2.1.0.0 Get supported language codes list

TrustVisionSdk.getSupportedLanguages();

2.1.1.1 Get language code in use

TrustVisionSdk.getLanguageCode();

2.1.1.2

Allow user to change the sdk language after initialization

TrustVisionSdk.changeLanguageCode(String languageCode);

3. Start the SDK

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

3.0. Capture the ID

The id capturing activity will show the camera to capture image, preview the image. To start the id capturing activity.

3.0.1. Set config parameters

TVIDConfiguration.Builder builder = new TVIDConfiguration.Builder()
.setCardType(selectedCard)
.setCardSide(TVSDKConfiguration.TVCardSide.FRONT)
.setReadBothSide(false)
.setEnableSound(false)
.setEnablePhotoGalleryPicker(false)
.setEnableTiltChecking(false)
.setSkipConfirmScreen(false);

TVIDConfiguration configuration = builder.build();

Options:

• setCardType: TVCardType. List of supported cards can be found by 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: boolean. Sound should be played or not.
• setEnablePhotoGalleryPicker: boolean. Allow user select id card image from phone gallery.
• setEnableTiltChecking: boolean. Check if the phone is parallel to the ground before taking the id card photo or not.
• setSkipConfirmScreen: boolean. Control whether the SDK should skip the confirmation screen.

3.0.2. Start id capturing activity from configuration

TrustVisionSDK.startIDCapturing(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 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:
      • getFrontCardImage()
      • getBackCardImage()
  • onError: ErrorCallback
  • onCanceled: CancellationCallback

3.0.3. Handle ID capturing results

3.0.3.1. Get Image Ids to be used in a particular use case

Use this API https://ekyc.trustingsocial.com/api-reference/customer-api/#upload-image The images should be uploaded as JPEG data with 100% quality. For example

ByteArrayOutputStream stream = new ByteArrayOutputStream();
// With front side
result.getFrontCardImage().getImage().compress(Bitmap.CompressFormat.JPEG, 100, stream); // 100% quality

// With back side
result.getBackCardImage().getImage().compress(Bitmap.CompressFormat.JPEG, 100, stream); // 100% quality

// With QR image (Available from v2.0.6.9)
// If result.isRequiredQrImage()` is true then `result.getCardQrImage()` should be non-null. Otherwise, clients should be warned to re-capture id card photos.
result.getCardQrImage().getBitmap().compress(Bitmap.CompressFormat.JPEG, 100, stream); // 100% quality

byte[] dataToUpload = stream.toByteArray();

3.1. Capture the selfie

The selfie capturing activity will show the camera to capture image, preview the image, verify liveness. To start the selfie capturing activity.

3.1.1. Set config parameters

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

Options:

• setCameraOption: TVCameraOption. Camera mode
• setEnableSound: boolean. Sound should be played or not
• setLivenessMode: TVLivenessMode. Liveness verification mode
• setSkipConfirmScreen: boolean. Control whether the SDK should skip the confirmation screen.

3.1.2. Start selfie capturing activity from configuration

TrustVisionSDK.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:
      • getSelfieImages()
      • getSelfieVideos()
      • getLivenessMetadata()
  • onError: ErrorCallback
  • onCanceled: CancellationCallback

3.1.3. Handle selfie results

3.1.3.1. Get Image Ids

Use this api https://ekyc.trustingsocial.com/api-reference/customer-api/#upload-image to get image ids with the inputs are the elements of result.getSelfieImages() The images should be uploaded as JPEG data with 100% quality. For example:

ByteArrayOutputStream stream = new ByteArrayOutputStream();
// With frontal images
result.getSelfieImages().get(index).getFrontalImage().getImage().compress(Bitmap.CompressFormat.JPEG, 100, stream); // 100% quality

// With gesture images
result.getSelfieImages().get(index).getGestureImage().getImage().compress(Bitmap.CompressFormat.JPEG, 100, stream); // 100% quality

byte[] dataToUpload = stream.toByteArray();

3.1.3.2. Get Video Ids

Depends on the provided settings, there may be a number of video data (byte array - byte[]) in the selfie result : result.getSelfieVideos() With each result.getSelfieVideos() 's element, call the below api to get video id https://ekyc.trustingsocial.com/api-reference/customer-api/#upload-videoaudioframes

{
  "file": " <result.getSelfieVideos().get(index)> "
}

3.1.3.3. Check liveness with available data

https://ekyc.trustingsocial.com/api-reference/customer-api/#verify-face-liveness Call the above api with below params:

1. In images field, each element contains:

{
  "id": "the frontal image id received in step #3.1.3.1 >"
}

2. In gesture_images field, each element contains:

{
  "gesture": "lower case string of <result.getSelfieImages().get(i).getGestureType().toGestureType()>",
  "images": [
    {
      "id": "the gesture image id received in step #3.1.3.1 >"
    }
  ]
}

3. videos field is a list which comprises 2 lists:

• (i) Liveness video ids:

[
  {
    "id": "the video id received in step #3.1.3.2>"
  }
]

• (ii) Liveness frames lists. Depends on the client setting, it's nullable.

result.getSelfieFrameLists() // JSONArray

4. metadata field is

result.getLivenessMetadata() // JSONObject

3.2. Error handling:

// [FlowStartingFunc]: startIdCapturing, startSelfieCapturing

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

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

        switch code {
            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.
        }
    }

    @Override
    public void onSuccess(TVDetectionResult result) {

    }
});

API Interface

1. TVLivenessResult

2. TVDetectionResult

3. SelfieImage

4. FaceDetectionType

int NEUTRAL = 1
int TURN_LEFT = 5
int TURN_RIGHT = 6
int FACE_UP = 7
int FACE_DOWN = 8

5. TVImageClass

6. TVDetectionError

Error code is one of the below list

int TVDetectionError.DETECTION_ERROR_PERMISSION_MISSING = 1004
int TVDetectionError.DETECTION_ERROR_CAMERA_ERROR = 1005
int TVDetectionError.DETECTION_ERROR_SDK_INTERNAL = 1007

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

8. TVLivenessMode (Enum)

• TVLivenessMode.NONE: no liveness verification. Just capture the selfie.
• 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...

9. TVDefaultCameraSide (Enum)

• TVDefaultCameraSide.FRONT
• TVDefaultCameraSide.BACK

10. ErrorCallback (Callback)

Will be called in case failed. Parameters:

• error: TVDetectionError.

11. CancellationCallback (Callback)

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