Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Oz Mobile SDK stands for the Software Developer’s Kit of the Oz Forensics Liveness and Face Biometric System, providing seamless integration with customers’ mobile apps for login and biometric identification.
Currently, both Android and iOS SDK work in the portrait mode.
To start using Oz Android SDK, follow the steps below.
Embed Oz Android SDK into your project as described here.
Connect SDK to API as described here. This step is optional, as this connection is required only when you need to process data on a server. If you use the on-device mode, the data is not transferred anywhere, and no connection is needed.
Capture videos using methods described here. You'll send them for analysis afterward.
Analyze media you've taken at the previous step. The process of checking liveness and face biometry is described here.
If you want to customize the look-and-feel of Oz Android SDK, please refer to this section.
Recommended Android version: 5+ (the newer the smartphone is, the faster the analyses are).
Recommended versions of components:
We do not support emulators.
Available languages: EN, ES, HY, KK, KY, TR, PT-BR.
To obtain the sample apps source code for the Oz Liveness SDK, proceed to the GitLab repository:
Follow the link below to see a list of SDK methods and properties:
Download the demo app latest build here.
Gradle
7.5.1
Kotlin
1.7.21
AGP
7.3.1
Java Target Level
1.8
JDK
17
The common way of Oz Mobile SDK to work is the server-based mode, when the Liveness and Biometry analyses are performed on a server as shown in the scheme below:
But there's also an option to perform checks without server calls or even Internet connection. This option stands for on-device analyses.
The on-device analyses are being performed faster and more secure as all data is processed directly on device, nothing is being sent anywhere. In this case, you don’t need a server at all, neither need you the API connection.
However, the API connection might be needed for some additional functions like telemetry or server-side SDK configuration.
The on-device analysis mode is useful when:
you do not collect, store or process personal data;
you need to identify a person quickly regardless of network conditions such as a distant region, inside a building, underground, etc.;
you’re on a tight budget as you can save money on the hardware part.
To launch the on-device check, set the appropriate mode
for Android or iOS SDK.
Android:
iOS:
For details, please refer to the Checking Liveness and Face Biometry sections for iOS and Android.
Add the following URL to the build.gradle
of the project:
Add this to the build.gradle
of the module (VERSION is the version you need to implement. Please refer to Changelog):
Please note: this is the default version.
Please note: the resulting file will be larger.
Also, regardless of the mode chosen, add:
You can generate the trial license here or contact us by email to get a productive license. To create the license, your applicationId
(bundle id
) is required.
To pass your license file to the SDK, call the OzLivenessSDK.init
method with a list of LicenseSources
. Use one of the following:
LicenseSource.LicenseAssetId
should contain a path to a license file called forensics.license
, which has to be located in the project's res/raw folder.
LicenseSource.LicenseFilePath
should contain a file path to the place in the device's storage where the license file is located.
In case of any license errors, the onError
function is called. Use it to handle the exception as shown above. Otherwise, the system will return information about license. To check the license data manually, use the getLicensePayload
method.
Error message | What to Do |
---|---|
License error. License at (your_URI) not found
The license file is missing. Please check its name and path to the file.
License error. Cannot parse license from (your_URI), invalid format
The license file is somehow damaged. Please email us the file.
License error. Bundle company.application.id is not in the list allowed by license (bundle.id1, bundle.id2)
The bundle (application) identifier you specified is missing in the allowed list. Please check the spelling, if it is correct, you need to get another license for your application.
License error. Current date yyyy-mm-dd hh:mm:ss is later than license expiration date yyyy-mm-dd hh:mm:ss
Your license has expired. Please contact us.
License is not initialized. Call 'OzLivenessSDK.init before using SDK
You haven't initialized the license. Call OzLivenessSDK.init
with your license data as explained above.
If you use our SDK just for capturing videos, omit this step.
To check liveness and face biometry, you need to upload media to our system and then analyze them.
To interpret the results of analyses, please refer to Types of Analyses.
Here’s an example of performing a check:
To delete media files after the checks are finished, use the clearActionVideos
method.
To add metadata to a folder, use the addFolderMeta
method.
In the params
field of the Analysis
structure, you can pass any additional parameters (key + value), for instance, to extract the best shot on the server side.
To use a media file that is captured with another SDK (not Oz Android SDK), specify the path to it in OzAbstractMedia:
If you want to add your media to the existing folder, use the setFolderId
method:
To connect SDK to Oz API, specify the API URL and access token as shown below.
Please note: in your host application, it is recommended that you set the API address on the screen that precedes the liveness check. Setting the API URL initiates a service call to the API, which may cause excessive server load when being done at the application initialization or startup.
Alternatively, you can use the login and password provided by your Oz Forensics account manager:
Although, the preferred option is authentication via access token – for security reasons.
For telemetry, set the separate connection as shown below:
Clearing authorization:
Check for the presence of the saved Oz API access token:
LogOut:
To start recording, use thestartActivityForResult
method:
actions
– a list of user actions while recording video.
For Fragment, use the code below. LivenessFragment
is the Fragment representation of the Liveness screen UI.
To obtain the captured video, use theonActivityResult
method:
sdkMediaResult
– an object with video capturing results for interactions with Oz API (a list of the OzAbstractMedia objects),
sdkErrorString
– description of errors, if any.
If you use our SDK just for capturing videos, omit the Checking Liveness and Face Biometry step.
If a user closes the capturing screen manually, resultCode
receives the Activity.RESULT_CANCELED
value.
Code example:
Please note: this feature has been implemented in 8.1.0.
To add or update the language pack for Oz Android SDK, please follow these instructions:
The localization record consists of the localization key and its string value, e.g., <string name="about">"About"</string>
.
Create the file called strings.xml.
Copy the strings from the attached file to your freshly created file.
Redefine the strings you need in the appropriate localization records.
A list of keys for Android:
The keys action_*_go
refer to the appropriate gestures. Others refer to the hints for any gesture, info messages, or errors.
When new keys appear with new versions, if no translation is provided in your file, the new strings are shown in English.
Go to the folder for the locale needed, or create a new folder. Proceed to for the details.
To customize the Oz Liveness interface, use UIcustomization
as shown below. For the description of customization parameters, please refer to .
To start using Oz iOS SDK, follow the steps below.
Embed Oz iOS SDK into your project as described here.
Connect SDK to API as described here. This step is optional, as this connection is required only when you need to process data on a server. If you use the on-device mode, the data is not transferred anywhere, and no connection is needed.
Capture videos by creating the controller as described here. You'll send them for analysis afterwards.
Upload and analyze media you've taken at the previous step. The process of checking liveness and face biometry is described here.
If you want to customize the look-and-feel of Oz iOS SDK, please refer to this section.
Recommended iOS version: 12 and higher.
Recommended Xcode version: 12.5 and higher.
Available languages: EN, ES, HY, KK, KY, TR, PT-BR.
A sample app source code using the Oz Liveness SDK is located in the GitLab repository:
Follow the link below to see a list of SDK methods and properties:
Download the demo app latest build here.
Android SDK changes
Added a description for the error that occurs when providing an empty string as an ID in the setFolderID
method.
Fixed a bug causing an endless spinner to appear if the user switches to another application during the Liveness check.
Fixed some smartphone model specific-bugs.
Upgraded the on-device Liveness model.
Security updates.
The length of the Selfie gesture is now configurable (affects the video file size).
You can set your own logo instead of Oz logo if your license allows it.
Removed the pause after the Scan gesture.
If the recorded video is larger than 10 MB, it gets compressed.
Security and logging updates.
Changed the master license validation algorithm.
Downgraded the required compileSdkVersion
from 34 to 33.
Security updates.
Updated the on-device Liveness model.
Fixed some bugs.
Internal licensing improvements.
Internal SDK improvements.
Bug fixes.
Implemented the possibility of using a master license that works with any bundle_id
.
Video compression failure on some phone models is now fixed.
Bug fixes.
The Analysis
structure now contains the sizeReductionStrategy
field. This field defines what type of media is being sent to the server in case of the hybrid analysis once the on-device analysis is finished successfully.
The messages for the errors that are retrieved from API are now detailed.
If multiple analyses are applied to the folder simultaneously, the system sends them as a group. It means that the “worst” of the results will be taken as resolution, not the latest. Please refer to this article for details.
For the Liveness analysis, the system now treats the highest score as a quantitative result. The Liveness analysis output is described here.
Updated the Liveness on-device model.
Added the Portuguese (Brazilian) locale.
You can now add a custom or update an existing language pack. The instructions can be found here.
If a media hasn't been uploaded correctly, the system repeats the upload.
Created a new method to retrieve the telemetry (logging) identifier: getEventSessionId
.
The login
and auth
methods are now deprecated. Use the setAPIConnection
method instead.
OzConfig.baseURL
and OzConfig.permanentAccessToken
are now deprecated.
If a user closes the screen during video capture, the appropriate error is now being handled by SDK.
Fixed some bugs and improved the SDK work.
Fixed errors.
The SDK now works properly with baseURL
set to null
.
The dependencies' versions have been brought into line with Kotlin version.
Added the new analysis mode – hybrid (Liveness only). If the score received from an on-device analysis is too high, the system initiates a server-based analysis as an additional check.
Kotlin version requirements lowered to 1.7.21.
Improved the on-device models.
For some phone models, fixed the fatal device error.
The hint text width can now exceed the frame width (when using the main camera).
Photos taken during the One Shot analysis are now being sent to the server in the original size.
Removed the OzAnalysisResult
class. The onSuccess
method ofAnalysisRequest.run
now uses the RequestResult
structure instead of List<OzAnalysisResult>.
All exceptions are moved to the com.ozforensics.liveness.sdk.core.exceptions
package (See changes below).
Classes related to AnalysisRequest
are moved to the com.ozforensics.liveness.sdk.analysis
package (See changes below).
The methods below are no longer supported:
Restructured the settings screen.
Added the center hint background customization.
Added new face frame forms (Circle, Square).
Added the antiscam widget and its customization. This feature allows you to alert your customers that the video recording is being conducted, for instance, for loan application purposes. The purpose of this is to safeguard against scammers who may attempt to deceive an individual into approving a fraudulent transaction.
The OzLivenessSDK::init
method no longer crashes if there is a StatusListener
parameter passed.
Changed the scan gesture animation.
Please note: for this version, we updated Kotlin to 1.8.20.
Improved the SDK algorithms.
Updated the model for the on-device analyses.
Fixed the animation for sunglasses/mask.
The oval size for Liveness is now smaller.
Fixed the error with the server-based analyses while using permanentAccessToken
for authorization.
Added customization for the hint animation.
You can now hide the status bar and system buttons (works with 7.0.0 and higher).
OzLivenessSDK.init
now requires context
as the first parameter.
OzAnalysisResult
now shows the server-based analyses' scores properly.
Fixed initialization issues, displaying of wrong customization settings, authorization failures on Android <7.1.1.
Fixed crashes for Android <6.
Fixed oval positioning for some phone models.
Internal fixes and improvements.
Updated security.
Implemented some internal improvements.
The addMedia
method is now deprecated, please use uploadMedia
for uploading.
Changed the way of sharing dependencies. Due to security issues, now we share two types of libraries as shown below: sdk
is a server analysis only, full
provides both server and on-device analyses:
UICustomization
has been implemented instead of OzCustomization
.
Implemented a range of UI customization options and switched to the new design. To restore the previous settings, please refer to this article.
Added the Spanish locale.
Fixed the bug with freezes that had appeared on some phone models.
SDK now captures videos in 720p.
Synchronized the names of the analysis modes with iOS: SERVER_BASED and ON_DEVICE.
Fixed the bug with displaying of localization settings.
Now you can use Fragment as Liveness screen.
Added a new field to the Analysis
structure. The params
field is for any additional parameters, for instance, if you need to set extracting the best shot on server to true. The best shot algorithm chooses the most high-quality frame from a video.
The Zoom in and Zoom out gestures are no longer supported.
Updated the biometry model.
Added a new simplified API – AnalysisRequest. With it, it’s easier to create a request for the media and analysis you need.
Published the on-device module for on-device liveness and biometry analyses. To add this module to your project, use:
To launch these analyses, use runOnDeviceBiometryAnalysis
and runOnDeviceLivenessAnalysis
methods from the OzLivenessSDK
class:
Liveness goes smoother.
Fixed freezes on Xiaomi devices.
Optimized image converting.
New metadata parameter for OzLivenessSDK.uploadMedia
and new OzLivenessSDK.uploadMediaAndAnalyze
method to pass this parameter to folders.
Added functions for SDK initialization with LicenseSources: LicenseSource.LicenseAssetId
and LicenseSource.LicenseFilePath
. Use the OzLivenessSDK.init
method to start initialization.
Now you can get the license info upon initialization val licensePayload = OzLivenessSDK.getLicensePayload().
Added the Kyrgyz locale.
Added local analysis functions.
You can now configure the face frame.
Fixed version number at the Liveness screen.
Added the main camera support.
Added configuration from license support.
Added the OneShot gesture.
Added new states for OzAnalysisResult.Resolution.
Added the uploadMediaAndAnalyze
method to load a bunch of media to the server at once and send them to analysis immediately.
OzMedia
is renamed to OzAbstractMedia
and got subclasses for images and videos.
Fixed camera bugs for some devices.
Access token updates automatically.
Renamed accessToken
to permanentAccessToken
.
Added R8 rules.
Configuration became easier: config settings are mutable.
Fixed the oval frame.
Removed the unusable parameters from AnalyseRequest
.
Removed default attempt limits.
To customize the configuration options, the config property is added instead of baseURL, accessToken, etc. Use OzConfig.Builder
for initialization.
Added license support. Licences should be installed as raw resources. To pass them to OzConfig
, use setLicenseResourceId
.
Replaced the context-dependent methods with analogs.
Improved the image analysis.
Removed unusable dependencies
Fixed logging
Rename this file to forensics.license and put it into the project. In this case, you don't need to set the path to the license.
During the runtime: when initializing SDK, use the following method.
or
LicenseSource
a source of license, and LicenseData
is the information about your license. Please note: this method checks whether you have an active license or not and if yes, this license won't be replaced with a new one. To force the license replacement, use the setLicense
method.
In case of any license errors, the system will use your error handling code as shown above. Otherwise, the system will return information about license. To check the license data manually, use OZSDK.licenseData
.
A singleton for Oz SDK.
Deletes all action videos from file system.
Parameters
-
Returns
-
Creates an intent to start the Liveness activity.
Returns
-
Utility function to get the SDK error from OnActivityResult's intent.
Returns
Retrieves the SDK license payload.
Parameters
-
Returns
Utility function to get SDK results from OnActivityResult's intent.
Returns
A list of OzAbstractMedia objects.
Initializes SDK with license sources.
Returns
-
Enables logging using the Oz Liveness SDK logging mechanism.
Returns
-
Connection to API.
Connection to the telemetry server.
Deletes the saved token.
Parameters
-
Returns
-
Retrieves the telemetry session ID.
Parameters
-
Returns
The telemetry session ID (String parameter).
Retrieves the SDK version.
Parameters
-
Returns
The SDK version (String parameter).
A class for performing checks.
The analysis launching method.
A builder class for AnalysisRequest.
Creates the AnalysisRequest instance.
Parameters
-
Returns
Adds an analysis to your request.
Returns
Error if any.
Adds a list of analyses to your request. Allows executing several analyses for the same folder on the server side.
Returns
Error if any.
Adds metadata to a folder you create (for the server-based analyses only). You can add a pair key-value as additional information to the folder with the analysis result on the server side.
Returns
Error if any.
Uploads one or more media to a folder.
Returns
Error if any.
For the previously created folder, sets a folderId. The folder should exist on the server side. Otherwise, a new folder will be created.
Returns
Error if any.
Configuration for OzLivenessSDK (use OzLivenessSDK.config).
Sets the length of the Selfie gesture (in milliseconds).
Returns
Error if any.
The possibility to enable additional debug info by clicking on version text.
The number of attempts before SDK returns error.
Settings for repeated media upload.
Timeout for face alignment (measured in milliseconds).
Interface implementation to retrieve error by Liveness detection.
Locale to display string resources.
Logging settings.
Uses the main (rear) camera instead of the front camera for liveness detection.
Customization for OzLivenessSDK (use OzLivenessSDK.config.customization
).
Hides the status bar and the three buttons at the bottom. The default value is True
.
A set of customization parameters for the toolbar.
A set of customization parameters for the center hint that guides a user through the process of taking an image of themselves.
A set of customization parameters for the hint animation.
A set of customization parameters for the frame around the user face.
A set of customization parameters for the background outside the frame.
A set of customization parameters for the SDK version text.
A set of customization parameters for the antiscam message that warns user about their actions being recorded.
Logo customization parameters. Custom logo should be allowed by license.
Contains the action from the captured video.
Contains the extended info about licensing conditions.
A class for the captured media that can be:
A document photo.
A set of shots in an archive.
A Liveness video.
Contains an action from the captured video.
A class for license that can be:
Contains the license ID.
Contains the path to a license.
A class for analysis status that can be:
This status means the analysis is launched.
This status means the media is being uploaded.
The type of the analysis.
Currently, the DOCUMENTS
analysis can't be performed in the on-device mode.
The mode of the analysis.
Contains information on what media to analyze and what analyses to apply.
The general status for all analyses applied to the folder created.
Holder for attempts counts before SDK returns error.
Contains logging settings.
A class for color that can be (depending on the value received):
Frame shape settings.
Exception class for AnalysisRequest.
Structure that describes media used in AnalysisRequest.
Structure that describes the analysis result for the single media.
Consolidated result for all analyses performed.
Result of the analysis for all media it was applied to.
Defines the authentication method.
Authentication via token.
Authentication via credentials.
Defines the settings for the repeated media upload.
Defines what type of media is being sent to the server in case of the hybrid analysis once the on-device analysis is finished successfully. By default, the system uploads the compressed video.
Master license is the offline license that allows using Mobile SDKs with any bundle_id
, unlike the regular licenses. To get a master license, create a pair of keys as shown below. Email us the public key, and we will email you the master license shortly after that.
Your application needs to sign its bundle_id
with the private key, and the Mobile SDK checks the signature using the public key from the master license. Master licenses are time-limited.
This section describes the process of creating your private and public keys.
To create a private key, run the commands below one by one.
You will get these files:
privateKey.der is a private .der key;
privateKey.txt is privateKey.der encoded by base64. This key containing will be used as the host app bundle_id signature.
File examples:
To create a public key, run this command.
You will get the public key file: publicKey.pub. To get a license, please email us this file. We will email you the license.
File example:
SDK initialization:
License setting:
Prior to the SDK initializing, create a base64-encoded signature for the host app bundle_id
using the private key.
Signature creation example:
Pass the signature as the masterLicenseSignature
parameter either during the SDK initialization or license setting.
If the signature is invalid, the initialization continues as usual: the SDK checks the list of bundle_id
included into the license like it does it by default without a master license.
You can generate the trial license or contact us by to get a productive license. To create the license, your bundle id
is required. After you get a license file, there are two ways to add the license to your project.
Error message | What to Do |
---|
The – String.
The license payload () – the object that contains the extended info about licensing conditions.
The class instance.
Contains the locale code according to .
The OpenSSL command specification:
Removed method
Replacement
OzLivenessSDK.uploadMediaAndAnalyze
AnalysisRequest.run
OzLivenessSDK.uploadMedia
AnalysisRequest.Builder.uploadMedia
OzLivenessSDK.runOnDeviceBiometryAnalysis
AnalysisRequest.run
OzLivenessSDK.runOnDeviceLivenessAnalysis
AnalysisRequest.run
AnalysisRequest.build(): AnalysisRequest
-
AnalysisRequest.Builder.addMedia
AnalysisRequest.Builder.uploadMedia
License error. License at (your_URI) not found | The license file is missing. Please check its name and path to the file. |
License error. Cannot parse license from (your_URI), invalid format | The license file is somehow damaged. Please email us the file. |
License error. Bundle company.application.id is not in the list allowed by license (bundle.id1, bundle.id2) | The bundle (application) identifier you specified is missing in the allowed list. Please check the spelling, if it is correct, you need to get another license for your application. |
License error. Current date yyyy-mm-dd hh:mm:ss is later than license expiration date yyyy-mm-dd hh:mm:ss | Your license has expired. Please contact us. |
License is not initialized. | You haven't initialized the license. Please add the license to your project as described above. |
Parameter | Type | Description |
data | Intent | The object to test |
Parameter | Type | Description |
data | Intent | The object to test |
Parameter | Type | Description |
tag | String | Message tag |
log | String | Message log |
Parameter | Type | Description |
key | String | Key for metadata. |
value | String | Value for metadata. |
Parameter | Type | Description |
folderID | String | A folder identifier. |
Parameter | Type | Description |
selfieLength | Int | The length of the Selfie gesture (in milliseconds). Should be within 500-5000 ms, the default length is 700 |
Parameter | Type | Description |
allowDebugVisualization | Boolean | Enables or disables the debug info. |
Parameter | Type | Description |
faceAlignmentTimeout | Long | A timeout value |
Parameter | Type | Description |
livenessErrorCallback | ErrorHandler | A callback value |
Parameter | Type | Description |
useMainCamera | Boolean | Switches cameras |
Parameter | Type | Description |
image | Bitmap (@DrawableRes) | Logo image |
size | Size | Logo size (in dp) |
Case | Description |
OneShot | The best shot from the video taken |
Blank | A selfie with face alignment check |
Scan | Scan |
HeadRight | Head turned right |
HeadLeft | Head turned left |
HeadDown | Head tilted downwards |
HeadUp | Head lifted up |
EyeBlink | Blink |
Smile | Smile |
Parameter | Type | Description |
expires | Float | The expiration interval |
features | Features | License features |
appIDS | [String] | An array of bundle IDs |
Case | Description |
Blank | A video with no gesture |
PhotoSelfie | A selfie photo |
VideoSelfieOneShot | A video with the best shot taken |
VideoSelfieScan | A video with the scanning gesture |
VideoSelfieEyes | A video with the blink gesture |
VideoSelfieSmile | A video with the smile gesture |
VideoSelfieHigh | A video with the lifting head up gesture |
VideoSelfieDown | A video with the tilting head downwards gesture |
VideoSelfieRight | A video with the turning head right gesture |
VideoSelfieLeft | A video with the turning head left gesture |
PhotoIdPortrait | A photo from a document |
PhotoIdBack | A photo of the back side of the document |
PhotoIdFront | A photo of the front side of the document |
Parameter | Type | Description |
id | Int | License ID |
Parameter | Type | Description |
path | String | An absolute path to a license |
Case | Description |
BIOMETRY | The algorithm that allows comparing several media and check if the people on them are the same person or not |
QUALITY | The algorithm that aims to check whether a person in a video is a real human acting in good faith, not a fake of any kind. |
DOCUMENTS | The analysis that aims to recognize the document and check if its fields are correct according to its type. |
Case | Description |
ON_DEVICE | The on-device analysis with no server needed |
SERVER_BASED | The server-based analysis |
HYBRID | The hybrid analysis for Liveness: if the score received from an on-device analysis is too high, the system initiates a server-based analysis as an additional check. |
Case | Description |
FAILED | One or more analyses failed due to some error and couldn't get finished |
DECLINED | The check failed (e.g., faces don't match or some spoofing attack detected) |
SUCCESS | Everything went fine, the check succeeded (e.g., faces match or liveness confirmed) |
OPERATOR_REQUIRED | The result should be additionally checked by a human operator |
Parameter | Type | Description |
singleCount | Int | Attempts on a single action/gesture |
commonCount | Int | Total number of attempts on all actions/gestures if you use a sequence of them |
Case | Description |
EN | English |
HY | Armenian |
KK | Kazakh |
KY | Kyrgyz |
TR | Turkish |
ES | Spanish |
PT-BR | Portuguese (Brazilian) |
Parameter | Type | Description |
allowDefaultLogging | Boolean | Allows logging to LogCat |
allowFileLogging | Boolean | Allows logging to an internal file |
journalObserver | StatusListener | An event listener to receive journal events on the application side |
Parameter | Type | Description |
resId | Int | Link to the color in the Android resource system |
Parameter | Type | Description |
hex | String | Color hex (e.g., #FFFFFF) |
Parameter | Type | Description |
color | Int | The Int value of a color in Android |
Case | Description |
Oval | Oval frame |
Rectangle | Rectangular frame |
Circle | Circular frame |
Square | Square frame |
Parameter | Type | Description |
apiErrorCode | Int | Error code |
message | String | Error message |
Parameter | Type | Description |
host | String | API address |
token | String | Access token |
Parameter | Type | Description |
host | String | API address |
username | String | User name |
password | String | Password |
Parameter | Type | Description |
attemptsCount | Int | Number of attempts for media upload |
attemptsTimeout | Int | Timeout between attempts |
Case | Description |
UPLOAD_ORIGINAL | The original video |
UPLOAD_COMPRESSED | The compressed video |
UPLOAD_BEST_SHOT | The best shot taken from the video |
UPLOAD_NOTHING | Nothing is sent (note that no folder will be created) |
To install OZLivenessSDK, use the CocoaPods dependency manager. To integrate OZLivenessSDK into an Xcode project, add the following code to Podfile:
Version is optional as, by default, the newest version is integrated. However, if necessary, you can find the older version number in Changelog.
Since 8.1.0, you can also use a simpler code:
By default, the full version is being installed. It contains both server-based and on-device analysis modes. To install the server-based version only, use the following code:
For 8.1.0 and higher:
You can also add the necessary frameworks to your project manually. Download the SDK files from here:
OZLivenessSDK.xcframework,
OZLivenessSDKOnDeviceResources.bundle,
OZLivenessSDKResources.bundle.
The TensorFlow framework can be found here.
To connect SDK to Oz API, specify the API URL and access token as shown below.
Please note: in your host application, it is recommended that you set the API address on the screen that precedes the liveness check. Setting the API URL initiates a service call to the API, which may cause excessive server load when being done at the application initialization or startup.
Alternatively, you can use the login and password provided by your Oz Forensics account manager:
For telemetry, set the separate connection as shown below:
If you use our SDK just for capturing videos, omit this step.
To check liveness and face biometry, you need to upload media to our system and then analyze them.
To interpret the results of analyses, please refer to Types of Analyses.
Below, you'll see the example of performing a check and its description.
To delete media files after the checks are finished, use the cleanTempDirectory
method.
To add metadata to a folder, use AnalysisRequest.addFolderMeta
.
In the params
field of the Analysis
structure, you can pass any additional parameters (key + value), for instance, to extract the best shot on the server side.
To use a media file that is captured with another SDK (not Oz iOS SDK), specify the path to it in the OzMedia structure (the bestShotURL
property):
If you want to add your media to the existing folder, use the addFolderId
method:
Parameter | Type | Description |
actions | A list of possible actions |
Parameter | Type | Description |
context | Context | The Context class |
licenseSources | A list of license references |
statusListener | StatusListener | Optional listener to check the license load result |
Parameter | Type | Description |
connection | Connection type |
statusListener | StatusListener<String?> | Listener |
Parameter | Type | Description |
connection | Connection type |
statusListener | StatusListener<String?> | Listener |
Parameter | Type | Description |
onStatusChange | A callback function as follows: | The function is executed when the status of the AnalysisRequest changes. |
onError | A callback function as follows:
| The function is executed in case of errors. |
onSuccess | A callback function as follows:
| The function is executed when all the analyses are completed. |
Parameter | Type | Description |
analysis | A structure for analysis |
Parameter | Type | Description |
analysis | A list of Analysis structures |
Parameter | Type | Description |
mediaList | An OzAbstractMedia object or a list of objects. |
Parameter | Type | Description |
attemptsSettings | Sets the number of attempts |
Parameter | Type | Description |
uploadMediaSettings | Sets the number of attempts and timeout between them |
Parameter | Type | Description |
localizationCode | A locale code |
Parameter | Type | Description |
logging | Logging settings |
Parameter | Type | Description |
closeIconRes | Int (@DrawableRes) | An image for the close button |
closeIconTint | Close button color |
titleTextFont | Int (@FontRes) | Toolbar title text font |
titleTextFontStyle | Int (values from android.graphics.Typeface properties, e.g., Typeface.BOLD) | Toolbar title text font style |
titleTextSize | Int | Toolbar title text size (in sp, 12-18) |
titleTextAlpha | Int | Toolbar title text opacity (in %, 0-100) |
titleTextColor | Toolbar title text color |
backgroundColor | Toolbar background color |
backgroundAlpha | Int | Toolbar background opacity (in %, 0-100) |
isTitleCentered | Boolean | Defines whether the text on the toolbar is centered or not |
title | String | Text on the toolbar |
Parameter | Type | Description |
textFont | String | Center hint text font |
textStyle | Int (values from android.graphics.Typeface properties, e.g.,Typeface.BOLD) | Center hint text style |
textSize | Int | Center hint text size (in sp, 12-34) |
textColor | Center hint text color |
textAlpha | Int | Center hint text opacity (in %, 0-100) |
verticalPosition | Int | Center hint vertical position from the screen bottom (in %, 0-100) |
backgroundColor | Center hint background color |
backgroundOpacity | Int | Center hint background opacity |
backgroundCornerRadius | Int | Center hint background frame corner radius (in dp, 0-20) |
Parameter | Type | Description |
hintGradientColor | Gradient color |
hintGradientOpacity | Int | Gradient opacity |
animationIconSize | Int | A side size of the animation icon square |
hideAnimation | Boolean | A switcher for hint animation, if |
Parameter | Type | Description |
geometryType | The frame type: oval, rectangle, circle, square |
cornerRadius | Int | Rectangle corner radius (in dp, 0-20) |
strokeDefaultColor | Frame color when a face is not aligned properly |
strokeFaceInFrameColor | Frame color when a face is aligned properly |
strokeAlpha | Int | Frame opacity (in %, 0-100) |
strokeWidth | Int | Frame stroke width (in dp, 0-20) |
strokePadding | Int | A padding from the stroke to the face alignment area (in dp, 0-10) |
Parameter | Type | Description |
backgroundColor | Background color |
backgroundAlpha | Int | Background opacity (in %, 0-100) |
Parameter | Type | Description |
textFont | Int (@FontRes) | SDK version text font |
textSize | Int | SDK version text size (in sp, 12-16) |
textColor | SDK version text color |
textAlpha | Int | SDK version text opacity (in %, 20-100) |
Parameter | Type | Description |
textMessage | String | Antiscam message text |
textFont | String | Antiscam message text font |
textSize | Int | Antiscam message text size (in px, 12-18) |
textColor | Antiscam message text color |
textAlpha | Int | Antiscam message text opacity (in %, 0-100) |
backgroundColor | Antiscam message background color |
backgroundOpacity | Int | Antiscam message background opacity |
cornerRadius | Int | Background frame corner radius (in px, 0-20) |
flashColor | Color of the flashing indicator close to the antiscam message |
Parameter | Type | Description |
tag | A tag for a document photo. |
photoPath | String | An absolute path to a photo. |
additionalTags (optional) | String | Additional tags if needed (including those not from the OzMediaTag enum). |
Parameter | Type | Description |
tag | A tag for a shot set |
archivePath | String | A path to an archive |
additionalTags (optional) | String | Additional tags if needed (including those not from the OzMediaTag enum) |
Parameter | Type | Description |
tag | A tag for a video |
videoPath | String | A path to a video |
bestShotPath (optional) | String | URL of the best shot in PNG |
preferredMediaPath (optional) | String | URL of the API media container |
additionalTags (optional) | String | Additional tags if needed (including those not from the OzMediaTag enum) |
Parameter | Type | Description |
analysis | Contains information on what media to analyze and what analyses to apply. |
Parameter | Type | Description |
media | The object that is being uploaded at the moment |
index | Int | Number of this object in a list |
from | Int | Objects quantity |
percentage | Int | Completion percentage |
Parameter | Type | Description |
type | Type | The type of the analysis |
mode | Mode | The mode of the analysis |
mediaList | An array of the OzAbstractMedia objects |
params (optional) | Map<String, Any> | Additional parameters |
sizeReductionStrategy | Defines what type of media is being sent to the server in case of the hybrid analysis once the on-device analysis is finished successfully |
Parameter | Type | Description |
mediaId | String | Media identifier |
mediaType | String | Type of the media |
originalName | String | Original media name |
ozMedia | Media object |
tags | List<String> | Tags for media |
Parameter | Type | Description |
confidenceScore | Float | Resulting score |
isOnDevice | Boolean | Mode of the analysis |
resolution | Consolidated analysis result |
sourceMedia | Source media |
type | Type of the analysis |
Parameter | Type | Description |
analysisResults | Analysis result |
folderId | String | Folder identifier |
resolution | Consolidated analysis result |
Parameter | Type | Description |
resolution | Consolidated analysis result |
type | Type of the analysis |
mode | Resulting score |
resultMedia | A list of results of the analyses for single media |
confidenceScore | Float | Resulting score |
analysisId | String | Analysis identifier |
params | @RawValue Map<String, Any> | Additional folder parameters |
error | Error if any |
serverRawResponse | String | Response from backend |
Error Code | Error Message | Description |
ERROR = 3 | Error. | An unknown error has happened |
ATTEMPTS_EXHAUSTED_ERROR = 4 | Error. Attempts exhausted for liveness action. |
VIDEO_RECORD_ERROR = 5 | Error by video record. | An error happened during video recording |
NO_ACTIONS_ERROR = 6 | Error. OzLivenessSDK started without actions. |
FORCE_CLOSED = 7 | Error. Liveness activity is force closed from client application. | A user closed the Liveness screen during video recording |
DEVICE_HAS_NO_FRONT_CAMERA = 8 | Error. Device has not front camera. | No front camera found |
DEVICE_HAS_NO_MAIN_CAMERA = 9 | Error. Device has not main camera. | No rear camera found |
DEVICE_CAMERA_CONFIGURATION_NOT_SUPPORTED = 10 | Error. Device camera configuration is not supported. | Oz Liveness doesn't support the camera configuration of the device |
FACE_ALIGNMENT_TIMEOUT = 12 | Error. Face alignment timeout in OzLivenessSDK.config.faceAlignmentTimeout milliseconds |
ERROR = 13 | The check was interrupted by user | User has closed the screen during the Liveness check. |
Please note: this feature has been implemented in 8.1.0.
To add or update the language pack for Oz iOS SDK, use the set(languageBundle: Bundle)
method. It shows the SDK that you are going to use the non-standard bundle. In OzLocalizationCode
, use the custom language (optional).
The localization record consists of the localization key and its string value, e.g., "about" = "About"
.
If you don’t set the custom language and bundle, the SDK uses the pre-installed languages only.
If the custom bundle is set (and language is not), it has a priority when checking translations, i.e, SDK checks for the localization record in the custom bundle localization file. If the key is not found in the custom bundle, the standard bundle text for this key is used.
If both custom bundle and language are set, SDK retrieves all the translations from the custom bundle localization file.
A list of keys for iOS:
The keys Action.*.Task
refer to the appropriate gestures. Others refer to the hints for any gesture, info messages, or errors.
When new keys appear with new versions, if no translation is provided by your custom bundle localization file, you’ll see the default (English) text.
If you want to get back to the previous (up to 6.4.2) versions' design, reset the customization settings of the capture screen and apply the parameters that are listed below.
Please note: the customization methods should be called before the video capturing ones.
[]
onStatusChange(status: AnalysisRequest.
) { handleStatus() }
onSuccess(result:
) {
[]
[]
[]
List<>
List<>
The number of action is exceeded
No found in a video
Time limit for the is exceeded
To customize the Oz Liveness interface, use OZCustomization
as shown below. For the description of customization parameters, please refer to .
In this section, we explain how to use Oz Flutter SDK for iOS and Android.
Before you start, it is recommended that you install:
Flutter 3.0.0 or higher;
Android SDK 21 or higher;
dart 2.18.6 or higher;
iOS platform 13 or higher;
Xcode.
Please find the Flutter sample here.
iOS SDK changes
The messages displayed by the SDK after uploading media have been synchronized with Android.
The bug causing analysis delays that might have occurred for the One Shot gesture has been fixed.
The length of the Selfie gesture is now configurable (affects the video file size).
You can set your own logo instead of Oz logo if your license allows it.
Removed the pause after the Scan gesture.
The code in Readme.md is now up-to-date.
Security and logging updates.
Security updates.
Changed the default behavior in case a localization key is missing: now the English string value is displayed instead of a key.
Fixed some bugs.
Internal licensing improvements.
Implemented the possibility of using a master license that works with any bundle_id
.
Fixed the bug with background color flashing.
Bug fixes.
The Analysis
structure now contains the sizeReductionStrategy
field. This field defines what type of media is being sent to the server in case of the hybrid analysis once the on-device analysis is finished successfully.
The messages for the errors that are retrieved from API are now detailed.
The toFrameGradientColor
option in hintAnimationCustomization
is now deprecated, please use the hintGradientColor
option instead.
Got back the iOS 11 support.
If multiple analyses are applied to the folder simultaneously, the system sends them as a group. It means that the “worst” of the results will be taken as resolution, not the latest. Please refer to this article for details.
For the Liveness analysis, the system now treats the highest score as a quantitative result. The Liveness analysis output is described here.
Updated the Liveness on-device model.
Added the Portuguese (Brazilian) locale.
You can now add a custom or update an existing language pack. The instructions can be found here.
If a media hasn't been uploaded correctly, the system now repeats the upload.
Added a new method to retrieve the telemetry (logging) identifier: getEventSessionId
.
The setPermanentAccessToken
, configure
and login
methods are now deprecated. Please use the setApiConnection
method instead.
The setLicense(from path:String)
method is now deprecated. Please use the setLicense(licenseSource: LicenseSource)
method instead.
Fixed some bugs and improved the SDK work.
Fixed some bugs and improved the SDK algorithms.
Added the new analysis mode – hybrid (Liveness only). If the score received from an on-device analysis is too high, the system initiates a server-based analysis as an additional check.
Improved the on-device models.
Updated the run method.
Added new structures: RequestStatus
(analysis state), ResultMedia
(analysis result for a single media) and RequestResult
(consolidated analysis result for all media).
The updated AnalysisResult
structure should be now used instead of OzAnalysisResult
.
For the OZMedia
object, you can now specify additional tags that are not included into our tags list.
The Selfie video length is now about 0.7 sec, the file size and upload time are reduced.
The hint text width can now exceed the frame width (when using the main camera).
The methods below are no longer supported:
Added the center hint background customization.
Added new face frame forms (Circle, Square).
Added the antiscam widget and its customization. This feature allows you to alert your customers that the video recording is being conducted, for instance, for loan application purposes. The purpose of this is to safeguard against scammers who may attempt to deceive an individual into approving a fraudulent transaction.
Synchronized the default customization values with Android.
Added the Spanish locale.
iOS 11 is no longer supported, the minimal required version is 12.
Fixed the issue with the server-based One shot analysis.
Improved the SDK algorithms.
Fixed error handling when uploading a file to API. From this version, an error will be raised to a host application in case of an error during file upload.
Improved the on-device Liveness.
Fixed the animation for sunglasses/mask.
Fixed the bug with the .document
analysis.
Updated the descriptions of customization methods and structures.
Updated the TensorFlow version to 2.11.
Fixed several bugs, including the Biometry check failures on some phone models.
Added customization for the hint animation.
Integrated a new model.
Added the uploadMedia
method to AnalysisRequest
. The addMedia
method is now deprecated.
Fixed the combo analysis error.
Added a button to reset the SDK theme and language settings.
Fixed some bugs and localization issues.
Extended the network request timeout to 90 sec.
Added a setting for the animation icon size.
Implemented a range of UI customization options and switched to the new design. To restore the previous settings, please refer to this article.
The run
method now works similar to the one in Android SDK and returns an array of analysis' results.
Synchronized the version numbers with Android SDK.
Added a new field to the Analysis
structure. The params
field is for any additional parameters, for instance, if you need to set extracting the best shot on server to true. The best shot algorithm chooses the most high-quality frame from a video.
Fixed some localization issues.
Changed the Combo gesture.
Now you can launch the Liveness check to analyze images taken with another SDK.
The Zoom in and Zoom out gestures are no longer supported.
Added a new simplified analysis structure – AnalysisRequest
.
Added methods of on-device analysis: runOnDeviceLivenessAnalysis
and runOnDeviceBiometryAnalysis
.
You can choose the installation version. Standard installation gives access to full functionality. The core
version (OzLivenessSDK/Core
) installs SDK without the on-device functionality.
Added a method to upload data to server and start analyzing it immediately: uploadAndAnalyse
.
Improved the licensing process, now you can add a license when initializing SDK: OZSDK(licenseSources: [LicenseSource], completion: @escaping ((LicenseData?, LicenseError?) -> Void))
, where LicenseSource
is a path to physical location of your license, LicenseData
contains the license information.
Added the setLicense
method to force license adding.
Added the Turkish locale
Added the Kyrgyz locale
Added Completion Handler for analysis results.
Added Error User Info to telemetry to show detailed info in case of an analysis error.
Added local on-device analysis.
Added oval and rectangular frames.
Added Xcode 12.5.1+ support.
Added SDK configuration with licenses.
Added the One Shot gesture.
Improved OZVerificationResult
: added bestShotURL
which contains the best shot image and preferredMediaURL
which contains an URL to the best quality video.
When performing a local check, you can now choose a main or back camera.
Authorization sessions extend automatically
Updated authorization interfaces.
Added the Kazakh locale
Added license error texts
You can cancel network requests
You can specify Bundle for license
Added analysis parameterization documentAnalyse
.
Fixed building errors (Xcode 12.4 / Cocoapods 1.10.1)
Added license support
Added Xcode 12 support instead of 11.
Fixed the documentAnalyse
error where you had to fill analyseStates
to launch the analysis
Fixed logging
Add the lines below in pubspec.yaml of the project you want to add the plugin to.
Add the license file (e.g., license.json or forensics.license) to the Flutter application/assets folder. In pubspec.yaml, specify the Flutter asset:
For Android, add the Oz repository to /android/build.gradle, allprojects → repositories section:
The minimum SDK version should be 21 or higher:
For iOS, set the minimum platform to 13 or higher in the Runner → Info → Deployment target → iOS Deployment Target.
In ios/Podfile, comment the use_frameworks!
line (#use_frameworks!
).
Initialize SDK by calling the init
plugin method. Note that the license file name and path should match the ones specified in pubspec.yaml (e.g., assets/license.json).
Use the API credentials (login, password, and API URL) that you’ve received from us.
In production, instead of hard-coding the login and password inside the application, it is recommended to get the access token on your backend via the API auth method, then pass it to your application:
To start recording, use the executeLiveness
method to obtain the recorded media:
The media
object contains the captured media data.
To run the analyses, execute the code below.
Create the Analysis
object:
Execute the formed analysis:
The analysisResult
list of objects contains the result of the analysis.
If you want to use media captured by another SDK, the code should look like this:
A singleton for Oz SDK.
Initializes OZSDK with the license data. The closure is either license data or LicenseError.
Returns
-
Forces the license installation.
Retrieves an access token for a user.
Returns
The access token or an error.
Retrieves an access token for a user to send telemetry.
Returns
The access token or an error.
Checks whether an access token exists.
Parameters
-
Returns
The result – the true or false value.
Deletes the saved access token
Parameters
-
Returns
-
Creates the Liveness check controller.
Returns
UIViewController or an exception.
Creates the Liveness check controller.
Returns
UIViewController or an exception.
Deletes all videos.
Parameters
-
Returns
-
Retrieves the telemetry session ID.
Parameters
-
Returns
The telemetry session ID (String parameter).
Sets the bundle to look for translations in.
Parameters
Returns
-
Sets the length of the Selfie gesture (in milliseconds).
SDK locale (if not set, works automatically).
The host to call for Liveness video analysis.
The holder for attempts counts before SDK returns error.
The SDK version.
A delegate for OZSDK.
Gets the Liveness check results.
Returns
-
The error processing method.
Returns
-
A protocol for performing checks.
Creates the AnalysisRequest instance.
Returns
The AnalysisRequest instance.
Adds an analysis to the AnalysisRequest instance.
Returns
-
Uploads media on server.
Returns
-
Adds the folder ID to upload media to a certain folder.
Returns
-
Adds metadata to a folder.
Returns
-
Runs the analyses.
Returns
The analysis result or an error.
Customization for OzLivenessSDK (use OZSDK.customization
).
A set of customization parameters for the toolbar.
A set of customization parameters for the center hint that guides a user through the process of taking an image of themselves.
A set of customization parameters for the hint animation.
A set of customization parameters for the frame around the user face.
A set of customization parameters for the background outside the frame.
A set of customization parameters for the SDK version text.
A set of customization parameters for the antiscam message that warns user about their actions being recorded.
Logo customization parameters. Custom logo should be allowed by license.
A source of a license.
The license data.
Contains action from the captured video.
Contains the locale code according to ISO 639-1.
Contains all the information on the media captured.
The type of media captured.
Error description.
Contains information on what media to analyze and what analyses to apply.
The type of the analysis.
Currently, the .document analysis can't be performed in the on-device mode.
The mode of the analysis.
Shows the media processing status.
Shows the files' uploading status.
Shows the analysis processing status.
Describes the analysis result for the single media.
Contains the consolidated analysis results for all media.
Contains the results of the checks performed.
The general status for all analyses applied to the folder created.
Contains the results for single analyses.
Frame shape settings.
Possible license errors.
The authorization type.
Defines the settings for the repeated media upload.
Defines what type of media is being sent to the server in case of the hybrid analysis once the on-device analysis is finished successfully. By default, the system uploads the compressed video.
Deletes all action videos from file system (iOS 8.4.0 and higher, Android).
Returns
Future<Void>.
Returns the SDK version.
Returns
Future<String>.
Initializes SDK with license sources.
Returns
Authentication via credentials.
Returns
Authentication via access token.
Returns
Connection to the telemetry server via credentials.
Returns
Connection to the telemetry server via access token.
Returns
Checks whether an access token exists.
Returns
Deletes the saved access token.
Returns
Nothing (void).
Returns the list of SDK supported languages.
Returns
List<Locale>.
Starts the Liveness video capturing process.
Returns
List<Media>.
Sets the length of the Selfie gesture (in milliseconds).
Returns
Error if any.
Launches the analyses.
Returns
List<RequestResult>.
Sets the SDK localization.
The number of attempts before SDK returns error.
Sets the UI customization values for OzLivenessSDK. The values are described in the Customization structures section. Structures can be found in the lib\customization.dart file.
Loads the customized resources’ parameters from the iOS/Android customization and passes them to the Flutter aplication level.
Returns
The JSON object woth the customization resources' parameters.
Sets the timeout for the face alignment for actions.
Add fonts and drawable resources to the application/ios project.
Fonts and images should be placed into related folders:
ozforensics_flutter_plugin\android\src\main\res\drawable ozforensics_flutter_plugin\android\src\main\res\font
The loadCustomizationResources
method delivers the customization data to the Flutter application layer. This structure can be extended according to customers’ demands.
These are defined in the customization.dart file.
Contains the information about customization parameters.
Toolbar customization parameters.
Center hint customization parameters.
Hint animation customization parameters.
Frame around face customization parameters.
SDK version customization parameters.
Background customization parameters.
Defined in the models.dart file.
Stores the language information.
The type of media captured.
The type of media captured.
Contains an action from the captured video.
Stores information about media.
Stores information about the analysis result.
Stores data about a single analysis.
Analysis type.
Analysis mode.
Contains the action from the captured video.
The general status for all analyses applied to the folder created.
Defines what type of media is being sent to the server in case of the hybrid analysis once the on-device analysis is finished successfully. By default, the system uploads the compressed video.
Loaded by the loadCustomizationResources method. This is a Map to define the platform-specific resources on the plugin level.
This key is a Map for the close button icon.
This key is a Map containing the data on the uploaded fonts.
This key is a Map containing the data on the uploaded font styles.
This key is a Map containing the data on grame shape.
Android: upgraded the on-device Liveness model.
Android: security updates.
iOS: the messages displayed by the SDK after uploading media have been synchronized with Android.
iOS: the bug causing analysis delays that might have occurred for the One Shot gesture has been fixed.
Removed the pause after the Scan gesture.
Security and logging updates.
Bug fixes.
Android: if the recorded video is larger than 10 MB, it gets compressed.
Android: updated the on-device Liveness model.
iOS: changed the default behavior in case a localization key is missing: now the English string value is displayed instead of a key.
Fixed some bugs.
Implemented the possibility of using a master license that works with any bundle_id
.
Fixed the bug with background color flashing.
Video compression failure on some phone models is now fixed.
First version.
Master license is the offline license that allows using Mobile SDKs with any bundle_id
, unlike the regular licenses. To get a master license, create a pair of keys as shown below. Email us the public key, and we will email you the master license shortly after that.
Your application needs to sign its bundle_id
with the private key, and the Mobile SDK checks the signature using the public key from the master license. Master licenses are time-limited.
This section describes the process of creating your private and public keys.
To create a private key, run the commands below one by one.
You will get these files:
privateKey.der is a private .der key;
privateKey.txt is privateKey.der encoded by base64. This key containing will be used as the host app bundle_id signature.
File examples:
To create a public key, run this command.
You will get the public key file: publicKey.pub. To get a license, please email us this file. We will email you the license.
File example:
SDK initialization:
For Android 6.0 (API level 23) and older:
Add the implementation 'com.madgag.spongycastle:prov:1.58.0.0'
dependency;
Before creating a signature, call Security.insertProviderAt(org.spongycastle.jce.provider.BouncyCastleProvider(), 1)
Prior to the SDK initializing, create a base64-encoded signature for the host app bundle_id
using the private key.
Signature creation example:
Pass the signature as the masterLicenseSignature
parameter during the SDK initialization.
If the signature is invalid, the initialization continues as usual: the SDK checks the list of bundle_id
included into the license, like it does it by default without a master license.
Parameter | Type | Description |
---|---|---|
The length of the Selfie gesture is now (affects the video file size).
The OpenSSL command specification:
Removed method
Replacement
analyse
AnalysisRequest.run
addToFolder
uploadMedia
documentAnalyse
AnalysisRequest.run
uploadAndAnalyse
AnalysisRequest.run
runOnDeviceBiometryAnalysis
AnalysisRequest.run
runOnDeviceLivenessAnalysis
AnalysisRequest.run
addMedia
uploadMedia
Parameter
Type
Description
actions
List<VerificationAction>
Actions from the captured video
use_main_camera
Boolean
If True
, uses the main camera, otherwise the front one.
Parameter
Type
Description
licenseSources
The source of the license
Parameter
Type
Description
licenseSource
Source of the license
Parameter
Type
Description
apiConnection
Authorization parameters
Parameter
Type
Description
eventsConnection
Telemetry authorization parameters
Parameter
Type
Description
delegate
The delegate for Oz Liveness
actions
Captured action
cameraPosition (optional)
AVCaptureDevice.Position
Captured camera position
Parameter
Type
Description
actions
Captured action
FaceCaptureCompletion
type alias used as follows:
public typealias FaceCaptureCompletion = (_ results: [OZMedia]?, _ error: OZVerificationStatus?) -> Void
cameraPosition (optional)
AVCaptureDevice.Position
Captured camera position
Parameter
Type
Description
languageBundle
Bundle
The bundle that contains translations
Parameter
Type
Description
selfieLength
Int
The length of the Selfie gesture (in milliseconds). Should be within 500-5000 ms, the default length is 700
Parameter
Type
Description
localizationCode
The localization code
Parameter
Type
Description
host
String
Host address
Parameter
Type
Description
singleCount
Int
Attempts on a single action/gesture
commonCount
Int
Total number of attempts on all actions/gestures if you use a sequence of them
faceAlignmentTimeout
Float
Time needed to align face into frame
uploadMediaSettings
Sets the number of attempts and timeout between them
Parameter
Type
Description
version
String
Version number
Parameter
Type
Description
results
[OzMedia]
An array of the OzMedia objects.
Parameter
Type
Description
status
The error description.
Parameter
Type
Description
folderId (optional)
String
The identifier to define when you need to upload media to a certain folder.
Parameter
Type
Description
analysis
A structure containing information on the analyses required.
Parameter
Type
Description
media
Media or an array of media objects to be uploaded.
Parameter
Type
Description
folderId
String
The folder identifier.
Parameter
Type
Description
meta
[String]
An array of metadata as follows:
["meta1": "data1"]
Parameter
Type
Description
statusHandler
A callback function as follows:
statusHandler: @escaping ((_ status:
RequestStatus
) -> Void)
The handler that is executed when the scenario state changes
errorHandler
A callback function as follows:
errorHandler: @escaping ((_ error: Error) -> Void)
Error handler
completionHandler
A callback function as follows:
completionHandler: @escaping (_ results :
RequestResult
) -> Void)
The handler that is executed when the run method completes.
Parameter
Type
Description
closeButtonIcon
UIImage
An image for the close button
closeButtonColor
UIColor
Close button tintColor
titleFont
UIFont
Toolbar title text font
titleColor
UIColor
Toolbar title text color
backgroundColor
UIColor
Toolbar background color
titleText
String
Text on the toolbar
Parameter
Type
Description
textFont
UIFont
Center hint text font
textColor
UIColor
Center hint text color
backgroundColor
UIColor
Center hint text background
verticalPosition
Int
Center hint vertical position from the screen top (in %, 0-100)
hideTextBackground
Bool
Hides text background
backgroundCornerRadius
Int
Center hint background frame corner radius
Parameter
Type
Description
hideAnimation
Bool
A switcher for hint animation, if True
, the animation is hidden
animationIconSize
CGfloat
A side size of the animation icon square
hintGradientColor
UIColor
The close-to-frame gradient color
Parameter
Type
Description
geometryType
The frame type: oval, rectangle, circle, or square
cornerRadius
CGFloat
Rectangle corner radius (in dp)
strokeFaceNotAlignedColor
UIColor
Frame color when a face is not aligned properly
strokeFaceAlignedColor
UIColor
Frame color when a face is aligned properly
strokeWidth
CGFloat
Frame stroke width (in dp, 0-20)
strokePadding
CGFloat
A padding from the stroke to the face alignment area (in dp, 0-10)
Parameter
Type
Description
backgroundColor
UIColor
Background color
Parameter
Type
Description
textFont
UIFont
SDK version text font
textColor
UIColor
SDK version text color
Parameter
Type
Description
customizationEnableAntiscam
Bool
Adds the antiscam message
customizationAntiscamTextMessage
String
Antiscam message text
customizationAntiscamTextFont
UIFont
Antiscam message text font
customizationAntiscamTextColor
UIColor
Antiscam message text color
customizationAntiscamBackgroundColor
UIColor
Antiscam message text background color
customizationAntiscamCornerRadius
CGFloat
Background frame corner radius
customizationAntiscamFlashColor
UIColor
Color of the flashing indicator close to the antiscam message
Parameter
Type
Description
image
UIImage
Logo image
size
CGSize
Logo size (in dp)
Case
Description
licenseFilePath
An absolute path to a license (String).
LicenseData
Full license information.
Parameter
Type
Description
appIDS
[String]
An array of bundle IDs
expires
TimeInterval
The expiration interval
features
Features
License features
configs (optional)
ABTestingConfigs
Additional configuration
Case
Description
smile
Smile
eyes
Blink
scanning
Scan
selfie
A selfie with face alignment check
one_shot
The best shot from the video taken
left
Head turned left
right
Head turned right
down
Head tilted downwards
up
Head lifted up
Case
Description
en
English
hy
Armenian
kk
Kazakh
ky
Kyrgyz
tr
Turkish
es
Spanish
pt-BR
Portuguese (Brazilian)
custom(String)
Custom language (language ISO 639-1 code, two letters)
Parameter
Type
Description
movement
User action type
mediaType
Type of media
metaData
[String] as follows:
["meta1": "data1"]
Metadata if any
videoURL
URL
URL of the Liveness video
bestShotURL
URL
URL of the best shot in PNG
preferredMediaURL
URL
URL of the API media container
timestamp
Date
Timestamp for the check completion
Case
Description
movement
A media with an action
documentBack
The back side of the document
documentFront
The front side of the document
Case
Description
userNotProcessed
The Liveness check was not processed
failedBecauseUserCancelled
The check was interrupted by user
failedBecauseCameraPermissionDenied
The Liveness check can't be performed: no camera access
failedBecauseOfBackgroundMode
The Liveness check can't be performed: background mode
failedBecauseOfTimeout
The Liveness check can't be performed: timeout
failedBecauseOfAttemptLimit
The Liveness check can't be performed: attempts limit exceeded
failedBecausePreparingTimout
The Liveness check can't be performed: face alignment timeout
failedBecauseOfLowMemory
The Liveness check can't be performed: no memory left
Parameter
Type
Description
media
[OzMedia]
An array of the OzMedia objects
type
The type of the analysis
mode
The mode of the analysis
sizeReductionStrategy
Defines what type of media is being sent to the server in case of the hybrid analysis once the on-device analysis is finished successfully
params (optional)
String
Additional parameters
Case
Description
biometry
The algorithm that allows comparing several media and check if the people on them are the same person or not
quality
The algorithm that aims to check whether a person in a video is a real human acting in good faith, not a fake of any kind.
document
The analysis that aims to recognize the document and check if its fields are correct according to its type.
blacklist
The analysis that compares a face on a captured media with faces from the pre-made media database.
Case
Description
onDevice
The on-device analysis with no server needed
serverBased
The server-based analysis
hybrid
The hybrid analysis for Liveness: if the score received from an on-device analysis is too high, the system initiates a server-based analysis as an additional check.
Case
Description
addToFolder
The system is creating a folder and adding files to this folder
addAnalyses
The system is adding analyses
waitAnalysisResult
The system is waiting for the result
Parameter
Type
Description
media
The object that is being uploaded at the moment
index
Int
Number of this object in a list
from
Int
Objects quantity
progress
Progress
Object uploading status
Parameter
Type
Description
status
Processing analysis status
progressStatus
Media uploading status
Parameter
Type
Description
resolution
Consolidated analysis result
sourceId
String
Media identifier
isOnDevice
Bool
Analysis mode
confidenceScore
Float
Resulting score
mediaType
String
Media file type: VIDEO / IMAGE / SHOT_SET
media
Media that is being analyzed
error
AnalysisError (inherits from Error)
Error
Parameter
Type
Description
resolution
Consolidated analysis result
folderId
String
Folder identifier
analysisResults
A list of analysis results
Parameter
Type
Description
resolution
Analysis resolution
type
Analysis type
mode
Analysis mode
analysisId
String
Analysis identifier
error
AnalysisError (inherits from Error)
Error
resultMedia
Results of the analysis for single media files
confidenceScore
Float
The resulting score
serverRawResponse
String
Server response
Case
Description
INITIAL
No analyses have been applied yet
PROCESSING
The analyses are in progress
FAILED
One or more analyses failed due to some error and couldn't get finished
FINISHED
The analyses are finished
DECLINED
The check failed (e.g., faces don't match or some spoofing attack detected)
SUCCESS
Everything went fine, the check succeeded (e.g., faces match or liveness confirmed)
OPERATOR_REQUIRED
The result should be additionally checked by a human operator
Parameter
Type
Description
analyseResolutionStatus
The analysis status
type
The analysis type
folderID
String
The folder identifier
score
Float
The result of the check performed
Case
Description
oval
Oval frame
rectangle(cornerRadius: CGFloat)
Rectangular frame (with corner radius)
circle
Circular frame
square(cornerRadius: CGFloat)
Square frame (with corner radius)
Case
Description
licenseFileNotFound
The license is not found
licenseParseError
Cannot parse the license file, the license might be invalid
licenseBundleError
The bundle_id
in the license file doesn't match with bundle_id
used.
licenseExpired
The license is expired
Case
Description
fromServiceToken
Authorization with a token:
host: String
token: String
fromCredentials
Authorization with credentials:
host: String
login: String
password: String
attemptsCount
Int
Number of attempts for media upload
attemptsTimeout
Int
Timeout between attempts
uploadOriginal
The original video
uploadCompressed
The compressed video
uploadBestShot
The best shot taken from the video
uploadNothing
Nothing is sent (note that no folder will be created)
Parameter
Type
Description
licenses
List<String>
A list of licences
Case
Text
True
Initialization has completed successfully
False
Initialization error
Parameter
Type
Description
String
User email
password
String
User password
host
String
Server URL
Case
Text
Success
Nothing (void)
Failed
PlatformException:
code = AUTHENTICATION_FAILED
message = exception details
Parameter
Type
Description
token
String
User email
host
String
Server URL
Case
Text
Success
Nothing (void)
Failed
PlatformException:
code = AUTHENTICATION_FAILED
message = exception details
Parameter
Type
Description
String
User email
password
String
User password
host
String
Server URL
Case
Text
Success
Nothing (void)
Failed
PlatformException:
code = AUTHENTICATION_FAILED
message = exception details
Parameter
Type
Description
token
String
User email
host
String
Server URL
Case
Text
Success
Nothing (void)
Failed
PlatformException:
code = AUTHENTICATION_FAILED
message = exception details
Case
Returns
Token exists
True
Token does not exist
False
Parameter
Type
Description
actions
List<VerificationAction>
Actions to execute
mainCamera
Boolean
Use main (True
) or front (False
) camera
Parameter
Type
Description
selfieLength
Int
The length of the Selfie gesture (in milliseconds). Should be within 500-5000 ms, the default length is 700
Parameter
Type
Description
analysis
List<Analysis>
The list of Analysis structures
uploadMedia
List<Media>
The list of the captures videos
params
Map<String, Any>
Additional parameters
Parameter
Type
Description
locale
The SDK language
Parameter
Type
Description
singleCount
int
Attempts on a single action/gesture
commonCount
int
Total number of attempts on all actions/gestures if you use a sequence of them
Parameter
Type
Description
timeout
int
Timeout in milliseconds
Parameter
Type
Description
closeButtonIcon
String
Close button icon received from plugin
closeButtonColor
String
Color #XXXXXX
titleText
String
Header text
titleFont
String
Text font
titleSize
int
Font size
titleFontStyle
String
Font style
titleColor
String
Color #XXXXXX
titleAlpha
int
Header text opacity
isTitleCentered
bool
Sets the text centered
backgroundColor
String
Header background color #XXXXXX
backgroundAlpha
int
Header background opacity
Parameter
Type
Description
textFont
String
Text font
textFontStyle
String
Font style
textColor
String
Color #XXXXXX
textSize
int
Font size
verticalPosition
int
Y position
textAlpha
int
Text opacity
centerBackground
bool
Sets the text centered
Parameter
Type
Description
hideAnimation
bool
Hides the hint animation
animationIconSize
int
Animation icon size in px (40-160)
hintGradientColor
String
Color #XXXXXX
hintGradientOpacity
int
Gradient color
Parameter
Type
Description
geometryType
String
Frame shape received from plugin
geometryTypeRadius
int
Corner radius for rectangle
strokeWidth
int
Frame stroke width
strokeFaceNotAlignedColor
String
Color #XXXXXX
strokeFaceAlignedColor
String
Color #XXXXXX
strokeAlpha
int
Stroke opacity
strokePadding
int
Stroke padding
Parameter
Type
Description
textFont
String
Text font
textFontStyle
String
Font style
textColor
String
Color #XXXXXX
textSize
int
Font size
textAlpha
int
Text opacity
Parameter
Type
Description
backgroundColor
String
Color #XXXXXX
backgroundAlpha
int
Background opacity
Case
Description
en
English
hy
Armenian
kk
Kazakh
ky
Kyrgyz
tr
Turkish
es
Spanish
pt_br
Portuguese (Brazilian)
Case
Description
movement
A media with an action
documentBack
The back side of the document
documentFront
The front side of the document
Case
Description
documentPhoto
A photo of a document
video
A video
shotSet
A frame archive
Case
Description
blank
A video with no gesture
photoSelfie
A selfie photo
videoSelfieOneShot
A video with the best shot taken
videoSelfieScan
A video with the scanning gesture
videoSelfieEyes
A video with the blink gesture
videoSelfieSmile
A video with the smile gesture
videoSelfieHigh
A video with the lifting head up gesture
videoSelfieDown
A video with the tilting head downwards gesture
videoSelfieRight
A video with the turning head right gesture
videoSelfieLeft
A video with the turning head left gesture
photoIdPortrait
A photo from a document
photoIdBack
A photo of the back side of the document
photoIdFront
A photo of the front side of the document
Parameter
Type
Description
Platform
fileType
The type of the file
Android
movement
An action on a media
iOS
mediatype
String
A type of media
iOS
videoPath
String
A path to a video
bestShotPath
String
path of the best shot in PNG for video or image path for liveness
preferredMediaPath
String
URL of the API media container
photoPath
String
A path to a photo
archivePath
String
A path to an archive
tag
A tag for media
Android
Parameter
Type
Description
Platform
folderId
String
The folder identifier
type
The analysis type
errorCode
int
The error code
Android only
errorMessage
String
The error message
mode
The mode of the analysis
confidenceScore
Double
The resulting score
resolution
The completed analysis' result
status
Boolean
The analysis state:
true
- success;
false
- failed
Parameter
Type
Description
type
The type of the analysis
mode
The mode of the analysis
mediaList
List<Media>
Media to analyze
params
Map<String, String>
Additional analysis parameters
sizeReductionStrategy
Defines what type of media is being sent to the server in case of the hybrid analysis once the on-device analysis is finished successfully
Case
Description
biometry
The algorithm that allows comparing several media and check if the people on them are the same person or not
quality
The algorithm that aims to check whether a person in a video is a real human acting in good faith, not a fake of any kind.
Case
Description
onDevice
The on-device analysis with no server needed
serverBased
The server-based analysis
hybrid
The hybrid analysis for Liveness: if the score received from an on-device analysis is too high, the system initiates a server-based analysis as an additional check.
Case
Description
oneShot
The best shot from the video taken
blank
A selfie with face alignment check
scan
Scan
headRight
Head turned right
headLeft
Head turned left
headDown
Head tilted downwards
headUp
Head lifted up
eyeBlink
Blink
smile
Smile
Case
Description
failed
One or more analyses failed due to some error and couldn't get finished
declined
The check failed (e.g., faces don't match or some spoofing attack detected)
success
Everything went fine, the check succeeded (e.g., faces match or liveness confirmed)
operatorRequired
The result should be additionally checked by a human operator
uploadOriginal
The original video
uploadCompressed
The compressed video
uploadBestShot
The best shot taken from the video
uploadNothing
Nothing is sent (note that no folder will be created)
Key
Value
Close
Android drawable resource / iOS Pods resource
Arrow
Android drawable resource / iOS Pods resource
Key
Value
Flutter application font name
Android font resource / iOS Pods resource, used to retrieve the font on the plugin level
Key
Value
Flutter application font style name
Name of the style retrieved for the font creation on the plugin level
Key
Value
Oval
Oval shape
Rectangle
Rectangular shape
If you want to get back to the previous (up to 6.4.2) versions' design, reset the customization settings of the capture screen and apply the parameters that are listed below.
Create a controller that will capture videos as follows:
Once video is captured, the system calls the onOZLivenessResult
method:
If you use our SDK just for capturing videos, omit the Checking Liveness and Face Biometry step.
If a user closes the capturing screen manually, the failedBecauseUserCancelled
error appears.
action
– a list of user’s while capturing the video.
The method returns the results of video capturing: the [
]
objects. The system uses these objects to perform checks.