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

import { NativeEventEmitter } from "react-native";

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

Full steps:

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

  const tvsdkEmitter = new NativeEventEmitter(RNTrustVisionRnsdkFramework);
  // Listen to the frame batches recorded during the capturing
  const subscription = tvsdkEmitter.addListener(
    "TVSDKFrameBatch",
    (frameBatch) => {
      console.log("TVSDK - FrameBatch:", frameBatch.batchId);
    }
  );
  // (Android only) image read from the chip during NFC face authentication:
  // tvsdkEmitter.addListener("TVSDKReadIdCardImage", (image) => { /* ... */ });

  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

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, iOS only). 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. On Android this key is ignored.

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)
• headers: Map<String, String> (optional). The headers to be added to the request.
• flowId: String (optional). The flow id of the API

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.
• enableGetClientSetting: boolean (Android only). Enable fetching the client settings from the server during initialization. Ignored on iOS.

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

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 allowed to capture. The list of supported cards can be retrieved via await RNTrustVisionRnsdkFramework.getCardTypes() after you initialize the SDK with the clientSettingsJsonString. If not, use :

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.

startIdCapturing also reads these options:

• idTamperingLevel: String. ID tampering sensitivity level (passed through as-is).
• idCaptureOnlyMode: boolean. Capture-only mode (skip verification APIs).
• nfcMaxRetries: Int. Maximum NFC scan retries.
• isRequestIntegrityCheckNfc: boolean. Request NFC chip integrity check.
• isRequestCloneDetectionNfc: boolean. Request NFC clone detection.
• isRequestReadImageNfc: boolean. Request reading the chip image.

Additional ID config fields

The ID config also accepts these keys (newly mapped by the wrapper):

3.2.2. Start flow

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

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.

Additional selfie config fields

The selfie config also accepts these keys (newly mapped by the wrapper):

3.3.2. Start flow

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.

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.

// 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:

{
  "id": "<id of frontal image i>"
}

• gesture_images field, each element contains:

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

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

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

Additional QR config field

The QR config also accepts this key (newly mapped by the wrapper):

3.4.2. Start flow

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

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

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

Options:

• nfcCode: String is the id number of ID card
• nfcSod: String (optional) is the hash of SOD
• cardIssueDate: String (optional) is the issue date of ID card (DD/MM/YYYY)
• nfcCacheFields: 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.

Additional NFC config fields

The NFC config also accepts these keys (newly mapped by the wrapper):

¹ Optional in general, but required for the passport / eMRTD MRZ input flow.

3.5.2. Start flow

const result = await RNTrustVisionRnsdkFramework.startNfcScanning(config);

3.6 Start Face Authentication

3.6.1 Set config parameters

const selfieConfig = {
  cameraOption: TVConst.SelfieCameraMode.FRONT,
  livenessMode: TVConst.LivenessMode.FLASH_ADVANCED,
  skipConfirmScreen: true,
  isEnableSound: false,
};
const cardTypes = await RNTrustVisionRnsdkFramework.getCardTypes();
const config = {
  cusUserId: "cusUserId",
  authType: TVConst.AuthenType.REGISTRATION,
  authMode: TVConst.AuthenMode.FLASH_ADVANCED,
  isEnableFaceAuthentication: true,
  isEnableFaceRegistration: true,
  selfieConfig: selfieConfig,
  cardConfig: {
    cardTypes,
    isEnableSound: true,
    isReadBothSide: true,
    skipConfirmScreen: true,
    isEnablePhotoGalleryPicker: false,
    cardSide: TVConst.CardSide.FRONT,
  },
};

• cusUserId: String. The customer user id
• authType: AuthType. Type of authentication, AUTH or REGISTRATION
• authMode: TVConst.AuthenMode. The authentication source — see the AuthenMode table. Can be NFC or a selfie/liveness mode.
• cardConfig: same shape as the ID capturing config — e.g. cardTypes (from getCardTypes()), cardSide, isReadBothSide, skipConfirmScreen, isEnablePhotoGalleryPicker, isEnableSound, … On Android it is consumed only when authMode is TVConst.AuthenMode.NFC (ignored for selfie/liveness modes).
• 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

TVConst.AuthenMode values

3.6.2 Start flow

await RNTrustVisionRnsdkFramework.startFaceAuthentication(config);

3.6.3. Frame Batch recorded during the capturing.

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

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

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 — lowercase value (e.g. 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
  • encrypted_image_hex_string: String. Encrypted image as hex string
  • image_id: String. Server image id
  • metadata: json. Image metadata

• TVCardQr:

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

• Error (rejected Promise):

  When a flow fails, its Promise is rejected with an error you read in catch (e):

  • code: String. The error code — switch on this (see the tables below).
  • message: String. The error description.
    • On iOS: a plain human-readable string (e.g. "SDK is timed out").
    • On Android: the JSON-serialized error, e.g. {"errorCode":1001,"detailErrorCode":"sdk_time_out","errorDescription":"SDK is timed out","details":{}}. Its readable text is errorDescription, and code equals detailErrorCode. The numeric errorCode (e.g. 1001) is an Android-internal value — do not branch on it (it does not exist on iOS); always switch on code.

  The nested error: TVError inside a result (e.g. NFC verification) is a different object: it exposes errorCode: String and description: String.

On Android, message is the JSON-serialized TVDetectionError. Its fields:

Standard TVErrorCode values (exported from the package; identical on Android & iOS)

Other code values a flow may reject with (handle them in a default branch)

For backend failures, the SDK forwards the server's response error code — see Customer API – Response errors. On iOS, capture flows may also return granular detection codes (e.g. noFace, multipleFaces, livenessCheckFailed, idGlare); handle any unrecognized code in default.

• 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

5. Enums reference

All enums are exported from react-native-trust-vision-SDK (TVConst.*, plus the top-level TVErrorCode).