v9.1.0 - v9.5.0 Release Notes

v9.5.0/v9.4.0 Release Notes

v9.3.0 Release Notes

v9.2.0 Release Notes

v9.1.0 Release Notes


v9.5.0/v9.4.0 Release Notes

NFC, Barcode, Arabic OCR & Much More Added!

Note:  If you are upgrading from a version earlier than v9.3.0, be sure to check out the v9.3.0, v9.2.0, and v9.1.0 release notes.

High-level notes about this release:

  1. Added Barcode Scanning Support (PDF417, QR & many more)
  2. Added NFC Chip Scanning Support for ePassports
  3. Arabic Language is now Supported for OCR Templates
  4. Cyrillic Language is now Supported for OCR Templates
  5. Thai Language is now Supported for OCR Templates
  6. Hebrew Language is now Supported for OCR Templates
  7. FaceTec Standard Server (v9), FaceTec Custom Server (v9), and Dashboard have been updated with the new functionality.
  8. Smarter Photo ID Document Auto-Capture
  9. Certain Legacy UI customization APIs have been retired from all Device SDKs.
  10. Increased Security, Bug Fixes, Performance Enhancements, & Stability Improvements throughout the FaceScan and ID Scan process.
  11. Added Face Photo Tamper detection. See Photo ID Anti-Spoofing

Upgrading

3D Liveness, Enrollment, Re-Verification - There are NO Breaking Changes in Device SDKs or FaceTec Servers for these modes.

ID Scan & Photo ID Match - There are No Breaking API Changes with this release, however, there are many new features in the ID Scan process that likely will require developer customization to fully use.

For Organizations currently using ID Scan, please take the following steps:

  1. If you are using Custom OCR Templates, please update them and re-download them.
  2. Please take a look at the new APIs and String Customizations listed on this page and in our Sample Apps.
  3. Please see the UI/UX Customizations Page for more details about the new ID Scan Screens.
  4. The Legacy Result & Upload Message Dynamic Override APIs are now deprecated.  Please use the new versions of these overloads as they contain all possible Strings that can be customized.
  5. Review the new FaceTec Strings files and make sure that you are customizing all of the new Strings that are available in this release.

FaceTec Server Initialization and Usage Log Server Requirements

In a previous release, the default setup for FaceTec Server would connect FaceTec Server instances to the FaceTec Usage Log Server.  The FaceTec Usage Log Server aggregates the log files for all FaceTec Server instances, and handles automatically sending Usage Logs to FaceTec.  As long as the configuration files are correct and FaceTec Server initializes successfully and the FaceTec Usage Log Server initializes successfully, your Server instances are configured correctly and you do not need to handle any details about sending Usage Logs to FaceTec.

In previous versions of the FaceTec SDK, the above functionality was on-by-default, could be turned off, but turning this off was not recommended and was only possible to support legacy implementations.

In v9.4.x, the Usage Log Server is now required, and the only way that Usage Logs can be sent to FaceTec.  If you are upgrading from a recent, previous version of the FaceTec SDK, and did not do any specific work around Usage Logs, you likely do not need to worry about this message, and your FaceTec Server will behave the same as always.

However, some customers who either disabled Usage Log Server in a previous version or who implemented Usage Log sending prior to the existence of FaceTec Usage Log Server, will need to update your deployment configuration to use the new Usage Log Server.  The Usage Log Server runs automatically if you use the default configuration of FaceTec Standard or Custom (v9) Servers, and simply requires that you use the correct configuration options in order to initialize it successfully. 

For more details, please see the FaceTec Standard or Custom (v9) Server packages.  If you download them using the Configuration Wizard, both the FaceTec Server and the Usage Log Server will be configured with correct parameters for successful initialization (assuming that outbound connections from your network are configured correctly).

Finally, initialization of the FaceTec Server in Development Mode has been removed, as this was not being used during our new customer onboarding flow -- instead of initializing in Development Mode, FaceTec now issues temporary Production Keys for FaceTec Server testing.


Adding NFC Support to iOS and Android

In order for apps to access the NFC hardware, Android and iOS Apps must be configured correctly.

Adding Android Support:

Declare these items in your AndroidManifest.xml:

<uses-permission android:name="android.permission.NFC"/>
<uses-feature android:name="android.hardware.nfc"android:required="false"/>

Adding iOS Support:

 - Device: iOS 13.0 and above
 - Device: iPhone 7+ (iPads don't have NFC readers)
 - App: Must have "Near Field Communication Tag Reading" added in its project settings ("Signing & Capabilities" > "+ Capability" > "Near Field Communication Tag Reading")
 - App: Must have "Privacy - NFC Scan Usage Description" key set in target properties (Info.plist)
 - App: Must have "ISO7816 application identifiers for NFC Tag Reader Session" filled in target properties (Info.plist)

<key>com.apple.developer.nfc.readersession.iso7816.select-identifiers</key>
<array>
  <string>A0000002471001</string>
  <string>A0000002472001</string>
  <string>00000000000000</string>
</array>

The documentData Object

In v9.4.0, the old "ocrResults" object has been deprecated and the contents remain unchanged from previous behavior.

New in v9.4.0, we have created a documentData object that holds the same data as the ocrResults object, but also has additional data for NFC and Barcode scenarios.

Notes:

  • The documentData object contains properties for:
    • scannedValues - Values specified on the OCR Template that have been OCR'd.
    • userConfirmedValues - Values that the User Submitted from the User Confirmation Page.
    • barcodeValues - Values that were scanned from the Barcode.  
    • nfcValues - Values that were extracted from the NFC Chip.
  • The "extractedInfo" field is special for barcodeValues and nfcValues, and contains the "raw" data (key/value pairs) that was lifted from the Barcode or NFC Scan. FaceTec has created some internal/private NFC and Barcode parsers that attempt to get structured data from the NFC or Barcode scan, but these parsers are not guaranteed to work for all Document Types that exist. We provide the "extractedInfo" property so that the Barcode or NFC data can be parsed by Customers based on their knowledge of specific formats.

Example documentData Object:

{
  "nfcValues": {
    "extractedInfo": {
      "issuingAuthority": "VALUE_SCANNED_FROM_NFC_CHIP",
      "mrzData": "VALUE_SCANNED_FROM_NFC_CHIP",
      "placeOfBirth": "VALUE_SCANNED_FROM_NFC_CHIP"
    },
    "groups": [
      {
        "fields": [
          {
            "fieldKey": "placeOfBirth",
            "uiFieldType": "Alphabetic",
            "value": "VALUE_SCANNED_FROM_NFC_CHIP"
          }
        ],
        "groupFriendlyName": "Your Information",
        "groupKey": "userInfo"
      }
    ]
  },
  "barcodeValues": {
    "extractedInfo": {
      "firstName": "VALUE_SCANNED_FROM_BARCODE",
    },
    "groups": [
      {
        "fields": [
          {
            "fieldKey": "placeOfBirth",
            "uiFieldType": "Alphabetic",
            "value": "VALUE_SCANNED_FROM_BARCODE"
          }
        ],
        "groupFriendlyName": "Your Information",
        "groupKey": "userInfo"
      }
    ]
  },
  "scannedValues": {
    "groups": [
      {
        "fields": [
          {
            "fieldKey": "firstName",
            "uiFieldType": "Alphabetic",
            "value": "VALUE_SCANNED_FROM_PHOTO_ID"
          },
          {
            "fieldKey": "dateOfBirth",
            "uiFieldType": "FORMAT_DEFINED_IN_IDTC",
            "value": "VALUE_SCANNED_FROM_PHOTO_ID"
          },
          {
        ],
        "groupFriendlyName": "Your Information",
        "groupKey": "userInfo"
      }
    ]
  },
  "userConfirmedValues": {
    "groups": [
      {
        "fields": [
          {
            "fieldKey": "firstName",
            "uiFieldType": "Alphabetic",
            "value": "VALUE_ENTERED_ON_USER_CONFIRMED"
          }
        ],
        "groupFriendlyName": "Your Information",
        "groupKey": "userInfo"
      }
    ]
  },
  "templateInfo" :{
    "templateName": "TEMPLATE_NAME",
    "templateType": "TEMPLATE_TYPE",
  }
}

Extracting Date Type Values (Date of Birth, Expiration, Issue, etc.)

Date values can be found in nfcValues, barcodeValues or scannedValues, inside the various "groups" objects.  Date properties contain the raw string value in "value" property, and the Date Format itself is specified in the OCRTemplate in the "uiFieldType" property.  This Date Format is a string containing the characaters "y" (year digit), "m" (month digit), "d" (day digit) or "M" (only appears as "MMM" or "MMMM" and both mean month abbreviation with the number of M's, but also month full name), as well as character delimiters (i.e.: "/", ".", " ", "-", etc).

Examples: Getting Date values from an IDScan response using Java and Python

Get DOB Value using Java

// 1.1 Get the documentData from the result.
String documentDataString = match3D2DIDScanResult.documentData;
JSONObject documentDataJSON = new JSONObject(documentDataString);

// 1.2 Get DOB field JSON (assuming the JSON example above, here you might need to loop through groups and fields to find the date you want)
JSONObject dobField = documentDataJSON["scannedValues"]["groups"][0][1];

// 1.3 Get DOB scannedValue and DOB format as specified in the OCRTemplate
String dobValue = dobField["value"].toString();
String dobFormat = dobField["uiFieldType"].toString();

// 2.0 Use SimpleDateFormat to parse the format and result
SimpleDateFormat format = new SimpleDateFormat(dobFormat);
Date dateObj = format.parse(dobValue); 

Get DOB Value using Python

# Example in Python, by using strptime (C++ is similar)
from datetime import datetime

# Convert from our format string to the expected by the strptime function
dobFormat.replace("MMMM", "%b");
dobFormat.replace("MMM", "%b");
dobFormat.replace("dd", "%d");
dobFormat.replace("yyyy", "%Y");
dobFormat.replace("mm", "%m");
dobFormat.replace("yy", "%y");
dateTimeObj = datetime.strptime(dobValue, dobFormat)

NFC Support in OCR Templates

The FaceTec SDK now supports scanning ePassports with NFC Chips.  To enable ePassport scanning, ensure the OCR Template you are creating has NFC Enabled on the Template Settings.

Implementation Notes:

  • iOS Support - iOS 13 and above.
  • Android Support - All Android Devices with NFC Support are supported.
  • Browser Support - While most modern Browsers have basic NFC Support, no modern Browser supports specific NFC features required to scan ePassports.  Thus, Browser is not supported.
  • On Browser, or on Android Devices without NFC Support, or on iOS 12 and below devices, if the OCR Template specifies NFC is Enabled, the NFC step will simply be skipped.
  • On Android, if NFC is supported, but turned off via settings, customizable UI will be shown to guide the User to turning on NFC before proceeding.
  • iOS uses a built-in UI similar to FaceID and Apple Pay to guide Users to using NFC.  This UI is required.  FaceTec has exposed all possible NFC String customizations possible for this built-in UI to Developers.
  • v9.4.0 contains a variety of new String customizations for the upload, success, retry, and skip behavior introduced by adding NFC support.  Please see the Sample Apps for exhaustive examples of how to customize the NFC experience on both iOS and Android.
  • Matching of the 3D FaceMap to the Image from the NFC Chip is performed during the NFC portion of the flow and the Match Level is returned.

Barcode Support in OCR Templates

The FaceTec SDK now supports scanning a variety of Barcodes, including PDF417, QR Codes, and more!  To scan Barcodes, the OCR Template must be marked up with the Barcode location and the Barcode Type.

Barcode data is returned to you on the documentData object in raw format in the "extractedInfo" property.  Structured data is returned if possible, however, there are numerous formats for the extracted Barcode data and FaceTec only supports several prominent formats.


Arabic Support in OCR Templates

The FaceTec SDK now supports the Arabic Language.  To OCR Arabic characters, the OCR Template must have fields marked correctly specifying Arabic.

The following Official OCR Templates have been updated to OCR data in Arabic:

  • Egypt - National ID Card - 2005 - Horizontal
  • Algeria - National ID Card - 2017 - Horizontal

These Official OCR Templates have been added and come pre-installed with the FaceTec Server:

  • Saudi Arabia - ID Card (Resident) - 2020_UC - Horizontal
  • Lebanon - Driver License - 2021_UC
  • Syria - National ID Card - 1998 - Horizontal

Behavior Caveats:

  • The OCR Template Creator doesn’t support marking a field designator in one charset (Latin for example) and its contents in a different charset (Arabic for example). Both the designator and the content must use the same character set.

Cyrillic Support in OCR Templates

The FaceTec SDK now supports the Cyrillic Language.  To OCR Cyrillic characters, the OCR Template must have fields marked correctly specifying Cyrillic.

Behavior Caveats:

  • The OCR Template Creator doesn’t support marking a field designator in one charset (Latin for example) and its contents in a different charset (Cyrillic for example). Both the designator and the content must use the same character set.

Thai Support in OCR Templates

The FaceTec SDK now supports the Thai Language.  To OCR Thai characters, the OCR Template must have fields marked correctly specifying Thai.

Behavior Caveats:

  • The OCR Template Creator doesn’t support marking a field designator in one charset (Latin for example) and its contents in a different charset (Thai for example). Both the designator and the content must use the same character set.

Hebrew Support in OCR Templates

The FaceTec SDK now supports the Hebrew Language.  To OCR Hebrew characters, the OCR Template must have fields marked correctly specifying Hebrew.

This Official OCR Template has been added and comes pre-installed with the FaceTec Server:

  • Israel - National ID Card - 2020 - Horizontal

Behavior Caveats:

  • The OCR Template Creator doesn’t support marking a field designator in one charset (Latin for example) and its contents in a different charset (Hebrew for example). Both the designator and the content must use the same character set.

iOS Config Wizard Sample App Note

Please note that the iOS SDK Config Wizard build will not run until you register your Bundle ID with Apple and add NFC support to your Application profile in your Apple Account.


v9.3.0 Release Notes

Template Creator v1 released, OCR Improvements and more!

Note: If you are upgrading from a version earlier then v9.2.0, be sure to check out the v9.2.0 and v9.1.0 release notes.

High-level notes about this release:

  1. Photo ID OCR Template Creator Released.
  2. Significant OCR accuracy improvements.  Text processing is much faster and compute is more efficient.
  3. Numerous UI/UX compatibility fixes and tuning throughout 3D Face and ID Scanning.
  4. In the Device SDKs, ID Scan Auto-Capture is much faster, and is more accurate.
  5. In the Device SDKs, Camera Auto-Focus logic is greatly improved.
  6. Upload Progress message customization added. See below for more details.
  7. OCR User Confirmation Screen Text Customization & Localization added.  See below for more details.

Upgrading

Breaking API Changes: There are NO breaking API changes in this release.

New APIs and Behavior Changes: Added new APIs to customize the text in different parts of the ID Scan process. Developers can now customize the upload message dynamically for each upload during ID Scan. Developers can also configure localization for the FaceTec ID Scan User OCR Confirmation Screen.

ID Scan Upload Text

There are several new scenarios that occur during ID Scan Upload. The text shown for these scenarios is controlled by the fully-dynamic programmatic API called setIDScanUploadMessageOverrides.

The below table shows the various messages that can be customized and localized:

 On Upload StartOn Upload Slow Network DetectedOn Upload CompleteDuring Server Processing
Front Scan"Uploading<br/>Encrypted<br/>ID Scan""Still Uploading...<br/>Slow Connection""Upload Complete""Processing ID Scan"
Back Scan"Uploading<br/>Encrypted<br/>Back of ID""Still Uploading...<br/>Slow Connection""Upload Complete""Processing Back of ID"
User Confirmation"Uploading<br/>Your Confirmed Info""Still Uploading...<br/>Slow Connection""Upload Complete""Processing"

A working example of setting these strings is included in the sample PhotoIDMatchProcessor code.

OCR Localization

Developers can now dynamically configure the strings to be used on the OCR Confirmation Screen using the new configureOCRLocalization API.

For the configureOCRLocalization API parameter, you may use any object that follows the same structure and key naming as the Template JSON file, "FaceTec_OCR_Customization.json", found in each Sample App's resources folder.

A working example of this API is in each the SampleAppUtilities code.

OCR Template Creator Released

You can now create your own OCR Templates and modify existing templates using the OCR Template Creator.

OCR Template Creator allows you to Accept ANY ID Document Type for the languages we support. To download already-existing ID Templates, or to create your own, please visit the OCR Template Creator.

FaceTec Server Dependency Update

The FaceTec Server Core now uses libc v2.28 (previously v2.17 was used). This change is required as many dependent libraries have upped their minimum requirements for the version of libc that is used, as v2.17 is a very old version. Updating the v2.28 has an added benefit to performance. In our measurements, Face and ID Scanning are 5-10% faster.

You may be required to use a newer base image that supports libc v2.28. If you are having issues you may see an error during initialization that the GLIBC version is not supported.


v9.2.0 Release Notes

Now Featuring Photo ID Optical Character Recognition (OCR) & Auto-Capture

We are pleased to announce the availability of the FaceTec SDKs v9.2.0!

High-level notes about this release:

  1. FaceTec Server now outputs text OCR'd from the Photo ID.
  2. Photo ID OCR Template Creator allows you to Accept ANY ID Type for the languages we support.
  3. FaceTec Customers can create their own OCR Templates using the OCR Template Creator.
  4. Photo IDs are auto-captured instead of requiring the User to press the “Take Photo” button. If the User experiences issues with auto-capture, a fallback is in place to take photos with a button press.
  5. The ID Scan process now allows the User to confirm the information OCR'd from the ID.
  6. For Face Scanning (3D Liveness, Enrollment, and 3D:3D Matching), we have kept current code compatible and added a new & recommended default calling convention for handling results in the Device SDK Processors.

Upgrading (3D Liveness, Enrollment & 3D:3D Matching)

Breaking API Changes: There are NO breaking API changes in this release.

New APIs and Behavior Changes: In this release, we have added new APIs that are the new default for handling core parts of the process.  Your previous code will still work with zero modifications.  However, we encourage you to use the new approach to processing results as it requires less code and is less prone to integration errors, and this new default will be required in an upcoming release of the FaceTec SDK.

Upgrading (3D:2D ID Scan)

API Changes: In v9.2.0, 3D:2D ID Scan APIs have changed.  Please see the latest PhotoIDMatchProcessor Device SDK code as well as the latest Match3D2DIDScanProcessor code for more details.  In the Device SDK, succeed and retry have been removed and proceedToNextStep must be called with the scanResultBlob created by the FaceTec Server.  /match-3d-2d-idscan must now be called multiple times during a Photo ID Match / IDScanning process in order to process the Front ID, Back ID (if applicable), as well as the final User-Confirmed OCR Results.  The FaceTec Server outputs a new ocrResults property that contains the Scanned and User-Confirmed values.

Upgrading (All Other APIs)

There are no changes to any other APIs.

FaceTec Testing API Changes

/api/v3.1 is now live and is the new default that all Sample Apps are hooked into.

 

This new version of the Testing API has changed ONLY in the following ways:
 

  1. For /liveness-3d, /enrollment, and /match-3d-3d, a scanResultBlob is returned in order to support the latest recommended results processing convention.  All other behavior for these endpoints is the same.
  2. For /match-3d-2d-idscan, the API response contains some new properties, including a scanResultBlob, that MUST be passed into the Device SDKs in order for the Device SDKs to proceed to the correct next step.  Please read the release notes and documentation for more information on the Scan Result Blob.
  3. All other endpoints have the same behavior as calling /api/v3

FaceTec Testing APIs /v1, /v2 & /v3 Are Deprecated

/v3.1 should be used for all prototypes, MVPs, POCs, etc.  v1, v2, and v3 will be discontinued in a future release.

Strings/Text Changes

Retry Screen Text (Browser Only)

For the Browser SDK, we were missing a customization for the text value of the Retry Screen Action Button Text. A new text customization has been added for this text for parity with iOS and Android.

ID Scan Text

There are several new scenarios that occur during ID Scanning. The text shown for these scenarios is controlled by the fully-dynamic programmatic API called setIDScanResultScreenMessageOverrides

  1. Success on Front of ID and User Confirmation Screen Next— "Your 3D Face\r\nMatched Your ID”
  2. Success on Front of ID and Back ID Scan Next: "Your 3D Face\r\nMatched Your ID”
  3. Success on Back of ID and User Confirmation Screen Next: "ID Scanned Successfully”
  4. Success on Upload of Confirmed User Text: "Success!”
  5. Retry Case — ID Not Fully Visible: "Photo ID\r\nNot Fully Visible”
  6. Retry Case — OCR Results Not Legible: "ID Text Not Legible\r\nPlease Try Again”
  7. Retry Case — Face Did Not Match ID: "Face Did Not Match Highly\r\nPlease Try Again"

A working example of setting these strings is included in the sample PhotoIDMatchProcessor code.

Photo ID OCR & ID Scan System & API Changes

Developers are now required to choose which IDs your application supports.  To download already-existing ID Templates, or to create your own, please visit the ID Template Creator.

After the ID Templates have been installed in the FaceTec Server, the FaceTec SDK will automatically determine the ID Type after the User scans the ID.  The ID Type will be returned to you in the OCR Results JSON.

If the ID Type detected has a backside, the backside will be scanned.

IDs are scanned automatically, without the User needing to press a button to take the photo.  If the User is not able to scan the ID automatically, the Take Photo button will appear and will provide enhanced help for the User to capture and provide a good scan of their ID.

  1. Success and Retry APIs for IDScan have been removed.

Other API Changes:

  • RetryMode API has been removed.
  • FaceTecIDScanNextStep changes - electIDCard, SelectPassport options have been removed because this happens automatically when the ID Type is detected.
  • ID Scan Success/Unsuccess Override API has been removed, but the setIDScanResultScreenMessageOverrides  API can now be used to control an expanded set of text options that now occur in the UI.

Scan Result Blob

In v9.2.0, there is a new Scan Result Blob property on the response to 3D Liveness, 3D:3D Matching, and 3D:2D ID Scanning.

The Scan Result Blob is an encrypted, proprietary payload that is output by the FaceTec Server, and must be passed into the Device SDK after performing the above operations. The Scan Result Blob allows the Device SDK and FaceTec Server to communicate to each other without Developers parsing various flags that the FaceTec Server outputs.

For 3D Liveness and 3D:3D Matching, usage of the Scan Result Blob is optional, but configured and on by default.

For 3D:2D ID Scanning, usage of the Scan Result Blob is required and cannot be turned off.

IDScan Compatibility

IDScans from v9.2.0+ Device SDKs are fully compatible with v9.2.0+ FaceTec Server.

IDScans from v9.1.0+ Device SDKs WILL NOT succeed in v9.2.0+ FaceTec Server /match-3d-2d-idscan endpoint.  It is recommended that you fully upgrade your Device SDKs when updating to v9.2.0+ if ID Scans are a core scenario for you.  HOWEVER, there are two ways that you can continue to support v9.1.0 and earlier ID Scans:

  1. You can maintain a version of v9.1.x FaceTec Server running side by side with your v9.2.0+ FaceTec Server, and route pre-v9.2.0 Device SDK traffic to your pre-v9.2.0 Server. This is the recommended approach if full compatibility is necessary.
     
  2. In order to provide additional compatibility, the FaceTec Server has a new Core API called match3d2d_idscan_legacy_matching_only, which can be called with pre-v9.2.0 ID Scans, which can be used to get the Match Level only between a 3D FaceMap and a pre-v9.2.0 ID Scan.

3D Liveness, Enrollment & 3D Matching

FaceTec Server now outputs a Scan Result Blob object out of each of these Core API calls.  By default, the Sample Apps demonstrate how to process this scanResultBlob, by calling the proceedToNextStep function.

This is the new recommended way of processing results in your Device SDK code, rather than evaluating flags and calling succeed or retry.

succeed and retry APIs have been deprecated and will be removed in a future release.  The succeed and retry APIs allowed you to control the flow of the Device SDK code based on results that you evaluated.  While this was flexible, this would often lead to issues where succeed() could be called even if the scan was not successful, or retry() to be called when the scan was actually successful.  While not a security risk, since the answer is still obtainable in Server code that cannot be tampered with, this created a surface area for bugs and improper integrations.

After checking out the new Processor code, you will notice that there is even less code for you to write and maintain in your App, and the code is very straightforward and no conditional branching.

The cancel API remains in place in case of a network connectivity issue, but should not be used to shortcut/bypass normal Success/Retry logic.  In a future release, the SDK APIs will enforce that cancel is also only used in appropriate circumstances.

Other API Changes

  • Device SDK - ID Scan idType is no longer returned. The ID Type is now returned on the ocrResults object on the Server
  • Server Core - In v9.1.0 and earlier, if you are not uploading Audit Trail images (e.g. your App does not upload image data due to PII concerns), you were previously able to enable this scenario by keying off the livenessResult. However, in this case, success would == false since we require ALL Security Checks to pass in order for success == true. In order to better support success == true for Apps that have heightened PII concerns, you can configure Server Core to return success based solely on the Liveness Result by setting the FaceTecInitializationConfig.disableAuditTrailVerification == true. We do not recommend doing this if you are uploading Audit Trail Images, as this is an important Security Check that should be performed in the vast majority of Apps.

 


v9.1.0 Release Notes

We are pleased to announce the general availability of the FaceTec SDKs v9.1.0!

This version contains extensive User Experience improvements to further increase first-time User Success Rates. Our team has worked to polish the user interface and provide an even more consistent and intuitive experience across more than a 1,000,000 device, platform, version, and browser combinations.


Upgrading from v9.0

Breaking API Changes: There are NO breaking API changes from v9.0 to v9.1. All SDKs will compile and run after updating the core library.

Behavior Changes There ARE several important changes to be aware of that require your attention if you are upgrading from a previous version:

  1. There are several behavior changes around specific text elements and customizations.
  2. There are new text guidance elements to be aware of and customize if necessary.
  3. New Feature: Vocal Guidance — Provides configuration options that the Device to play an MP3 file with vocal instructions on important FaceTec SDK Screens. Also provides configurable vocal instructions when certain interface elements are tapped.

Dynamic Retry Screen Guidance Text

In previous versions of the FaceTec SDK, the text area below the User Image and Ideal Image on the Retry Screen were customizable. In v9.1.0, the text is still 100% customizable, but the behavior has changed, and there are additional text elements to customize.

In pre-v9.1.0, the Face Expression Issues and Lighting Issues feedback was a single text element.

In v9.1.0 and beyond, this element has changed to become 3 separate text customizations, one for Face Expression Issues, one for Lighting Issues, and one for Camera Blurriness. The FaceTec SDK now determines whether the likely cause of a User Retry was due to Face Expression, Lighting, or Camera Blurriness.

To see the new text customizations, please open the Strings file on each platform, and see the UX Customizations page for the locations of each of these text elements.


 


Text Customization Behavior Change: Single Line Customizations Only

In v9.1.0, each line of text must be customized.  Previously, for elements that span multiple lines, we would attempt to make the text fit flexibly.  In v9.1.0 and above, you must configure each line (for relevant elements that can span multiple lines) individually.  For instance, on the Get Ready Screen for iOS Native, Android Native, and Mobile Browser, you must specify your multi-line text in two separate text elements, rather than relying on automatic text overflow to a new line.

In v9.1.0, no text will overflow to new lines, and you must specify text that is very concise so that it fits on the line that you are customizing.


Browser: Desktop vs. Mobile Text Customizations

In pre-v9.1.0, the 2 non-header text elements on the Get Ready Screen were controlled with 2 separate text elements. The Sample Apps showed how to detect mobile vs. desktop, and conditionally display newlines in the subtext elements if mobile was detected in order to get proper rendering.

In v9.1.0 and beyond, we have split out these into separate customizations, and no longer require that you do your own lightweight detection of mobile vs. desktop to get the correct behavior.

Simply configure your mobile-specific, 4 lines of text for the Get Ready Screen subtext, as well as your desktop-specific 2 lines, and we will do the mobile vs. desktop detection internally and render the correct text!


Face Scan Initial Quality Checks

New in v9.1.0, Users cannot press the I'm Ready button without a face of reasonably appropriate size is shown in front of the camera.

Once the I'm Ready button is pressed, if the User environment and face position is sufficient, a quick countdown will be displayed, and the Session will proceed as in previous versions of the FaceTec SDK.

During the initial quality checks, feedback will be given to the User if their lighting, pose, or facial expression is not adequate in order to perform a Liveness Check.

Also during the initial quality checks, the Screen will be dimmed if the environment is too bright and will be brightened if more light must be cast on the Face in order to perform a good scan.

There are several new text elements to customize & localize related to this new piece of the interface. Please see the Strings files for more detailed information and examples.

The quality checks are limited to a max of 2 retries. On the 3rd try, the quality checks are disabled and will allow the 3D FaceScan to be sent to the server for processing.


Usage Logs Changes

There are several changes in v9.1.0 related to Usage Logs:

  1. Availability of HTTPS Usage Log send.
  2. New prescriptive & turnkey Usage Log send solutions for both SFTP and HTTPS modes.
  3. Configuration Wizard builds create fully configured FaceTec Standard and Custom Server (v9) packages that instantly use our best practices and code written to automatically send Usage Logs via either HTTPS or SFTP.
  4. Usage Log Server

Sending ALL Usage Logs to FaceTec is still a requirement, and will always be a requirement.

In v9.1.0, we now offer several prescriptive and turnkey log send solutions. These included methods use the new Usage Log Server to aggregate logs and send Usage Logs to FaceTec.

In v9.1.0, the Usage Log Server is optional, but configured to be ON by default.

In v9.2.0 and beyond, the Usage Log Server will be mandatory.

Please see the Strings files for more detailed information and examples.


Vocal Guidance

Vocal Guidance is a new feature in v9.1.0 that allows Developers to customize instructions that are read out loud to User in order to provide additional assistance and directives.

The SDK ships with basic English mp3s and the default mode is Minimal.  The other supported modes are None (zero sounds played ever) and Full.

Vocal Guidance can be set and customized using FaceTecVocalGuidanceCustomization object.

Currently, there are 6 different Vocal Guidance sounds, and you can provide your own sound files.  The English sounds read these directions out loud:

  • "Please press the button to start"
  • "Please frame your face in the oval"
  • "Please move closer"
  • "Uploading"
  • "Please Retry"
  • "FaceScan Successful"

Here are the specific places where the various sounds are launched:

  • Get Ready Screen
    • Minimal Mode
      • "Please Frame Your Face in the Oval" occurs when the I’m Ready Button is disabled and the User taps anywhere on the screen except Cancel and Action Button.
      • "Please press the button to start" occurs when the I’m Ready Button is enabled and the user taps anywhere on the screen except Cancel and Action Button.
    • Full Mode
      • Same behavior as Minimal Mode, and:
      • "Please Frame Your Face in the Oval" is launched when the Screen is opened.
      • "Please press the button to start" occurs if on this screen for 4.5 seconds and the I’m Ready Button has not been pressed.
  • Face Capture screen
    • Minimal Mode
      • "Please Frame Your Face in the Oval" occurs when the feedback is "Frame your face in the oval" and the User taps anywhere on the screen.
      • “Please Move Closer" occurs when the feedback is "Move Closer" or "Even Closer” and User taps anywhere on the screen.
      • "Please Frame your face in the oval" occurs 8 seconds after session starts and the oval is still small. 
      • "Please Move Closer" occurs after 1 second (AFTER feedback text pulsing) when the Oval expands to the ZoOmed phase, the User hasn't moved their face closer, and the feedback text is still "Move Closer" or "Even Closer". This only happens once.
    • Full Mode 
      • Same behavior as Minimal Mode, and:
      • "Please Frame your face in the oval" occurs when the session stays in the Unzoomed phase for more than 4.5 seconds. 
      • "Please Move Closer occurs when the Oval transitions from UnZoOmed to ZoOmed.
      • "Please Move Closer" occurs when the session is in the ZoOmed phase for more than 4.5 seconds and the user's face is not ZoOmed.
  • Uploading Screen
    • Minimal Mode
      • Nothing
    • Full Mode
      • "Uploading" occurs when Face Scanning completes and it goes to uploading screen.
      • "FaceScan Successful" occurs when the FaceScan is successful.
      • "Please Retry" occurs when the User needs to retry.
  • Retry Screen that shows side by side image
    • Minimal Mode
      • "Please press the button to start" occurs when the User taps anywhere on the screen except Cancel and Action Button. 
    • Full Mode
      •  Same behavior as Minimal Mode.


Android Minified/No-Network Build

In order to reduce the Android SDK size by an additional 200-300KB, the FaceTec Android SDK now ships with a "minified" .aar file. This .aar file is exactly the same as the non-minified .aar file, except it has had the network libraries removed from it, and is only capable of initializing in Production Mode.

The non-minified .aar can still be used to initialize in Production Mode, but for Developers wishing to save an extra 200-300KB on their App size, the minified .aar can be used.


Font Sizing

In v9.1.0, you may still customize any interface element with the font you choose, however, you the Device SDK will now set the font size based on the Device’s properties.

There are over 1,000,000 different end user device variations (models, carrier platforms, screen aspect ratio, size, pixel density). It is not possible to choose a single font size that works everywhere, fits and looks good, so the FaceTec SDK takes care of rendering optimally given your font and text string length.

For optimal layout, you are also expected to use non-monospace fonts and fonts that have "standard" size. Roboto, Arial, San Francisco, Tahoma, Verdana, Georgia, Helvetica, and similar popular fonts are all "standard" size because most conceivably strings you can create will differ in width by 5% or less.

The FaceTec SDK will log warnings in your application if:

  1. You have configured a font that is a non-standard size. For instance, Courier New, Consolas, and Syncopate are "wide" fonts and will cause layout issues. Wide or monospace fonts are not recommended and not supported, please do not use them.
  2. You have configured any text element with text that will likely cause the text to appear too small on a large percentage of devices.


More Misc. Changes

  1. Browser - Code related to detection and rendering inside of an iFrame has been overhauled in order to reduce surface area for edge case issues related to Browser support of the Fullscreen APIs. There is not any Developer action required, but if you use the FaceTec SDK within an iFrame, please be sure to verify your mainline scenarios.
  2. The Device Not Compatible Screen removed. This screen is superseded by the Camera Feed Issues Screen, which gives feedback that there is an issue with encrypting the camera feed once a session.
  3. Updated several underlying toolchains and libraries to more recent versions — the result is stability and performance wins with no compatibility changes.
  4. Several APIs related to font size have been deprecated and are now no-ops.

 


Usage Logs - Technical Specs

Usage Log Server Connectivity to FaceTec

The Usage Log Server ensures that a connection can be made to FaceTec on startup. The Usage Log Server will not start unless a valid HTTPS or SFTP connection can be made to your FaceTec Account with the credentials you have specified.

Default Mode — 1 Usage Log Server per Instance

In the default FaceTec Server packages created by the Configuration Wizard, a Usage Log Server will be spawned on each instance of the FaceTec Server. The FaceTec Server will connect to the Usage Log Server running on localhost (which will be spawned automatically as a part of starting the image).

If you wish to have a single Usage Log Server or a cluster of Usage Log Servers, you are free to do so.

Usage Log Server Summary

The Usage Log Server consists of a new standalone server program that can handle requests from FaceTec Server for the following scenarios:

  • Usage Log validation (/validate) - The Usage Log Usage Log will validate your Key when it starts up and each FaceTec Server instance will validate itself via a network request to the Usage Log Server during init. The SDK instance will fail to initialize if the usage log server cannot be reached or validation fails.
  • Logging (/log) - Usage data from the individual FaceTec Server machines will continuously be sent in batches to the Usage Log Server instance.

In addition to handling these network requests, the Usage Log Server also writes all usage log data to a local disk and periodically uploads the data to FaceTec via the new usage log upload API. Uploads occur when the current log file is rotated, which is currently configured to occur when the log file reaches 10MB or when the system clock reaches midnight; whichever happens first.

Technology Overview

The Usage Log Server is a standalone application written in Node.js. It is shipped as source so you can inspect the data that is stored and how it is uploaded. Key validation and other internals are) or needs to be shared between the Usage Log Server and the FaceTec Server (e.g. Usage Log request parsing), we use the Node Addon API to create a Node.js module from C++ code.

Security Comments

  • Usage Log Server Data Security: Data transferred between FaceTec Server instances and the Usage Log Server is not encrypted by default.
  • Usage Log Server → FaceTec Data Security: Usage log data uploaded to FaceTec's server is sent over HTTPS and, thus, encrypted.

Implementation Notes

  • FaceTec Server nodes MUST retain connectivity to the Usage Log Server at all times. Temporary connectivity issues are tolerated, but prolonged disconnection will result in the SDK instances no longer functioning.
  • Each Usage Server instance can handle connections from a maximum of 20 FaceTec Server instances.

Error Conditions

The Usage Log Server will fail upon startup in the following scenarios:

  • Key validation failure: The Keys are not valid or they have expired
  • Connectivity issues: The Usage Log Server initially attempts to contact the FaceTec servers. If this attempt does not succeed, then the server does not start.