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:
- FaceTec Server now outputs text OCR'd from the Photo ID.
- Photo ID OCR Template Creator allows you to Accept ANY ID Type for the languages we support.
- FaceTec Customers can create their own OCR Templates using the OCR Template Creator.
- 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.
- The ID Scan process now allows the User to confirm the information OCR'd from the ID.
- 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:
- 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.
- 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.
- 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
- Success on Front of ID and User Confirmation Screen Next— "Your 3D Face\r\nMatched Your ID”
- Success on Front of ID and Back ID Scan Next: "Your 3D Face\r\nMatched Your ID”
- Success on Back of ID and User Confirmation Screen Next: "ID Scanned Successfully”
- Success on Upload of Confirmed User Text: "Success!”
- Retry Case — ID Not Fully Visible: "Photo ID\r\nNot Fully Visible”
- Retry Case — OCR Results Not Legible: "ID Text Not Legible\r\nPlease Try Again”
- 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.
- 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:
- 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.
- 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 unexpected behaviors 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.