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