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

User Onboarding

All APIs were called from the Bank's backend. No API calls at SDK. Reference Scenario Scenario 1

Step 1: Get settings from Backend

  • Define flow_id to use for your business: eg. retail or enterprise

Use API directly: Get client settings
Use Java SDK: Java API librarary

Sample code

java
// Get client settings
String flowID = "retail"
TVResponseData<TVClientSettings> response = TVApi.getInstance().getClientSettings(flowID);
if (response.hasErrors()) {
    List<TVApiError> errors = response.getErrors();
    System.out.println("Get client settings error:" + errors.get(0).getMessage());
} else {
    System.out.println("Get client settings successful");
}
System.out.println(response.getRawJSON());

Step 2: Init SDK with settings from Step 1

Pass the settings string from step 1 to parameter jsonConfigurationByServer
Android: Init SDK
iOS: Init SDK
React Native: Init SDK
Flutter: Init SDK

Sample code

kotlin
val config = TVInitializeConfiguration(
    jsonConfigurationByServer = jsonConfigurationByServer,
    languageCode = languageCode,
    theme = theme
)

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    TrustVisionSDK.init(context, config, object : TVInitializeListener {
        override fun onInitSuccess(result: TVInitResult) {
            // Start capture ID card or capture selfie
            // eg. TrustVisionSDK.startIDCapturing(...)
            // or TrustVisionSDK.startSelfieCapturing(...)
        }

        override fun onInitError(error: TVDetectionError) {
            // Handle errors
        }
    })
}

Step 3: Start capture the frontside of ID Card after init SDK successfully.

Android: Start capture ID Card
iOS: Start capture ID Card
React Native: Start capture ID Card
Flutter: Start capture ID Card

Parameters:

paramAndroidiOS
cardTypesReferenceReference
cardSidecardSide = TVSDKConfiguration.TVCardSide.FRONTcardSide: TVIdCardConfiguration.TVCardSide.front

Sample code

Kotlin
val configuration = TVIDConfiguration(
    enableSound = true,
    cardTypes = selectedCards,
    cardSide = TVSDKConfiguration.TVCardSide.FRONT,
    isReadBothSide = false,
    isEnableScanNfc = true,
    isEnableScanQr = true,
    isEnablePhotoGalleryPicker = false,
    isEnableTiltChecking = false,
    isSkipConfirmScreen = true,
    isEnableUploadFrames = false,
    isEnableUploadImages = false,
    isEnableSanityCheck = false,
    isEnableDetectIdCardTampering = false,
    isEnableReadCardInfo = false,
    isEnableCheckNfcData = false,
    isEnableVerifyNfc = false
)
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? {

    }
})

Step 4: Mobile App receives result images from SDK

Images: The result was returned after the SDK finish.

Android: Handle results from SDK
iOS: Handle results from SDK
React Native: Handle results from SDK
Flutter: Handle results from SDK

  1. SDK output result images.
  2. Mobile App upload images to server.
  1. After upload all images finish go to step 5.

Sample code

Kotlin
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)
    }
}

Step 5: Integrate client's backend call TS's backend

After you have image id from upload, you can call API ID card sanity, ID Card tampering and OCR

Step 6: Repeat from step 3 to step 5 for backside of ID card.

Step 7: Start capture the Selfie

Android: Start capture the Selfie
iOS: Start capture the Selfie
React Native: Start capture the Selfie
Flutter: Start capture the Selfie

Parameters:

paramAndroidiOS
livenessModelivenessMode = TVLivenessMode.FLASH_16livenessMode: TVLivenessMode.flash_16

Sample code

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

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) {

    }
})

Step 8: Mobile App receives result images, frames videos from SDK

Images: The result was returned after the SDK finish.

Android: Handle results from SDK
iOS: Handle results from SDK
React Native: Handle results from SDK
Flutter: Handle results from SDK

Video frames: The result will return each batch while user perform action in realtime.

Android: Handle results from SDK iOS: Handle results from SDK

  1. SDK output result images, and frames videos.
  2. Mobile App upload images and frames videos to server.
  1. After upload all images, frames videos finish go to step 9.

Note: frames video were batched and sent to host app via method onNewFrameBatch to upload async.

Sample code: Recive video frames via callback onNewFrameBatch

Kotlin
// 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
}

Sample code: Recive images after SDK finish.

Kotlin
// 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)
        }
    }
}

Step 9: Integrate client's backend call TS's backend

After you have image id, video id from upload, you can call API Portrait sanity, Liveness check and Compare face with image_id of ID card frontside from step 5. Note: Use last frontal image_id to call API Portrait sanity, Compare face with image_id of ID Card, Search face and Index face.

I.2 Hybrid: Share APIs called for both SDK and client's backend.

There are some APIs called from SDK. There are some APIs called from the client's backend. Reference Scenario Scenario Hybrid

Step 1: Create temporary credentials with a verified session token.

Use API directly: Create temporary credential
Use Java SDK: Create temporary credentials

Sample code

java
// Create temporary credentials
int durationInSeconds = 900;
String transactionID = "";
String xRequestID = "";
String xRequestID2 = "";
Map<String, String> headers = new HashMap<String, String>();
headers.put("X-Request-Id", xRequestID);
headers.put("X-Request-Id2", xRequestID2);
TVTemporaryCredentialRequest request = new TVTemporaryCredentialRequest(durationInSeconds);
TVResponseData<TVTemporaryCredentialResponse> response = TVApi.getInstance().createTemporaryCredential(request, transactionID, headers);
System.out.println("TVTemporaryCredentialResponse: " + GsonUtils.toJson(response));
if (response.hasErrors()) {
    List<TVApiError> errors = response.getErrors();
    System.out.println("Create temporary credentials error:" + errors.get(0).getMessage());
} else {
    System.out.println("Create temporary credentials successful");
}

Secure X-Request-ID2 to return SDK

Use Java SDK: Reference

Return Mobile values to init SDK

propsdescription
x-request-idAPI reconciliation. Reference
x-request-id2Hash(x-request-id2). Reference
access_keythe value from API temporary credentials. Reference
secret_keythe value from API temporary credentials. Reference
face_auth_endpointthe value from TS's administrator

Step 2: Init SDK with temporary credential from Step 1

Android: Init SDK
iOS: Init SDK
React Native: Init SDK
Flutter: Init SDK

Parameters:

The flowId parameter is defined for each use-case differently

flowIddescription
retailOnboarding for retail customer
enterpriseOnboarding for enterprise customer
...You can define any authentication type based on your business

Other parameters:

parameterdescription
endpointFrom step 1. Please contact administrator to get correct endpoint
accessKeyIdFrom step 1
accessKeySecretFrom step 1
xRequestIdFrom step 1
xRequestId2From step 1

Which endpoint depend on each environment of country: Testing:

Sample code

kotlin
val config = TVInitializeConfiguration(
    endpoint = endpoint,
    accessKeyId = accessKeyId,
    accessKeySecret = accessKeySecret,
    xRequestId = xRequestId,
    xRequestId2 = xRequestId2_of_backend at step1,
    flowId = flowId,
    languageCode = languageCode,
    theme = theme
)

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    TrustVisionSDK.init(context, config, object : TVInitializeListener {
        override fun onInitSuccess(result: TVInitResult) {
            // Start capture ID card or capture selfie
            // eg. TrustVisionSDK.startIDCapturing(...)
            // or TrustVisionSDK.startSelfieCapturing(...)
        }

        override fun onInitError(error: TVDetectionError) {
            // Handle errors
        }
    })
}

Step 3: Start capture the frontside of ID Card after init SDK successfully.

Android: Start capture ID Card
iOS: Start capture ID Card
React Native: Start capture ID Card
Flutter: Start capture ID Card

Parameters:

paramAndroidiOS
cardTypesReferenceReference
cardSidecardSide = TVSDKConfiguration.TVCardSide.FRONTcardSide: TVIdCardConfiguration.TVCardSide.front
isEnableUploadImagesisEnableUploadImages = trueisEnableUploadImages: true
isEnableUploadFramesisEnableUploadFrames = trueisEnableUploadFrames: true

Sample code

Kotlin
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 = false,
    isEnableDetectIdCardTampering = false,
    isEnableReadCardInfo = false,
    isEnableCheckNfcData = false,
    isEnableVerifyNfc = false
)
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? {

    }
})

Step 4: Mobile App receives result image IDs from SDK

Images: The result was returned after the SDK finish.

Android: Handle results from SDK
iOS: Handle results from SDK
React Native: Handle results from SDK
Flutter: Handle results from SDK

  1. SDK output result image ID and go to step 5.

Sample code

Kotlin
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?.imageID
    // With back side
    backCardId = result.backCardImage?.imageID

    // 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?.imageID
    backQrId = result.backIdQr?.imageID
}

Step 5: Integrate client's backend call TS's backend

After you have image id from upload, you can call API ID card sanity, ID Card tampering and OCR

Step 6: Repeat from step 3 to step 5 for backside of ID card.

Step 7: Start capture the Selfie

Android: Start Face Authentication
iOS: Start Face Authentication
React Native: Start Face Authentication
Flutter: Start Face Authentication

Parameters:

paramAndroidiOS
livenessModelivenessMode = TVLivenessMode.FLASH_16livenessMode: TVLivenessMode.flash_16
isEnableUploadImagesisEnableUploadImages = trueisEnableUploadImages: true
isEnableUploadFramesisEnableUploadFrames = trueisEnableUploadFrames: true

Sample code

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

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) {

    }
})

Step 8: Mobile App receives result image IDs, frames video IDs from SDK

Images: The result was returned after the SDK finish.

Android: Handle results from SDK
iOS: Handle results from SDK
React Native: Handle results from SDK
Flutter: Handle results from SDK

Video frames: The result will return each batch while user perform action in realtime.

Android: Handle results from SDK iOS: Handle results from SDK

  1. SDK output result image IDs, and frames video IDs. Go to step 9

Note: frames video were batched and sent to host app via method onNewFrameBatch to upload async.

Sample code: Recive image IDs and video IDs after SDK finish.

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

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)
    }
}

Step 9: Integrate client's backend call TS's backend

After you have image id, video id from upload, you can call API Portrait sanity, Liveness check and Compare face with image_id of ID card frontside from step 5. Note: Use last frontal image_id to call API Portrait sanity, Compare face with image_id of ID Card, Search face and Index face.