• About TrustVision
  • APP TS eKYC/FA Guideline
  • eKYC SDK & API
    Android SDK
    iOS SDK
    Flutter SDK
    React Native SDK
    Web SDK
    API Client Libraries
TrustVision API Documentation

React Native 4.0.4.x

1 Installation

1.1. Add Trust Vision React Native lib

Add to package.json file under dependencies group:

"react-native-trust-vision-SDK": "git+https://<github_token>:[email protected]/tsocial/<repo_name>#<version_tag_name>"

1.2. Run

$ yarn

1.3 iOS

1.3.1. Add to podfile

...
pod 'RNTrustVisionRnsdkFramework', path: '../node_modules/react-native-trust-vision-SDK'

...

# Add below lines to the end of podfile
post_install do |installer|
    installer.pods_project.targets.each do |target|
        target.build_configurations.each do |config|
            config.build_settings['OTHER_SWIFT_FLAGS'] = '$(inherited) -no-verify-emitted-module-interface'
        end

        // you can add more modules which have the error "Undefined symbol" into the list
        if ['TensorFlowLiteC', 'TensorFlowLiteSwift', 'PromiseKit', 'CryptoSwift'].include? "#{target}"
            target.build_configurations.each do |config|
                config.build_settings['BUILD_LIBRARY_FOR_DISTRIBUTION'] = 'YES'
            end
        end
    end
end

1.3.2. Run

$ pod install

1.4 Android

Add to root-level build.gradle file (host app):

maven {
     url("$rootDir/../node_modules/react-native-trust-vision-SDK/android/repo")
}

eg:

allprojects {
    repositories {
        mavenLocal()
        ...
        maven {
             url("$rootDir/../node_modules/react-native-trust-vision-SDK/android/repo")
        }
        google()
        jcenter()
        maven { url 'https://jitpack.io' }
    }
}

Add to app/build.gradle

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

     // Support 16KB https://developer.android.com/guide/practices/page-sizes
     ndk {
         abiFilters "arm64-v8a", "armeabi-v7a"
    }
}

1.5 Usage

javascript
import { NativeEventEmitter } from "react-native";

import RNTrustVisionRnsdkFramework, {
  TVConst,
  TVErrorCode,
  TVThemeCustomization,
} from "react-native-trust-vision-SDK";

Full steps:

javascript
try {
  const initConfig = {
    jsonConfigurationByServer: jsonConfigurationByServer,
    languageCode: languageCode,
  };
  await RNTrustVisionRnsdkFramework.initializeWithConfig(initConfig);

  const tvsdkEmitter = new NativeEventEmitter(RNTrustVisionRnsdkFramework);
  // Listen to the events during the capturing
  const subscription = tvsdkEmitter.addListener("TVSDKEvent", (event) => {
    console.log("TVSDK - " + event.name + " - " + event.params.page_name);
  });

  const selfieConfig = {
    cameraOption: TVConst.SelfieCameraMode.FRONT,
    livenessMode: TVConst.LivenessMode.FLASH_ADVANCED,
    skipConfirmScreen: true,
    isEnableSound: false,
  };
  const faceAuthConfig = {
    cusUserId: "cusUserId",
    authType: TVConst.AuthenType.REGISTRATION,
    authMode: TVConst.AuthenMode.FLASH_8,
    selfieConfig: selfieConfig,
  };
  const faceAuthResult =
    await RNTrustVisionRnsdkFramework.startFaceAuthentication(faceAuthConfig);
} catch (e) {}

2. Initialize SDK

SDK needs to be initialized first

javascript
const initConfig = {
  jsonConfigurationByServer: jsonConfigurationByServer,
  languageCode: languageCode,
  theme: theme,
  endpoint: endpoint,
  accessKeyId: accessKeyId,
  accessKeySecret: accessKeySecret,
  endpointLogger: endpointLogger,
  accessKeyIdLogger: accessKeyIdLogger,
  accessKeySecretLogger: accessKeySecretLogger,
  xRequestId: xRequestId,
  xRequestId2: xRequestId2,
  imageEncryptionKey: imageEncryptionKey,
  securityPublicKey: securityPublicKey,
  flowId: flowId,
  headers: headers,
};
await RNTrustVisionRnsdkFramework.initializeWithConfig(initConfig);

Options:

  • languageCode: String the code of the language that will show and sound to user. E.g Vietnamese (vi), English ( en).
  • imageEncryptionKey: 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.
  • securityPublicKey: 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.
  • theme: 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:

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

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

3. Start the SDK

The SDK provides some built in functions to capture id, selfie, liveness...

3.2. Start ID card capturing

3.2.1. Set config parameters

javascript
const idConfig = {
  cardTypes: [cardType],
  cardSide: TVConst.CardSide.FRONT,
  isEnableSound: true,
  isReadBothSide: false,
  skipConfirmScreen: true,
  isEnablePhotoGalleryPicker: false,
  isEnableUploadFrames: true,
  isEnableUploadImages: true,
  isEnableSanityCheck: true,
  isEnableDetectingIdCardTampering: true,
  isEnableReadCardInfo: true,
  isEnableCheckNfcData: true,
  isEnableVerifyNfc: true,
};

Options:

  • cardTypes: [CardType]. Card types is allowed capture. List of supported cards can be found by RNTrustVisionRnsdkFramework.cardTypes after you initialize the SDK with the clientSettingsJsonString. If not, use :
javascript
const cardType = {
  id: "vn.national_id",
  name: "CMND cũ / CMND mới / CCCD",
  orientation: TVConst.Orientation.HORIZONTAL,
  hasBackSide: true,
  frontQr: {
    exist: true,
    type: "qr_code",
    widthHeightRatio: 1,
  },
};
  • cardSide: TVConst.CardSide. Card side
  • isEnableSound: bool. Sound is played or not
  • isReadBothSide: bool. Read both sides of id card or not
  • skipConfirmScreen: bool. Skip confirmation screen or not
  • isEnablePhotoGalleryPicker: bool. Allow user select id card image from phone gallery
  • isEnableScanQr: bool. Allow user scan QR code or not
  • isEnableScanNfc: bool. Allow user scan NFC or not
  • isEnableUploadFrames: 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.
  • isEnableUploadImages: 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.
  • isEnableSanityCheck: 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.
  • isEnableDetectingIdCardTampering: 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.
  • isEnableReadCardInfo: boolean. Enable read card info or not. If it's true then the SDK will call the API to read the card info.
  • isEnableCheckNfcData: 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.
  • isEnableVerifyNfc: boolean. Enable verify NFC or not. If it's true then the SDK will call the API to verify the NFC.

3.2.2. Start flow

javascript
const result = await RNTrustVisionRnsdkFramework.startIdCapturing(config);

3.2.3. Handle Id card images

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

if result.frontIdQr.is_required is true then result.frontIdQr.images array should be non-empty. Otherwise, clients should be warned to re-capture id card photos.

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

  • Fields:
    • data: result.frontIdQr.images[i].raw_image_base64
    • label: result.frontIdQr.images[i].label
    • metadata: result.frontIdQr.images[i].metadata

*The same logic will be applied to result.backIdQr

3.3. Start selfie capturing

3.3.1. Set config parameters

javascript
const config = {
  cameraOption: TVConst.SelfieCameraMode.FRONT,
  isEnableSound: true,
  livenessMode: TVConst.LivenessMode.FLASH_16,
  skipConfirmScreen: true,
  isEnableUploadFrames: true,
  isEnableUploadImages: true,
  isEnableSanityCheck: true,
  isEnableVerifyLiveness: true,
};

Options:

  • cameraOption: TVConst.SelfieCameraMode. Camera option
  • isEnableSound: bool. Sound is played or not
  • livenessMode: TVConst.LivenessMode. Liveness mode
  • skipConfirmScreen: bool. Skip confirmation screen or not
  • isEnableUploadFrames: 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.
  • isEnableUploadImages: 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.
  • isEnableSanityCheck: boolean. Enable sanity check or not. If it's true then the SDK will call the API to check the sanity of the selfie.
  • isEnableVerifyLiveness: 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.3.2. Start flow

javascript
const selfieCapturingResult =
  await RNTrustVisionRnsdkFramework.startSelfieCapturing(config);

3.3.3. Frame Batch recorded during the capturing.

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

Note: Ignore this section if Frame recording is disabled by client settings.

javascript
var frameBatchIdsDictionary = []; // this dictionary will be used for liveness verification
// frameBatchIdsDictionary.push({
//    key:   <id_returned_from_sdk>,
//    value: <id_returned_from_server>
// });

// Listen to the frame batches recorded during the capturing
const framesRecordedSubscription = tvsdkEmitter.addListener(
  "TVSDKFrameBatch",
  async (frameBatch) => {
    console.log("TVSDK - " + "FrameBatch: ", frameBatch);
    // upload frame batch to server using this api:
    // https://ekyc.trustingsocial.com/api-reference/customer-api/#upload-videoaudioframes
    const uploadingResult = await uploadFrameBatch(frameBatch);
    frameBatchIdsDictionary.push({
      key: frameBatch.batchId,
      value: uploadingResult.fileId,
    });
  }
);

3.3.4. Handle selfie capturing results

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

3.3.4.1 Remove invalid frame batch ids

Note: Ignore this section if Frame recording is disabled by client settings.

Only frame batches of Selfie capturing which id is containing in selfieCapturingResult.livenessFrameBatchIds are valid to be used for liveness verification.

javascript
// Remove all invalid batch ids:
Object.entries(frameBatchIdsDictionary).map(
  ([id_returned_from_sdk, id_returned_from_server]) => {
    if (
      !selfieCapturingResult.livenessFrameBatchIds.includes(
        id_returned_from_sdk
      )
    ) {
      delete frameBatchIdsDictionary[id_returned_from_sdk];
    }
  }
);
3.3.4.2. Use this api to get image id:

https://ekyc.trustingsocial.com/api-reference/customer-api/#upload-image id of frontal image i = image id of selfieCapturingResult.selfieImages[i].frontal_image.raw_image_base64 id of gesture image i = image id of selfieCapturingResult.selfieImages[i].gesture_image.raw_image_base64

3.3.4.3. Call this api to check liveness

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

  • images field, each element contains:
json
{
  "id": "<id of frontal image i>"
}
  • gesture_images field, each element contains:
json
{
  "gesture": "lower case string of <selfieCapturingResult.selfieImages[i].gesture_type>",
  "images": [
    {
      "id": "<id of gesture image i>"
    }
  ]
}
  • videos field is the list of frame batch ids returned from server, which are the values of frameBatchIdsDictionary Note: Ignore this field if Frame recording is disabled by client settings.
json
{
"id": "<frameBatchIdsDictionary's values[0]>"
},
{
"id": "<frameBatchIdsDictionary's values[1]>"
}
...
  • metadata field is selfieCapturingResult.livenessMetadata

3.4. Start QR scanning

3.4.1. Set config parameters

javascript
const config = {
  cardType: cardType,
  cardTypes: [cardType],
  isEnableSound: false,
  skipConfirmScreen: true,
  cardSide: TVConst.CardSide.FRONT,
  isEnableUploadFrames: true,
  isEnableUploadImages: true,
};

Options:

  • cardType: CardType. Card type
  • cardTypes: [CardType]. List of Card type, please init with one item.
  • cardSide: TVConst.CardSide. Card side
  • isEnableSound: bool. Sound is played or not
  • skipConfirmScreen: bool. Skip confirmation screen or not
  • isEnableUploadFrames: boolean. Enable upload video frames or not
  • isEnableUploadImages: boolean. Enable upload images or not

3.4.2. Start flow

javascript
const result = await RNTrustVisionRnsdkFramework.startQRScanning(config);

3.4.3. Upload QR images

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

if result.frontIdQr.isRequired is true then result.frontIdQr.images array should be non-empty. Otherwise, clients should be warned to re-scan QR code.

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

javascript
const frontQrImage = result.frontIdQr.images[i];
const metadata = frontQrImage.metadata;
const label = frontQrImage.label;
const data = frontQrImage.imageByteArray;

*The same logic will be applied to result.backIdQr

3.5. Start NFC scanning

3.5.1. Set config parameters

javascript
const config = {
  nfcCode: nfcCode,
  hashSod: sod,
  issueDate: issueDate,
  cachedFields: cachedFields,
  isRequestReadImageNfc: true,
  isRequestIntegrityCheckNfc: true,
  isRequestCloneDetectionNfc: true,
  nfcMaxRetries: 5,
  isEnableCheckNfcData: true,
  isEnableVerifyNfc: true,
};

Options:

  • nfcCode: String is the id number of ID card
  • hashSod: String (optional) is the hash of SOD
  • issueDate: String (optional) is the issue date of ID card (DD/MM/YYYY)
  • cachedFields: List<String> (optional) is the list of fields that was cached from previous scanning
  • isRequestReadImageNfc: boolean (optional) read image in the chip when scan nfc or not
  • isRequestIntegrityCheckNfc: boolean (optional) check integrity of the chip when scanning nfc or not
  • isRequestCloneDetectionNfc: boolean (optional) check clone of the chip when scanning nfc or not
  • nfcMaxRetries: Int. (optional) The maximum number of times the SDK retries an NFC scanning before giving up
  • isEnableCheckNfcData: 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.
  • isEnableVerifyNfc: boolean. Enable verify NFC or not. If it's true then the SDK will call the API to verify the NFC data.

3.5.2. Start flow

javascript
const result = await RNTrustVisionRnsdkFramework.startNfcScanning(config);

3.6 Start Face Authentication

3.6.1 Set config parameters

javascript
const selfieConfig = {
  cameraOption: TVConst.SelfieCameraMode.FRONT,
  livenessMode: TVConst.LivenessMode.FLASH_ADVANCED,
  skipConfirmScreen: true,
  isEnableSound: false,
};
const config = {
  cusUserId: "cusUserId",
  authType: TVConst.AuthenType.REGISTRATION,
  authMode: TVConst.AuthenMode.FLASH_ADVANCED,
  isEnableFaceAuthentication: true,
  isEnableFaceRegistration: true,
  selfieConfig: selfieConfig,
};
  • 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
  • selfieConfig: TVSelfieConfiguration. The configuration of selfie capturing
  • isEnableFaceAuthentication: boolean. Enable call API face authentication or not
  • isEnableFaceRegistration: boolean. Enable call API face registration or not

3.6.2 Start flow

javascript
await RNTrustVisionRnsdkFramework.startFaceAuthentication(config);

4. Result Handling:

  • result:

    • cardType: CardType. Card type

    • actionMode: TVConst.ActionMode. Action Mode

    • selfieImages: [SelfieImage]. List of selfie image objects

    • livenessVideos: [Base64 String]. List of liveness videos data base64

    • livenessMetadata: json

    • livenessVideoFramesList: [json]

    • idFrontImage: ImageClass. Id front image object

    • idBackImage: ImageClass. Id back image object

    • frontIdQr: TVCardQr. Front Id card's QR info

    • backIdQr: TVCardQr. Back Id card's QR info

    • frontIdCapturingVideoFramesList: json

    • backIdCapturingVideoFramesList: json

    • nfcInfoResult: TVNfcInfoResult. NFC info result

    • faceAuthRegisterResult: TVFaceAuthRegisterResult

    • faceAuthResult: TVFaceAuthResult

  • SelfieImage:

    • gesture_type: String. UP | DOWN | LEFT | RIGHT | FRONTAL
    • frontal_image: ImageClass. Frontal image object
    • gesture_image: ImageClass. Gesture image object

  • ImageClass:

    • raw_image_base64: String. Base64 string of image data
    • label: String. Image label
    • metadata: json. Image metadata

  • TVCardQr:

    • is_required: Bool. This side of card contains QR or not
    • images: [ImageClass]. QR images

  • Error:

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

  • TVNfcInfoResult:

    • com: String
    • sod: String
    • dg1: String
    • dg2: String
    • dg13: String
    • dg14: String
    • dg15: String
    • verificationResult: TVNfcVerificationResult

  • TVNfcVerificationResult:

    • cloneStatus: TVNfcVerificationResultStatus

  • TVNfcVerificationResultStatus:

    • error: TVError
    • verdict: TVNfcVerdict. TVNfcVerdict.notChecked | TVNfcVerdict.alert | TVNfcVerdict.good | TVNfcVerdict.error

  • TVFaceAuthRegisterResult:

    • requestId: String
    • status: String. success | failure

  • TVFaceAuthResult:

    • requestId: String
    • status: String. success | failure
    • score: Float
    • matchResult: MatchResult. MatchResult.match | MatchResult.unmatched | MatchResult.unsure