Android v4.0.x

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:

• Separate the QR code scanning
• Scan QR while capturing front card
• Allow certain card types
• Cache SOD NFC
• Modify UI while reading NFC
• Capture ID and Selfie.
• Liveness checking.
• Face authentication

Specifications

• Gradle Version 7.3.3
• Tested with Gradle Plugin for Android Studio - version 7.2.2
• minSdkVersion 21
• targetSdkVersion 33
• Support Kotlin version 1.5.0 - 1.8.0

Integration Steps

1. Adding the SDK to your project

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

Note : tv_sdk_client Each client will have a SDK name. That SDK name will contain the name of the client

app
root
repo
    +--com
        +--trustvision
            +--tv_api_sdk
                +--4.0.x
                    +--tv_api_sdk-4.0.x.aar
                    +--tv_api_sdk-4.0.x.pom
                maven-metadata.xml
            +--tv_core_sdk
            +--tv_sdk_client
...

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

buildscript {
    ext.kotlin_version = '1.6.21' // or any version that >= 1.5 and < 1.8

    repositories {
        maven {
            url 'https://maven.google.com'
        }
        mavenCentral()
        google()
    }

    dependencies {
        classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version"
    }
}

allprojects {
    repositories {
        maven { url "https://maven.google.com" }
        maven { url "https://jitpack.io" }
        maven { url "path/to/tvsdk/folder" }  // example : maven { url "${project.rootDir}/repo" }
        ...
    }
}

Note : If your project uses the new way to define repositories (central declaration of repositories), you must change repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS) to repositoriesMode.set(RepositoriesMode.PREFER_PROJECT)

pluginManagement {
    repositories {
        google()
        mavenCentral()
        gradlePluginPortal()
    }
}
dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.PREFER_PROJECT)
    repositories {
        google()
        mavenCentral()
    }
}

• 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_client:4.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.

val config = TVInitializeConfiguration(
    jsonConfigurationByServer = jsonConfigurationByServer,
    endpoint = endpoint,
    accessKeyId = accessKeyId,
    accessKeySecret = accessKeySecret,
    endpointLogger = endpointLogger,
    accessKeyIdLogger = accessKeyIdLogger,
    accessKeySecretLogger = accessKeySecretLogger,
    languageCode = languageCode,
    theme = theme,
    imageEncryptionKey = imageEncryptionKey,
    securityPublicKey = securityPublicKey,
    xRequestId = xRequestId,
    xRequestId2 = xRequestId2,
    flowId = flowId,
    enableGetClientSetting = enableGetClientSetting,
    tvCertificate = tvCertificate,
    headers = headers
)

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    TrustVisionSDK.init(context, config, object : TVInitializeListener {
        override fun onInitSuccess(result: TVInitResult) {
            super.onInitSuccess(result)
        }

        override fun onInitError(error: TVDetectionError) {

        }
    })
}

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.

Options:

• setLanguageCode: String the code of the language that will show and sound to user. E.g Vietnamese (vi), English ( en).
• setImageEncryptionKey: String (optional). the key to encrypt image data. It's optional. If it's null or empty then the image data will not be encrypted.
• setSecurityPublicKey: String (optional). the key to encrypt exif data. It's optional. If it's null or empty then the exif data will be encrypted by the default key.
• setTheme: TVTheme (optional). The theme of the SDK. If it's null then the sdk will use the default theme or the theme that we customized for the client.

To call the APIs in the SDK, the host app needs to set the following parameters:

• endpoint: String. The endpoint of the server.
• accessKeyId: String. The access key id of the server.
• accessKeySecret: String. The secret key of the server.
• xRequestId: String (optional) https://ekyc.trustingsocial.com/api-reference/customer-api#api-reconciliation
• xRequestId2: String (optional)
• flowId: String (optional). Allow these values:
  • facce_authen
  • onboarding
• tvCertificate: Int (optional). It is the raw resource ID (@RawRes) of the SSL certificates file
• setHeaders: Map<String, String> (optional). The headers to be added to the request.
• setFlowId: String (optional). The flow id of the API
• setSSLCertificates: List<Int> (optional). The list of resource IDs (@RawRes) corresponds to the SSL certificates that should be added to the request.

The host app will call the APIs itself, set the following parameters:

• enableGetClientSetting: Boolean (optional).
  • true (default) for calling api getClientSettings from SDK full mode.
  • false for otherwise.
• setJsonConfigurationByServer: String. set this parameter if the host app will call the APIs itself. The jsonConfigurationByServer is 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.

If the log event feature is used, set the following parameters:

• endpointLogger: String. The endpoint of the log event server.
• accessKeyIdLogger: String. The access key id of the log event server.
• accessKeySecretLogger: String. The secret key of the log event server.

2.1. Config

2.1.0 Language code

2.1.0.0 Get supported language codes list

TrustVisionSdk.supportedLanguages

2.1.0.1 Change language code

Allow user to change the sdk language after initialization

TrustVisionSdk.changeLanguageCode(languageCode)

wherer:

• languageCode:String the code of the language that will show and sound to user. E.g Vietnamese (vi), English ( en).

2.2. Dynamic feature

2.2.0 Prerequisites

Need to have background of Dynamic Feature. Practice guideline reference

2.2.1 Configuration

Add placeholder placeholder_missing_resources.xml for missing resources, these values will be override from SDK:

<resources>
    <string name="tv_title_activity_main" />
    <integer name="google_play_services_version">1</integer>
    <style name="tvAppTheme.NoActionBar" parent="AppTheme.NoActionBar" />
</resources>

Please execute this code before starting SDK if we're using Dynamic Feature in host app

TrustVisionSDK.installDynamicFeature {
    // We often execute this code to install some necessary resources for dynamic feature
    SplitCompat.installActivity(it)
}

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

val configuration = TVIDConfiguration(
    enableSound = true,
    cardTypes = selectedCards,
    cardSide = TVSDKConfiguration.TVCardSide.FRONT,
    isReadBothSide = false,
    isEnableScanNfc = true,
    isEnableScanQr = true,
    isEnablePhotoGalleryPicker = false,
    isEnableTiltChecking = false,
    isSkipConfirmScreen = true,
    isEnableUploadFrames = true,
    isEnableUploadImages = true,
    isEnableSanityCheck = true,
    isEnableDetectIdCardTampering = true,
    isEnableReadCardInfo = true,
    isEnableCheckNfcData = true,
    isEnableVerifyNfc = true
)

Options:

• setCardTypes: List<TVCardType>. Card types is allowed capture.

  card_type	description	supported countries
  TVCardType.default(Country.VIETNAM)	Any of Vietnam national ID versions	vietnam
  TVCardType.cmnd()	Chứng minh nhân dân cũ	vietnam
  TVCardType.cmndNew()	Chứng minh nhân dân mới	vietnam
  TVCardType.cccd()	Căn cước công dân	vietnam
  TVCardType.cccdNew()	Căn cước công dân gắn chip	vietnam
  TVCardType.passport()	Vietnam passport	vietnam
  TVCardType.tcc()	Thẻ căn cước	vietnam

• setEnableSound: boolean. Sound should be played or not.

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

• setEnableScanNfc boolean. scan NFC chip of the id card or not.

• setEnableScanQr boolean. scan QR code of the id card 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.

• setEnableUploadFrames: boolean. Enable upload video frames or not. If it's false then the SDK won't call the API to upload the frames and the APIs that need the video frames will be skipped or called with empty frames data.

• setEnableUploadImages: boolean. Enable upload images or not. If it's false then the SDK won't call the API to upload the images and the APIs that need the image will be skipped.

• setEnableSanityCheck: boolean. Enable sanity check or not. If it's true then the SDK will call the API to check the sanity of the id card.

• setEnableDetectIdCardTampering: boolean. Enable ID Tampering Verification or not. If it's true then the SDK will call the API to check the tampering of the id card.

• setEnableReadCardInfo: boolean. Enable read card info or not. If it's true then the SDK will call the API to read the card info.

• setEnableCheckNfcData: boolean. Enable check NFC data or not. If it's true then the SDK will call the API to get sod and cached fields of the NFC data.

• setEnableVerifyNfc: boolean. Enable verify NFC or not. If it's true then the SDK will call the API to verify the NFC.

3.0.2. Start id capturing activity from configuration

TrustVisionSDK.startIDCapturing(activity, configuration, object : TVCapturingCallBack() {
    override fun onNewFrameBatch(frameBatch: FrameBatch) {

    }
    override fun onError(error: TVDetectionError) {

    }
    override fun onSuccess(result: TVDetectionResult) {

    }
    override fun onCanceled(reason: TVCancelReason) {

    }
    override fun readIdCardImage(image: TVImageClass): TVNfcParams? {

    }
})

where:

• activity: is 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 methods
  • onNewFrameBatch: NewFrameBatchCallback. can be called multiple times during the capturing to return frame data.
    • frameBatch: FrameBatch
      • getId(): String. batch id generated by TV SDK
      • getFrames(): List<TVFrameClass>. batch frame to push
      • getMetadata(): Map<String, String>. batch metadata to push
      • getValidVideoIds() Set<String>. For debugging purpose only
  • onSuccess method that will be called in case of success. The onSuccess method has one parameter.
    • result : TVDetectionResult. has the following methods:
      • getFrontCardImage(): TVImageClass
      • getBackCardImage(): TVImageClass
      • getFrontIdQr(): TVCardQr
      • getBackIdQr(): TVCardQr
      • getNfcInfoResult(): TVNfcInfoResult
      • getIdSanityResult(): TVSanityResult
      • getIdTamperingResult(): TVSanityResult
      • getCardInfoResult(): TVCardInfoResult
  • onError: ErrorCallback. Will be called when an error has occurred during the capturing.
    • error: TVDetectionError
  • onCanceled: CancellationCallback. Will be called when the journey has been cancelled (e.g user clicked on back button...)
  • readIdCardImage: method that will be called in case of scan NFC to read SDK Id number from the image. The readIdCardImage method has a parameter and return tvNfcParams.
    • image: TVImageClass. image of back id card
    • tvNfcParams: TVNfcParams has the following params:
      • idNumber: String. The id number of the card. If it's null or empty then the SDK will skip flow scan NFC and continue.
      • issueDate: String (optional). The issue date of the card
      • hashSod: String (optional). The hash of the SOD NFC
      • cachedFields: List<String>(optional). The cached fields of the card

3.0.3. Handle onNewFrameBatch callback

If the APIs is called by the SDK, please skip this step.

With each batch that returned by onNewFrameBatch(FrameBatch) callback, call the below api to upload the data to server, and store the frame batch id that responses from the API, keep it corresponding with frameBatch.getId() - local id https://ekyc.trustingsocial.com/api-reference/customer-api/#upload-frame-batch

For example:

// this dictionary will be used for ID Tampering Verification
val frontCardFrameBatchIdsDictionary: MutableMap<String, String> = mutableMapOf()
val backCardFrameBatchIdsDictionary: MutableMap<String, String> = mutableMapOf()
// frameBatchIdsDictionary.put(
//    key = <id_returned_from_sdk>,
//    value = <id_responded_from_server>
// )

override fun onNewFrameBatch(frameBatch: FrameBatch) {
    val gson = Gson()
    val framesStr = gson.toJson(frameBatch.frames)
    val params: MutableMap<String, Any> = HashMap()
    params["frames"] = framesStr
    params["metadata"] = frameBatch.metadata
    params["label"] = "video"
    val jsonToBeUploaded = gson.toJson(params)
    // upload frame batch to server using this api:
    // https://ekyc.trustingsocial.com/api-reference/customer-api/#upload-videoaudioframes
    val uploadingResult: YourResponseObject = yourMethodToUploadFrameBatch(jsonToBeUploaded)

    // Keep the id that generated by the SDK corresponding with the one responded from server
    if (cardSide === TVSDKConfiguration.TVCardSide.FRONT) {
        frontCardFrameBatchIdsDictionary[frameBatch.id] = uploadingResult.fileId
    } else {
        backCardFrameBatchIdsDictionary[frameBatch.id] = uploadingResult.fileId
    }
}

3.0.4. Handle ID capturing results

3.0.4.1 Remove redundant frame batch ids

If the APIs is called by the SDK, please skip this step.

// These lists contain all valid frame batch ids that responded by server
var validFrontCardServerFrameBatchIds: List<String>? = null
var validBackCardServerFrameBatchIds: List<String>? = null

override fun onSuccess(result: TVDetectionResult) {
// the batch id list is null when Frame Recording feature is disabled by client settings.
// Wait until every Frame batch has been uploaded to server before calling this
    if (everyFrameBatchUploadingCompleted) {
        result.frontCardFrameBatchIds?.also {
            validFrontCardServerFrameBatchIds = removeRedundantFrameBatchIds(
                frontCardFrameBatchIdsDictionary,
                it
            )
        }
        result.backCardFrameBatchIds?.also {
            validBackCardServerFrameBatchIds = removeRedundantFrameBatchIds(
                backCardFrameBatchIdsDictionary,
                it
            )
        }
    }
}

private fun removeRedundantFrameBatchIds(
    batchIdsDictionary: MutableMap<String, String>,
    validIdsFromSDK: Collection<String>
): List<String> {
    val iter: MutableIterator<Map.Entry<String, String>> = batchIdsDictionary.entries.iterator()
    while (iter.hasNext()) {
        val (key1) = iter.next()
        if (!validIdsFromSDK.contains(key1)) {
            iter.remove()
        }
    }
    return batchIdsDictionary.values.toList()
}

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

If the APIs is called by the SDK, please skip the image upload step.

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:

var frontCardId: String? = null
var backCardId: String? = null
var frontQrId: String? = null
var backQrId: String? = null

fun onSuccess(result: TVDetectionResult) {
    // With front side
    frontCardId = result.frontCardImage?.imageByteArray?.let {
        yourMethodToUploadImage(it)
    }
    // With back side
    backCardId = result.backCardImage?.imageByteArray?.let {
        yourMethodToUploadImage(it)
    }

    // In case the QR capturing feature is enabled, and `result.getCardQrImage()` is null then
    // the user will be notified, so they can choose to re-capture their ID card.
    frontQrId = result.frontIdQr?.images?.getOrNull(i)?.imageByteArray?.let {
        yourMethodToUploadImage(it)
    }
    backQrId = result.backIdQr?.images?.getOrNull(i)?.imageByteArray?.let {
        yourMethodToUploadImage(it)
    }
}

3.0.4.3. Check ID Tampering

If the APIs is called by the SDK, please skip this step.

Call this API https://ekyc.trustingsocial.com/api-reference/customer-api/#request-detect-id-card-tampering with params:

{
  "image": {
    "id": "<frontCardId>"
  },
  "image2": {
    "id": "<backCardId>"
  },
  "qr1_images": [
    {
      "id": "<qrId>"
    }
  ],
  "card_type": "<result.cardType.getCardId()>",
  "videos": [
    {
      "id": "<validFrontCardServerFrameBatchIds.get(index)>"
    },
    {
      "id": "<validFrontCardServerFrameBatchIds.get(index + 1)>"
    },
    ...
    {
      "id": "<validBackCardServerFrameBatchIds.get(index)>"
    },
    {
      "id": "<validBackCardServerFrameBatchIds.get(index + 1)>"
    },
    ...
  ]
}

3.0.4.4 Upload QR images

If the APIs is called by the SDK, please skip this step.

if result.getFrontIdQr().isRequired() is true then result.getFrontIdQr().getImages() array should be non-empty. Otherwise, clients should be warned to re-capture id card photos.

QR images will be uploaded with this api: https://ekyc.trustingsocial.com/api-reference/customer-api/#upload-image

val frontQrImage = result.frontIdQr?.images?.getOrNull(i)
val metadata: Map<String,String>? = frontQrImage?.metadata
val label: String? = frontQrImage?.label
val data: ByteArray? = frontQrImage?.imageByteArray

*The same logic will be applied to result.getBackIdQr()

3.0.5 Scan NFC in back ID card capturing step

If the APIs is called by the SDK, please skip this step.

After capture the back card, if the card has nfc chip, SDK will call readIdCardImage method in background thread. With image that returned by readIdCardImage, call api or do anything to detect id number of the card then return tvNfcParams to start flow scan NFC. If id number is null or empty, SDK skip flow scan NFC and continue

override fun readIdCardImage(image: TVImageClass): TVNfcParams? {
  var idNumber: String? = null;
  // call api or do any thing to read and return id number
  // TODO
  return TVNfcParams(idNumber, null, null, null)
}

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

val configuration = TVSelfieConfiguration(
    cameraOption = TVCameraOption.FRONT,
    enableSound = true,
    livenessMode = TVLivenessMode.PASSIVE,
    isEnableVerticalChecking = false,
    isSkipConfirmScreen = true,
    isEnableUploadFrames = true,
    isEnableUploadImages = true,
    isEnableSanityCheck = true,
    isEnableVerifyLiveness = true
)

Options:

• setCameraOption: TVCameraOption. Camera mode
• setEnableSound: boolean. Sound should be played or not
• setLivenessMode: TVLivenessMode. Liveness verification mode
• setEnableVerticalChecking: boolean. Check if the phone is vertical or not before
• setSkipConfirmScreen: boolean. Control whether the SDK should skip the confirmation screen.
• setEnableUploadFrames: boolean. Enable upload video frames or not. If it's false then the SDK won't call the API to upload the frames and the APIs that need the video frames will be skipped or called with empty frames data.
• setEnableUploadImages: boolean. Enable upload images or not. If it's false then the SDK won't call the API to upload the images and the APIs that need the image will be skipped.
• setEnableSanityCheck: boolean. Enable sanity check or not. If it's true then the SDK will call the API to check the sanity of the selfie.
• setEnableVerifyLiveness: boolean. Enable liveness verification or not. If it's true then the SDK will call the API to verify the liveness of the selfie.

3.1.2. Start selfie capturing activity from configuration

TrustVisionSDK.startSelfieCapturing(activity, configuration, object : TVCapturingCallBack() {
    override fun onNewFrameBatch(frameBatch: FrameBatch) {

    }
    override fun onError(error: TVDetectionError) {

    }
    override fun onSuccess(result: TVDetectionResult) {

    }
    override fun onCanceled(reason: TVCancelReason) {

    }
})

where:

• activity: is the current Activity being displayed
• 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 methods
  • onNewFrameBatch: NewFrameBatchCallback. can be called multiple times during the capturing to return frame data.
    • frameBatch: FrameBatch
      • getId(): String. batch id generated by TV SDK
      • getFrames(): List<TVFrameClass>. batch frame to push
      • getMetadata(): Map<String, String>. batch metadata to push
      • getValidVideoIds() Set<String>. For debugging purpose only
  • onSuccess method that will be called in case of success. The onSuccess method has one parameter.
    • result : TVDetectionResult. has the following methods:
      • getFaces(): List<TVImageClass>
      • getGestureFaces(): List<TVGestureFace>
      • getLivenessFrameBatchIds(): Collection<String>
      • getLivenessMetadata(): JSONObject
  • onError: ErrorCallback. Will be called when an error has occurred during the capturing.
    • error: TVDetectionError
  • onCanceled: CancellationCallback. Will be called when the journey has been cancelled (e.g user clicked on back button...)

3.1.3. Handle onNewFrameBatch callback

If the APIs is called by the SDK, please skip this step.

With each batch that returned by onNewFrameBatch(FrameBatch) callback, call the below api to upload the data to server, and store the frame batch id that responses from the API, keep it corresponding with frameBatch.getId() - local id https://ekyc.trustingsocial.com/api-reference/customer-api/#upload-frame-batch

For example:

// this dictionary will be used for face liveness Verification
val selfieFrameBatchIdsDictionary: MutableMap<String, String> = mutableMapOf()
// frameBatchIdsDictionary.put(
//    key = <id_returned_from_sdk>,
//    value = <id_responded_from_server>
// )

override fun onNewFrameBatch(frameBatch: FrameBatch) {
    val gson = Gson()
    val framesStr = gson.toJson(frameBatch.frames)
    val params: MutableMap<String, Any> = HashMap()
    params["frames"] = framesStr
    params["metadata"] = frameBatch.metadata
    params["label"] = "video"
    val jsonToBeUploaded = gson.toJson(params)
    // upload frame batch to server using this api:
    // https://ekyc.trustingsocial.com/api-reference/customer-api/#upload-videoaudioframes
    val uploadingResult: YourResponseObject = yourMethodToUploadFrameBatch(jsonToBeUploaded)

    // Keep the id that generated by the SDK corresponding with the one responded from server
    selfieFrameBatchIdsDictionary[frameBatch.id] = uploadingResult.fileId
}

3.1.4. Handle selfie results

3.1.4.1 Remove redundant frame batch ids

If the APIs is called by the SDK, please skip this step.

// These lists contain all valid frame batch ids that responded by server
var validServerFrameBatchIds: List<String>? = null

override fun onSuccess(result: TVDetectionResult) {
    // the batch id list is null when Frame Recording feature is disabled by client settings.
    // Wait until every Frame batch has been uploaded to server before calling this
    if (everyFrameBatchUploadingCompleted) {
        result.livenessFrameBatchIds?.also {
            validServerFrameBatchIds = removeRedundantFrameBatchIds(
                selfieFrameBatchIdsDictionary,
                it
            )
        }
    }
}

private fun removeRedundantFrameBatchIds(
    batchIdsDictionary: MutableMap<String, String>,
    validIdsFromSDK: Collection<String>
): List<String> {
    val iter: MutableIterator<Map.Entry<String, String>> = batchIdsDictionary.entries.iterator()
    while (iter.hasNext()) {
        val (key1) = iter.next()
        if (!validIdsFromSDK.contains(key1)) {
            iter.remove()
        }
    }
    return batchIdsDictionary.values.toList()
}

3.1.4.2. Get Image Ids

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

For example:

// These lists of image ids will be used in Liveness Verification
val frontalImageIds = mutableListOf<String>()
val gestureImageIds = mutableListOf<String>()

override fun onSuccess(result: TVDetectionResult) {
    handleSelfieImages(result.faces, result.gestureFaces)
}

private fun handleSelfieImages(faces: List<TVImageClass>?, gestureFaces: List<TVGestureFace>?) {
    faces?.forEach { face ->
        // Handle frontal images
        face.imageByteArray?.also {
            // frontalImageId is the id of the image, returned from server when the uploading API is completed successfully
            val frontalImageId = yourUploadImageMethod(it)
            frontalImageIds.add(frontalImageId)
        }
    }

    gestureFaces?.forEach { face ->
        // Handle gesture images
        face.images.forEach { image ->
            // gestureImageId is the id of the image, returned from server when the uploading API is completed successfully
            val gestureImageId = yourUploadImageMethod(image.imageByteArray ?: return@forEach)
            gestureImageIds.add(gestureImageId)
        }
    }
}

Upload Image API request, parameters:

{
  "file": "<byte[] dataToUpload>",
  "label": "<proper label, check the API document for detail>"
}

3.1.4.3. Liveness Verification

If the APIs is called by the SDK, please skip this step.

API document: https://ekyc.trustingsocial.com/api-reference/customer-api/#verify-face-liveness

Call the above api with below parameters:

1. images field

{
  "images": [
    {
      "id": "<frontalImageIds.get(index)>"
    },
    {
      "id": "<frontalImageIds.get(index + 1)>"
    },
    ...
  ]
}

2. gesture_images field

{
  "gesture_images": [
    {
      "gesture": "<result.getSelfieImages().get(index).getGestureType().toGestureType().toLowerCase()>",
      "images": [
        {
          "id": "<gestureImageIds.get(index)>"
        }
      ]
    },
    {
      "gesture": "<result.getSelfieImages().get(index + 1).getGestureType().toGestureType().toLowerCase()>",
      "images": [
        {
          "id": "<gestureImageIds.get(index + 1)>"
        }
      ]
    },
    ...
  ]
}

3. videos field

{
  "videos": [
    {
      "id": "<validServerFrameBatchIds.get(index)>"
    },
    {
      "id": "<validServerFrameBatchIds.get(index + 1)>"
    },
    ...
  ]
}

4. metadata field

{
  "metadata": "<result.getLivenessMetadata()>"
}

3.2. Scan QR

The QR scanner activity will show the camera to scan image, preview the image. To start the QR scanner activity.

3.2.1. Set config parameters

val builder = TVQRConfiguration.Builder()
    .setCardTypes(cards)
    .setCardSide(TVSDKConfiguration.TVCardSide.FRONT)
    .setEnableSound(false)
    .setSkipConfirmScreen(true)
    .setEnableUploadFrames(true)
    .setEnableUploadImages(true)

val configuration = builder.build()

Options:

• setCardTypes: List<TVCardType>. List of supported cards can be found by TrustVisionSDK.getCardTypes() if you set jsonConfigurationByServer when init SDK. If not, use :

TVCardType(
    "vn.national_id",
    "CMND cũ / CMND mới / CCCD",
    true,
    TVCardType.TVCardOrientation.HORIZONTAL
)

• setCardSide: TVCardSide. Card side to capture.
• setEnableSound: boolean. Sound should be played or not.
• setSkipConfirmScreen: boolean. Control whether the SDK should skip the confirmation screen.
• setEnableUploadFrames: boolean. Enable upload video frames or not
• setEnableUploadImages: boolean. Enable upload images or not

3.2.2. Start QR Scanning activity from configuration

TrustVisionSDK.startQRScanning(activity, configuration, object : TVCapturingCallBack() {
    override fun onError(error: TVDetectionError) {

    }

    override fun onSuccess(result: TVDetectionResult) {

    }

    override fun onCanceled(reason: TVCancelReason) {

    }

})

where:

• activity: is the current Activity being displayed
• configuration: the configuration would like to pass to QR scanning activity
• callback: is an object of type TVCapturingCallBack . It is an interface that has 3 methods
  • onSuccess method that will be called in case of success. The onSuccess method has one parameter.
    • result : TVDetectionResult. has the following methods:
      • getFrontIdQr(): TVCardQr
      • getBackIdQr(): TVCardQr
  • onError: ErrorCallback. Will be called when an error has occurred during the capturing.
    • error: TVDetectionError
  • onCanceled: CancellationCallback. Will be called when the journey has been cancelled (e.g user clicked on back button...)

3.2.3 Upload QR images

If the APIs is called by the SDK, please skip this step.

if result.getFrontIdQr().isRequired() is true then result.getFrontIdQr().getImages() array should be non-empty. Otherwise, clients should be warned to re-capture id card photos.

QR images will be uploaded with this api: https://ekyc.trustingsocial.com/api-reference/customer-api/#upload-image

val frontQrImage = result.frontIdQr?.images?.getOrNull(i)
val metadata: Map<String,String>? = frontQrImage?.metadata
val label: String? = frontQrImage?.label
val data: ByteArray? = frontQrImage?.imageByteArray

*The same logic will be applied to result.getBackIdQr()

3.3. Scan NFC

The NFC scanner activity will show the guideline screen, the scanner popup. To start the NFC scanner activity.

3.3.1. Set config parameters

val configuration = TVNfcConfiguration(
    nfcCode = nfcCode,
    hashSod = sod,
    issueDate = issueDate,
    cachedFields = cachedFields,
    isRequestReadImageNfc = true,
    isRequestIntegrityCheckNfc = true,
    isRequestCloneDetectionNfc = true,
    nfcMaxRetries = 5,
    isEnableCheckNfcData = true,
    isEnableVerifyNfc = true
)

Options:

• setNfcCode: String is the id number of ID card
• setHashSod: String (optional) is the hash of SOD
• setIssueDate: String (optional) is the issue date of ID card (DD/MM/YYYY)
• setCachedFields: List<String> (optional) is the list of fields that was cached from previous scanning
• setRequestReadImageNfc: boolean (optional) read image in the chip when scan nfc or not
• setRequestIntegrityCheckNfc: boolean (optional) check integrity of the chip when scanning nfc or not
• setRequestCloneDetectionNfc: boolean (optional) check clone of the chip when scanning nfc or not
• setNfcMaxRetries: Int. (optional) The maximum number of times the SDK retries an NFC scanning before giving up
• setEnableCheckNfcData: boolean. Enable check NFC data or not. If it's true then the SDK will call the API to get sod and cached fields of the NFC data.
• setEnableVerifyNfc: boolean. Enable verify NFC or not. If it's true then the SDK will call the API to verify the NFC data.

3.3.2. Start nfc scanning activity from configuration

TrustVisionSDK.startNfcScanning(activity, configuration, object : TVCapturingCallBack() {
    override fun onError(error: TVDetectionError) {

    }

    override fun onSuccess(result: TVDetectionResult) {

    }

    override fun onCanceled(reason: TVCancelReason) {

    }

})

where:

• activity: is the current Activity being displayed
• configuration: the configuration would like to pass to nfc scanning activity
• callback: is an object of type TVCapturingCallBack . It is an interface that has 3 methods
  • onSuccess method that will be called in case of success. The onSuccess method has one parameter.
    • result : TVDetectionResult. has the following methods:
      • getNfcInfoResult(): TVNfcInfoResult
  • onError: ErrorCallback. Will be called when an error has occurred during the capturing.
    • error: TVDetectionError
  • onCanceled: CancellationCallback. Will be called when the journey has been cancelled (e.g user clicked on back button...)

3.4. Face authentication

The Face Authentication activity will show the guideline screen. To start the Face Authentication activity.

3.4.1. Set config parameters

val configuration = TVFaceAuthenticationConfiguration(
    cusUserId = "1",
    authType = AuthType.AUTH,
    authMode = TVAuthMode.FlashEdge(),
    isEnableFaceAuthentication = true,
    isEnableFaceRegistration = true
)

Options:

• cusUserId: String. The customer user id
• authType: AuthType. Type of authentication, AUTH or REGISTRATION
• authMode: TVAuthMode. The source of authentication process, it might be Nfc or Selfie
• isEnableFaceAuthentication: boolean. Enable call API face authentication or not
• isEnableFaceRegistration: boolean. Enable call API face registration or not

3.4.2. Start face authentication with configuration

TrustVisionSDK.startFaceAuthentication(activity, configuration, object : TVCapturingCallBack() {
    override fun onNewFrameBatch(frameBatch: FrameBatch) {
    }
    override fun onError(error: TVDetectionError) {
    }
    override fun onSuccess(result: TVDetectionResult) {
    }
    override fun onCanceled(reason: TVCancelReason) {
    }
})

where:

• activity: is the current Activity being displayed
• configuration: the configuration would like to pass to nfc scanning activity
• callback: is an object of type TVCapturingCallBack . It is an interface that has 3 methods
  • onNewFrameBatch: NewFrameBatchCallback. can be called multiple times during the capturing to return frame data.
    • frameBatch: FrameBatch
      • getId(): String. batch id generated by TV SDK
      • getFrames(): List<TVFrameClass>. batch frame to push
      • getMetadata(): Map<String, String>. batch metadata to push
      • getValidVideoIds() Set<String>. For debugging purpose only
  • onSuccess method that will be called in case of success. The onSuccess method has one parameter.
    • result : TVDetectionResult. has the following methods:
      • getFaceAuthenticationResult(): TVFaceAuthenticationResult
      • getFaces(): List<TVImageClass>
      • getGestureFaces(): List<TVGestureFace>
  • onError: ErrorCallback. Will be called when an error has occurred during the capturing.
    • error: TVDetectionError
  • onCanceled: CancellationCallback. Will be called when the journey has been cancelled (e.g user clicked on back button...)

3.4.3 Sample code

Note: Sample code for face authentication in the case of initializing the SDK with the parameters endpoint, accessKeyId, and accessKeySecret.

val configuration = TVFaceAuthenticationConfiguration(
    cusUserId = "1",
    authType = AuthType.AUTH,
    authMode = TVAuthMode.FlashEdge(),
    isEnableFaceAuthentication = false,
    isEnableFaceRegistration = false
)
TrustVisionSDK.startFaceAuthentication(activity, configuration, object : TVCapturingCallBack() {
    override fun onError(error: TVDetectionError) {

    }
    override fun onSuccess(result: TVDetectionResult) {
        val faceIds: List<TVImageClass> = result.faces?.map {
          TVSyncFile.createById(it.imageId)
        } ?: emptyList()
        val gestureFaces: List<TVGestureFace> = result.gestureFaces?.map {
          val gesture = it.gesture
          val ids = it.images.map { img -> TVSyncFile.createById(img.imageId) }
          TVGestureImage(gesture, ids)
        } ?: emptyList()
        val videoIds = result.livenessFrameBatchIds?.map {
          TVVideoFile.createById(it)
        }
        val cusUserId = "1"
        val selfieType = "selfie"
        val authType = "transfer"

        // SDK uploads images to the server and returns the image IDs to the host app
        // call api to verify face authentication
        // https://ekyc.trustingsocial.com/api-reference/customer-api#request-face-authentication
        yourMethodToCallFaceAuthenticationAPI(
            cusUserId,
            faceIds,
            gestureFaces,
            videoIds,
            selfieType,
            authType
        )
    }
    override fun onCanceled(reason: TVCancelReason) {

    }
})

3.5. Error handling

// [FlowStartingFunc]: startIdCapturing, startSelfieCapturing, startQRScanning, startNfcScanning
TrustVisionSDK.[FlowStartingFunc](activity, configuration, object : TVCapturingCallBack() {
    override fun onError(error: TVDetectionError) {
        val message = error.errorDescription
        Log.d("", message)
        showToast(message)

        ///////////////////////////////////////
        // ERROR HANDLER
        val code = error.errorCode
        val description = error.errorDescription
        val detailErrorCode = error.detailErrorCode

        when (code) {
            TVDetectionError.CONFIGURATION_ERROR -> {
                // Invalid configuration
            }
            TVDetectionError.DETECTION_ERROR_PERMISSION_MISSING -> {
                // No camera permission.
            }
            TVDetectionError.DETECTION_ERROR_CAMERA_ERROR -> {
                // The camera can't be opened.
            }
            TVDetectionError.DETECTION_ERROR_SDK_INTERNAL -> {
                // The SDK has an unexpected error.
            }
            TVDetectionError.DETECTION_ERROR_NFC -> {
                // The SDK has an unexpected error when scanning NFC
            }
            TVDetectionError.DETECTION_ERROR_API_ERROR -> {
                // The SDK has an unexpected error when calling API
                // https://ekyc.trustingsocial.com/api-reference/customer-api#response-errors
            }
            TVDetectionError.DETECTION_ERROR_MAX_RETRY -> {
                // When the SDK reaches the maximum timeout, this only applies to FlashLiveness
            }
        }
    }

    override fun onSuccess(result: TVDetectionResult) {

    }

    override fun onCanceled(reason: TVCancelReason) {

    }

})

4. Additional built-in API

The SDK provides some built-in API for quick detection

4.0. Detect if device support NFC

Allow users to quick check if device support NFC so that they can determine for their next step

val isNfcSupport: Boolean = TrustVisionSDK.isNfcSupport(Context)

4.1. Get Device Info

Allow users to get device information: DeviceInfo

val info: DeviceInfo = TrustVisionSDK.getDeviceInfo(Context)

DeviceInfo contains following properties (will return empty string if SDK cannot get information of that property)

Location contains following properties (will return empty string if SDK cannot get information of that property)

API Interface

1. TVLivenessResult

2. TVDetectionResult

3. TVGestureFace

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...
• TVLivenessMode.FLASH: Use challenge-response approach (advanced). User needs to follow and finish all steps when capturing selfie like far, close, flash. We have different mechanisms for flash:
  • TVLivenessMode.FLASH_EDGE: less frames for detecting than advanced.
  • TVLivenessMode.FLASH_ADVANCED: full frames, highest quality for liveness detection.
  • TVLivenessMode.FLASH_8: use around 8 frames for liveness detection.
  • TVLivenessMode.FLASH_16: use around 16 frames for liveness detection.
  • TVLivenessMode.FLASH_32: use around 32 frames for liveness detection.

9. TVDefaultCameraSide (Enum)

• TVDefaultCameraSide.FRONT
• TVDefaultCameraSide.BACK

10. FrameBatch

11. TVFrameClass

11. ErrorCallback (Callback)

Will be called in case failed. Parameters:

• error: TVDetectionError.

12. CancellationCallback (Callback)

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

13. TVNfcInfoResult

14. TVNfcVerificationResult

14. TVNfcVerificationStatus

15. TVAuthMode (Sealed)

• TVAuthMode.Nfc: process face authentication from IDCard with Nfc Chip.
  • config: [TVIDConfiguration] ID Card configuration
• TVAuthMode.Selfie: process face authentication from front side camera. This is an abstract mode, it has many implementation modes.
  • config: [TVSelfieConfiguration] Selfie configuration
  • livenessMode: [TVLivenessMode] selfie liveness mode
  • TVAuthMode.Passive: implementation of TVAuthMode.Selfie that using PASSIVE livenessMode
  • TVAuthMode.Active: implementation of TVAuthMode.Selfie that using ACTIVE livenessMode
  • TVAuthMode.Flash: implementation of TVAuthMode.Selfie that using FLASH livenessMode
  • TVAuthMode.FlashEdge: implementation of TVAuthMode.Selfie that using FLASH_EDGE livenessMode
  • TVAuthMode.FlashAdvanced: implementation of TVAuthMode.Selfie that using FLASH_ADVANCED livenessMode
  • TVAuthMode.Flash8: implementation of TVAuthMode.Selfie that using FLASH_8 livenessMode
  • TVAuthMode.Flash16: implementation of TVAuthMode.Selfie that using FLASH_16 livenessMode
  • TVAuthMode.Flash32: implementation of TVAuthMode.Selfie that using FLASH_32 livenessMode

16. TVFaceAuthenticationResult

UI Customization

This document introduces how to enable the ability to customize UI components of TrustingVision SDK.

Default UI prototypes

Check out the default UI of TrustingVision SDK. We provide you the ability to change and modify many UI components: background colors, font interfaces, font sizes, icons, buttons.

Before initialize the SDK

Initialize and change properties of TVTheme class. If any of which is not set, it will get default value.

After that, input the instance of TVTheme as a parameter of the TV SDK's initialization method. See Initialize TV SDK

TVTheme let you custom and override attributes, which includes:

Common UI components

Object TVThemeDefaultValues helps you to quickly change some common UI components that will be used across the whole SDK.

In case a specific Screen's theme is set, it will override TVThemeDefaultValues's properties.

The object TVLabelTheme can be described in this table below:

Here is a snipped code example:

private fun customizeTVCommonThemes() {
    // Common Title label theme
    val titleLabelThemeDefault = titleLabelTheme
    titleLabelThemeDefault.font = your_font
    // there are more to be customized...

    // Common Normal label theme
    val normalLabelThemeDefault = normalLabelTheme
    normalLabelThemeDefault.textSize = your_text_size
    // there are more to be customized...

    // Common Instruction label theme
    val instructionLabelTheme = instructionLabelTheme
    instructionLabelTheme.textColor = your_text_color
    // there are more to be customized...

    // Common Error label theme
    val errorLabelThemeDefault = errorLabelTheme
    errorLabelThemeDefault.cornerRadius = your_corner_radius
    // there are more to be customized...

    // Common Timeout label theme
    val timeoutLabelThemeDefault = timeoutLabelTheme
    timeoutLabelThemeDefault.backgroundColors = your_background_colors
    // there are more to be customized...
}

ID Card Detection: UI customization

Class TVIdCapturingTheme

If a property is not set then the default value will be used.

ID Card Confirmation: UI customization

Class TVIdConfirmationTheme

If a property is not set then the default value will be used.

Selfie Capturing: UI customization

Class TVSelfieCapturingTheme

If a property is not set then the default value will be used.

Selfie Confirmation: UI customization

Class TVSelfieConfirmationTheme

If a property is not set then the default value will be used.

QR Popup: UI customization

Class TVQrPopupTheme

If a property is not set then the default value will be used.

Here is a snipped code example:

private fun initTVTheme(): TVTheme {
    val customizedTheme = TVTheme()

    // Selfie capturing screen
    customizedTheme.selfieCapturingTheme.gestureTheme.lookStraightActiveImage = your_image
    // there are more to be customized...

    // Selfie confirmation screen
    customizedTheme.selfieConfirmationTheme.retryButtonImage = your_image
    // there are more to be customized...

    // Id capturing screen
    customizedTheme.idCapturingTheme.maskViewNeutralImage = your_image
    // there are more to be customized...

    // Id confirmation screen
    customizedTheme.idConfirmationTheme.closeButtonImage = your_image
    // there are more to be customized...

    // QR guideline popup
    customizedTheme.qrGuidelinePopupTheme.headerImage = your_image
    // there are more to be customized...

    // QR guideline popup
    customizedTheme.qrRetryPopupTheme.backgroundColor = your_color
    // there are more to be customized...
    return customizedTheme
}