The objective of the Liveness check is to verify the authenticity and physical presence of an individual in front of the camera. In the passive Liveness check, it is sufficient to capture a user's face while they look into the camera. Conversely, the active Liveness check requires the user to perform an action such as smiling, blinking, or turning their head. While passive Liveness is more user-friendly, active Liveness may be necessary in some situations to confirm that the user is aware of undergoing the Liveness check.

In our Mobile or Web SDKs, you can define what action the user is required to do. You can also combine several actions into a sequence. Actions vary in the following dimensions:

• User experience,

• File size,

• Liveness check accuracy,

• Suitability for review by a human operator or in court.

In most cases, the Selfie action is optimal, but you can choose other actions based on your specific needs. Here is a summary of available actions:

Passive Liveness

Active Liveness

To recognize the actions from either passive or active Liveness, our algorithms refer to the corresponding tags. These tags indicate the type of action that a user is performing within a media. For more information, please read the Media Tags article. The detailed information on how the actions, or, in other words, gestures are called in different Oz Liveness components is here.

This article describes Oz components that can be integrated into your infrastructure in various combinations depending on your needs.

The typical integration scenarios are described in the Integration Quick Start Guides section.

Oz API

Oz API is the central component of the system. It provides RESTful application programming interface to the core functionality of Liveness and Face matching analyses, along with many important supplemental features:

• Persistence: your media and analyses are stored for future reference unless you explicitly delete them,

• Authentication, roles and access management,

• Asynchronous analyses,

• Ability to work with videos as well as images.

For more information, please refer to Oz API Key Concepts and Oz API Developer Guide. To test Oz API, please check the Postman collection here.

Under the logical hood, Oz API has the following components:

• File storage and database where media, analyses, and other data are stored,

• The Oz BIO module that runs neural network models to perform facial biometry magic,

• Licensing logic.

The front-end components (Oz Liveness Mobile or Web SDK) connect to Oz API to perform server-side analyses either directly or via customer's back end.

iOS and Android SDK

iOS and Android SDK are collectively referred to as Mobile SDKs or Native SDKs. They are written on Swift and Kotlin/Java, respectively, and designed to be integrated into your native mobile application.

Mobile SDKs implement the out-of-the-box customizable user interface for capturing Liveness video and ensure that the two main objectives are met:

• The capture process is smooth for users,

• The quality of a video is optimal for the subsequent Liveness analysis.

After Liveness video is recorded and available to your mobile application, you can run the server-side analysis. You can use corresponding SDK methods, call the API directly from your mobile application, or pass the media to your backend and interact with Oz API from there.

The basic integration option is described in the Quick Start Guide.

Mobile SDKs are also capable of On-device Liveness and Face matching. On-device analyses may be a good option in low-risk context, or when you don’t want the media to leave the users’ smartphones. Oz API is not required for On-device analyses. To learn how it works, please refer to this Integration Quick Start Guide.

Web SDK

Web Adapter and Web Plugin together constitute Web SDK.

Web SDK is designed to be integrated into your web applications and have the same main goals as Mobile SDKs:

• The capture process is smooth for users,

• The quality of a video is optimal for the subsequent Liveness analysis.

Web Adapter needs to be set up on a server side. Web Plugin is called by your web application and works in a browser context. It communicates with Web Adapter, which, in turn, communicates with Oz API.

Web SDK adds the two-layer protection against injection attacks:

1. Collects information about browser context and camera properties to detect usage of virtual cameras or other injection methods.

2. Records liveness video in a format that allows server-side neural networks to search for traces of injection attack in the video itself.

Check the Integration Quick Start Guide for the basic integration scenario, and explore the Web SDK Developer Guide for more details.

Web UI (Web Console)

Web UI is a convenient user interface that allows to explore the stored API data in the easy way. It relies on API authentication and database and does not store any data on its own.

Web console has an intuitive interface, yet the user guide is available here.

Liveness and Face Matching can also be provided by the Oz API Lite module. Oz API Lite is conceptually different from Oz API.

• Fully stateless, no persistence,

• Extremely easy to scale horizontally,

• No built-in authentication and access management,

• Works with single images, not videos.

Oz API Lite is suitable when you want to embed it into your product and/or have extremely high performance requirements (millions checks per week).

For more details, please refer to the Oz API Lite Developer Guide.

For commercial use of Oz Forensics products, a license is required. The license is time-limited and defines the software access parameters based on the terms of your agreement.

Once you initialize mobile SDK, run Web Plugin, or use Oz Bio, the system checks if your license is valid. The check runs in the background and has minimal impact on the user experience.

As you can see on the scheme above, the license is required for:

• Mobile SDKs for iOS and Android,

• Web SDK, which consists of Web Adapter and Web Plugin,

For each of the components, you require a separate license which is bound to this component. Thus, if you use all three components, three licenses are required.

Native SDKs (iOS and Android)

To issue a license for mobile SDK, we require your bundle (application) ID. There are two types of licenses for iOS and Android SDKs: online and offline. Any license type can be applied to any analysis mode: on-device, server-based, or hybrid.

Online License

As its name suggests, an online license requires a stable connection. Once you initialize our SDK with this license, it connects to our license server and retrieves information about license parameters, including counters of transactions or devices, where:

• Transaction: increments each time you start a video capture.

• Device: increments when our SDK is installed on a new device.

The online license can be transaction-limited, device-limited, or both, according to your agreement.

The main advantages of the online license are:

• You don’t need to update your application after the license renewal,

• And if you want to add a new bundle ID to the incense, there’s also no need to re-issue it. Everything is done on the fly.

The data exchange for the online license is quick, ensuring your users won't experience almost any delay compared to using the offline license.

Please note that even though on-device analyses don’t need the Internet themselves, you still require a connection for license verification.

Offline License

Offline license is a type of license that can work without Internet. All license parameters are set in the license file, and you just need to add the file to your project. This license type doesn’t have any restrictions on transactions or devices.

The main benefit of the offline license is its autonomy, allowing it to function without a network connection. However, when your license expires, and you add a new one, you’ll require to release a new version of your application in Google Play and App Store. Otherwise, the SDK won’t function.

How to add a license to mobile SDK:

Web SDK

Web SDK license is almost similar to the mobile SDK offline license. It can function without network connection, and the license file contains all the necessary parameters, such as expiration date. Web SDK license also has no restrictions on transactions or devices.

The difference between Mobile SDK offline license and Web SDK license is that you don’t need to release a new application version when Web SDK license is renewed.

On-Premise (Oz BIO or Server License)

Trial

Once you're ready to move to commercial use, a new production license will be issued. We’ll provide you with new production credentials and assist you with integration and configuration. Our engineers are always available to help.

Our software offers flexible licensing options to meet your specific needs. Whether you prioritize seamless updates or prefer autonomous operation, we have a solution tailored for you. If you have any questions, please contact us.

In this section, we listed the guides for the server-based liveness check integrations.

Oz Forensics specializes in liveness and face matching: we develop products that help you to identify your clients remotely and avoid any kind of spoofing or deepfake attack. Oz software helps you to add facial recognition to your software systems and products. You can integrate Oz modules in many ways depending on your needs. We are constantly improving our components, increasing their quality.

Oz Liveness

• Oz Liveness is responsible for recognizing a living person on a video it receives. Oz Liveness can distinguish a real human from their photo, video, mask, or other kinds of spoofing and deepfake attacks. The algorithm is certified in ISO-30137-3 standard by NIST accreditation iBeta biometric test laboratory with 100% accuracy.

Our liveness technology protects both against injection and presentation attacks.

The injection attack detection is layered. Our SDK examines user environment to detect potential manipulations: browser, camera, etc. Further on, the deep neural network comes into play to defend against even the most sophisticated injection attacks.

Oz Face Matching (Biometry)

• Oz Face Matching (Biometry) aims to identify the person, verifying that the person who performs the check and the papers' owner are the same person. Oz Biometry looks through the video, finds the best shot where the person is clearly seen, and compares it with the photo from ID or another document. The algorithm's accuracy is 99.99% confirmed by NIST FRVT.

Our biometry technology has both 1:1 Face Verification and 1:N Face Identification, which are also based on ML algorithms. To train our neural networks, we use an own framework based on state-of-the-art technologies. The large private dataset (over 4.5 million unique faces) with a wide representation of ethnic groups as well as using other attributes (predicted race, age, etc.) helps our biometric models to provide the robust matching scores.

Our face detector can work with photos and videos. Also, the face detector excels in detecting faces in images of IDs and passports (which can be rotated or of low quality).

This guide outlines the steps for integrating the Oz Liveness Mobile SDK into a customer mobile application for capturing facial videos and performing on-device liveness checks without sending any data to a server.

The SDK implements the ready-to-use face capture user interface that is essential for seamless customer experience and accurate liveness results.

Oz Liveness Mobile SDK requires a license. License is bound to the bundle_id of your application, e.g., com.yourcompany.yourapp. Issue the 1-month trial license on our website or email us for a long-term license.

Android

1. Add SDK to your project

In the build.gradle of your project, add:

allprojects {
    repositories {
        maven { url "https://ozforensics.jfrog.io/artifactory/main" }
    }
}

In the build.gradle of the module, add:

dependencies {
    implementation 'com.ozforensics.liveness:full:<version>'
    // You can find the version needed in the Android changelog
}

2. Initialize SDK

Rename the license file to forensics.license and place it into the project's res/raw folder.

OzLivenessSDK.init(
    context,
    listOf(LicenseSource.LicenseAssetId(R.raw.forensics))
)

OzLivenessSDK.INSTANCE.init(
        context,
        Collections.singletonList(new LicenseSource.LicenseAssetId(R.raw.forensics)),
        null
);

3. Add face recording

To start recording, use startActivityForResult:

val OZ_LIVENESS_REQUEST_CODE = 1
val intent = OzLivenessSDK.createStartIntent(listOf( OzAction.Blank)) startActivityForResult(intent, OZ_LIVENESS_REQUEST_CODE)

int OZ_LIVENESS_REQUEST_CODE = 1;
Intent intent = OzLivenessSDK.INSTANCE.createStartIntent(Collections.singletonList(OzAction.Blank));
startActivityForResult(intent, OZ_LIVENESS_REQUEST_CODE);

To obtain the captured video, use onActivityResult:

override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
    super.onActivityResult(requestCode, resultCode, data)
        if (requestCode == OZ_LIVENESS_REQUEST_CODE) {
            val sdkMediaResult = OzLivenessSDK.getResultFromIntent(data)
            val sdkErrorString = OzLivenessSDK.getErrorFromIntent(data)
            if (!sdkMediaResult.isNullOrEmpty()) {
                analyzeMedia(sdkMediaResult)
            } else println(sdkErrorString)
        }
    }

protected void onActivityResult(int requestCode, int resultCode, Intent data) {
    super.onActivityResult(requestCode, resultCode, data);
    if (requestCode == OZ_LIVENESS_REQUEST_CODE) {
        List<OzAbstractMedia> sdkMediaResult = OzLivenessSDK.INSTANCE.getResultFromIntent(data);
        String sdkErrorString = OzLivenessSDK.INSTANCE.getErrorFromIntent(data);
        if (sdkMediaResult != null && !sdkMediaResult.isEmpty()) {
            analyzeMedia(sdkMediaResult);
        } else System.out.println(sdkErrorString);
    }
}

The sdkMediaResult object contains the captured videos.

4. Run analyses

To run the analyses, execute the code below. Mind that mediaList is an array of objects that were captured (sdkMediaResult) or otherwise created (media you captured on your own).

private fun analyzeMedia(mediaList: List<OzAbstractMedia>) {
    AnalysisRequest.Builder()
        .addAnalysis(Analysis(Analysis.Type.QUALITY, Analysis.Mode.ON_DEVICE, mediaList))
        .build()
        .run(object : AnalysisRequest.AnalysisListener {
            override fun onSuccess(result: List<OzAnalysisResult>) {
                result.forEach { 
                    println(it.resolution.name)
                    println(it.folderId)
                }
            }
            override fun onError(error: OzException) {
                error.printStackTrace()
            }
        })
} 

private void analyzeMedia(List<OzAbstractMedia> mediaList) {
    new AnalysisRequest.Builder()
            .addAnalysis(new Analysis(Analysis.Type.QUALITY, Analysis.Mode.ON_DEVICE, mediaList, Collections.emptyMap()))
            .build()
            .run(new AnalysisRequest.AnalysisListener() {
                @Override public void onStatusChange(@NonNull AnalysisRequest.AnalysisStatus analysisStatus) {}
                @Override
                public void onSuccess(@NonNull List<OzAnalysisResult> list) {
                    for (OzAnalysisResult result: list) {
                        System.out.println(result.getResolution().name());
                        System.out.println(result.getFolderId());
                    }
                }
                @Override
                public void onError(@NonNull OzException e) { e.printStackTrace(); }
    });
}

iOS

1. Add our SDK to your project

Install OZLivenessSDK via CocoaPods. To integrate OZLivenessSDK into an Xcode project, add to Podfile:

pod 'OZLivenessSDK', :git => 'https://gitlab.com/oz-forensics/oz-liveness-ios', :tag => '<version>' // You can find the version needed in  iOS changelog

2. Initialize SDK

Rename the license file to forensics.license and put it into the project.

OZSDK(licenseSources: [.licenseFileName("forensics.license")]) { licenseData, error in
    if let error = error {
        print(error.errorDescription)
    }
}

3. Add face recording

Create a controller that will capture videos as follows:

let actions: [OZVerificationMovement] = [.selfie]
let ozLivenessVC: UIViewController = OZSDK.createVerificationVCWithDelegate(delegate, actions: actions) 
self.present(ozLivenessVC, animated: true)

The delegate object must implement OZLivenessDelegate protocol:

let actions: [OZVerificationMovement] = [.selfie]
let ozLivenessVC: UIViewController = OZSDK.createVerificationVCWithDelegate(delegate, actions: actions) 
self.present(ozLivenessVC, animated: true)

4. Run analyses

Use AnalysisRequestBuilder to initiate the Liveness analysis.

let analysisRequest = AnalysisRequestBuilder()
let analysis = Analysis.init(
media: mediaToAnalyze, 
type: .quality, 
mode: .onDevice)
analysisRequest.uploadMedia(mediaToAnalyze)
analysisRequest.addAnalysis(analysis)
analysisRequest.run(
scenarioStateHandler: { state in }, // scenario steps progress handler
uploadProgressHandler: { (progress) in } // file upload progress handler 
) { (analysisResults : [OzAnalysisResult], error) in 
    // receive and handle analyses results here 
    for result in analysisResults {
        print(result.resolution)
        print(result.folderID)
    }
}

With these steps, you are done with basic integration of Mobile SDKs. The data from the on-device analysis is not transferred anywhere, so please bear in mind you cannot access it via API or Web console. However, the internet is still required to check the license. Additionally, we recommend that you use our logging service called telemetry, as it helps a lot in investigating attacks' details. We'll provide you with credentials.

This guide outlines the steps for integrating the Oz Liveness Mobile SDK into a customer mobile application for capturing facial videos and subsequently analyzing them on the server.

The SDK implements a ready-to-use face capture user interface that is essential for seamless customer experience and accurate liveness results. The SDK methods for liveness analysis communicate with Oz API under the hood.

Before you begin, make sure you have Oz API credentials. When using SaaS API, you get them from us:

For the on-premise Oz API, you need to create a user yourself or ask your team that manages the API. See the guide on user creation via Web Console. Consider the proper user role (CLIENT in most cases or CLIENT ADMIN, if you are going to make SDK work with the pre-created folders from other API users). In the end, you need to obtain a similar set of credentials as you would get for the SaaS scenario.

We also recommend that you use our logging service called telemetry, as it helps a lot in investigating attacks' details. For Oz API users, the service is enabled by default. For on-premise installations, we'll provide you with credentials.

Oz Liveness Mobile SDK requires a license. License is bound to the bundle_id of your application, e.g., com.yourcompany.yourapp. Issue the 1-month trial license on our website or email us for a long-term license.

Android

1. Add SDK to your project

In the build.gradle of your project, add:

allprojects {
    repositories {
        maven { url "https://ozforensics.jfrog.io/artifactory/main" }
    }
}

In the build.gradle of the module, add:

dependencies {
    implementation 'com.ozforensics.liveness:full:<version>'
    // You can find the version needed in the Android changelog
}

2. Initialize SDK

Rename the license file to forensics.license and place it into the project's res/raw folder.

OzLivenessSDK.init(
    context,
    listOf(LicenseSource.LicenseAssetId(R.raw.forensics))
)

OzLivenessSDK.INSTANCE.init(
        context,
        Collections.singletonList(new LicenseSource.LicenseAssetId(R.raw.forensics)),
        null
);

3. Connect SDK to Oz API

Use API credentials (login, password, and API URL) that you’ve got from us.

OzLivenessSDK.setApiConnection(
    OzConnection.fromCredentials(host, username, password),
    statusListener(
        { token -> /* token */ },
        { ex -> /* error */ }
    )
)

OzLivenessSDK.INSTANCE.setApiConnection(
        OzConnection.Companion.fromCredentials(host, username, password),
        new StatusListener<String>() {
            @Override
            public void onStatusChanged(@Nullable String s) {}
            @Override
            public void onSuccess(String token) { /* token */ }
            @Override
            public void onError(@NonNull OzException e) { /* error */ }
        }
);

In production, instead of hard-coding login and password in the application, it is recommended to get access token on your backend with API auth method then pass it to your application:

OzLivenessSDK.setApiConnection(OzConnection.fromServiceToken(host, token))

OzLivenessSDK.INSTANCE.setApiConnection(
        OzConnection.Companion.fromServiceToken(host, token), 
        null
);

4. Add face recording

To start recording, use startActivityForResult:

val OZ_LIVENESS_REQUEST_CODE = 1
val intent = OzLivenessSDK.createStartIntent(listOf( OzAction.Blank)) startActivityForResult(intent, OZ_LIVENESS_REQUEST_CODE)

int OZ_LIVENESS_REQUEST_CODE = 1;
Intent intent = OzLivenessSDK.INSTANCE.createStartIntent(Collections.singletonList(OzAction.Blank));
startActivityForResult(intent, OZ_LIVENESS_REQUEST_CODE);

To obtain the captured video, use onActivityResult:

override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
    super.onActivityResult(requestCode, resultCode, data)
        if (requestCode == OZ_LIVENESS_REQUEST_CODE) {
            val sdkMediaResult = OzLivenessSDK.getResultFromIntent(data)
            val sdkErrorString = OzLivenessSDK.getErrorFromIntent(data)
            if (!sdkMediaResult.isNullOrEmpty()) {
                analyzeMedia(sdkMediaResult)
            } else println(sdkErrorString)
        }
    }

protected void onActivityResult(int requestCode, int resultCode, Intent data) {
    super.onActivityResult(requestCode, resultCode, data);
    if (requestCode == OZ_LIVENESS_REQUEST_CODE) {
        List<OzAbstractMedia> sdkMediaResult = OzLivenessSDK.INSTANCE.getResultFromIntent(data);
        String sdkErrorString = OzLivenessSDK.INSTANCE.getErrorFromIntent(data);
        if (sdkMediaResult != null && !sdkMediaResult.isEmpty()) {
            analyzeMedia(sdkMediaResult);
        } else System.out.println(sdkErrorString);
    }
}

The sdkMediaResult object contains the captured videos.

5. Run analyses

To run the analyses, execute the code below. Mind that mediaList is an array of objects that were captured (sdkMediaResult) or otherwise created (media you captured on your own).

private fun analyzeMedia(mediaList: List<OzAbstractMedia>) {
    AnalysisRequest.Builder()
        .addAnalysis(Analysis(Analysis.Type.QUALITY, Analysis.Mode.SERVER_BASED, mediaList))
        .build()
        .run(object : AnalysisRequest.AnalysisListener {
            override fun onSuccess(result: List<OzAnalysisResult>) {
                result.forEach { 
                    println(it.resolution.name)
                    println(it.folderId)
                }
            }
            override fun onError(error: OzException) {
                error.printStackTrace()
            }
        })
} 

private void analyzeMedia(List<OzAbstractMedia> mediaList) {
    new AnalysisRequest.Builder()
            .addAnalysis(new Analysis(Analysis.Type.QUALITY, Analysis.Mode.SERVER_BASED, mediaList, Collections.emptyMap()))
            .build()
            .run(new AnalysisRequest.AnalysisListener() {
                @Override public void onStatusChange(@NonNull AnalysisRequest.AnalysisStatus analysisStatus) {}
                @Override
                public void onSuccess(@NonNull List<OzAnalysisResult> list) {
                    for (OzAnalysisResult result: list) {
                        System.out.println(result.getResolution().name());
                        System.out.println(result.getFolderId());
                    }
                }
                @Override
                public void onError(@NonNull OzException e) { e.printStackTrace(); }
    });
}

iOS

1. Add our SDK to your project

Install OZLivenessSDK via CocoaPods. To integrate OZLivenessSDK into an Xcode project, add to Podfile:

pod 'OZLivenessSDK', :git => 'https://gitlab.com/oz-forensics/oz-liveness-ios', :tag => '<version>' // You can find the version needed in  iOS changelog

2. Initialize SDK

Rename the license file to forensics.license and put it into the project.

OZSDK(licenseSources: [.licenseFileName("forensics.license")]) { licenseData, error in
    if let error = error {
        print(error.errorDescription)
    }
}

3. Connect SDK to Oz API

Use API credentials (login, password, and API URL) that you’ve got from us.

OZSDK.setApiConnection(Connection.fromCredentials(host: “https://sandbox.ohio.ozforensics.com”, login: login, password: p)) { (token, error) in
    // Your code to handle error or token
}

In production, instead of hard-coding the login and password in the application, it is recommended to get an access token on your back end using the API auth method, then pass it to your application:

OZSDK.setApiConnection(Connection.fromServiceToken(host: "https://sandbox.ohio.ozforensics.com", token: token)) { (token, error) in
}

4. Add face recording

Create a controller that will capture videos as follows:

let actions: [OZVerificationMovement] = [.selfie]
let ozLivenessVC: UIViewController = OZSDK.createVerificationVCWithDelegate(delegate, actions: actions) 
self.present(ozLivenessVC, animated: true)

The delegate object must implement OZLivenessDelegate protocol:

let actions: [OZVerificationMovement] = [.selfie]
let ozLivenessVC: UIViewController = OZSDK.createVerificationVCWithDelegate(delegate, actions: actions) 
self.present(ozLivenessVC, animated: true)

5. Run analyses

Use AnalysisRequestBuilder to initiate the Liveness analysis. The communication with Oz API is under the hood of the run method.

let analysisRequest = AnalysisRequestBuilder()
let analysis = Analysis.init(
media: mediaToAnalyze, 
type: .quality, 
mode: .serverBased)
analysisRequest.uploadMedia(mediaToAnalyze)
analysisRequest.addAnalysis(analysis)
analysisRequest.run(
scenarioStateHandler: { state in }, // scenario steps progress handler
uploadProgressHandler: { (progress) in } // file upload progress handler 
) { (analysisResults : [OzAnalysisResult], error) in 
    // receive and handle analyses results here 
    for result in analysisResults {
        print(result.resolution)
        print(result.folderID)
    }
}

With these steps, you are done with basic integration of Mobile SDKs. You will be able to access recorded media and analysis results in Web Console via browser or programmatically via API.

In developer guides, you can also find instructions for customizing the SDK look-and-feel and access the full list of our Mobile SDK methods. Check out the table below:

Please note that the Oz Liveness Mobile SDK does not include a user interface for scanning official documents. You may need to explore alternative SDKs that offer that functionality or implement it on your own. Web SDK does include a simple photo ID capture screen.

This guide describes the steps needed to add face matching to your liveness check.

By this time you should have already implemented liveness video recording and liveness check. If not, please refer to these guides:

• Integration of Oz Liveness Web SDK

• Integration of Oz Liveness Mobile SDK

Adding Photo ID Capture Step to Web SDK

Simply add photo_id_front to the list of actions for the plugin, e.g.,

OzLiveness.open({
  lang: 'en',
  action: [
    'photo_id_front', 
    'video_selfie_blank'
  ],
  ...
});

Adding Face Matching to Android SDK

For the purpose of this guide, it is assumed that your reference photo (e.g., front side of an ID) is stored on the device as reference.jpg.

Modify the code that runs the analysis as follows:

private fun analyzeMedia(mediaList: List<OzAbstractMedia>) {

    val refFile = File(context.filesDir, "reference.jpg")
    val refMedia = OzAbstractMedia.OzDocumentPhoto(
        OzMediaTag.PhotoIdFront , // OzMediaTag.PhotoSelfie for a non-ID photo
        refFile.absolutePath
    )

    AnalysisRequest.Builder()
        .addAnalysis(Analysis(Analysis.Type.QUALITY, Analysis.Mode.SERVER_BASED, mediaList))
        .addAnalysis(Analysis(Analysis.Type.BIOMETRY, Analysis.Mode.SERVER_BASED, mediaList + refMedia))
        .build()
        .run(object : AnalysisRequest.AnalysisListener {
            override fun onSuccess(result: List<OzAnalysisResult>) {
                result.forEach { 
                    println(it.resolution.name)
                    println(it.folderId)
                }
            }
            override fun onError(error: OzException) {
                error.printStackTrace()
            }
        })
} 

private void analyzeMedia(List<OzAbstractMedia> mediaList) {
    File refFile = new File(context.getFilesDir(), "reference.jpg");
    OzAbstractMedia refMedia = new OzAbstractMedia.OzDocumentPhoto(
            OzMediaTag.PhotoIdFront , // OzMediaTag.PhotoSelfie for a non-ID photo
            refFile.getAbsolutePath()
    );
    ArrayList<OzAbstractMedia> mediaWithReferencePhoto = new ArrayList<>(mediaList);
    mediaWithReferencePhoto.add(refMedia);
    new AnalysisRequest.Builder()
            .addAnalysis(new Analysis(Analysis.Type.QUALITY, Analysis.Mode.SERVER_BASED, mediaList, Collections.emptyMap()))
            .addAnalysis(new Analysis(Analysis.Type.BIOMETRY, Analysis.Mode.SERVER_BASED, mediaWithReferencePhoto, Collections.emptyMap()))
            .build()
            .run(new AnalysisRequest.AnalysisListener() {
                @Override public void onStatusChange(@NonNull AnalysisRequest.AnalysisStatus analysisStatus) {}
                @Override
                public void onSuccess(@NonNull List<OzAnalysisResult> list) {
                    String folderId = list.get(0).getFolderId();
                }
                @Override
                public void onError(@NonNull OzException e) { e.printStackTrace(); }
    });
}

For on-device analyses, you can change the analysis mode from Analysis.Mode.SERVER_BASED to Analysis.Mode.ON_DEVICE

Check also the Android sample app source code.

Adding Face Matching to iOS SDK

For the purpose of this guide, it is assumed that your reference photo (e.g., front side of an ID) is stored on the device as reference.jpg.

Modify the code that runs the analysis as follows:

let imageURL = URL(fileURLWithPath: NSTemporaryDirectory())
    .appendingPathComponent("reference.jpg")

let refMedia = OZMedia.init(movement: .selfie,
                   mediaType: .movement,
                   metaData: nil,
                   videoURL: nil,
                   bestShotURL: imageUrl,
                   preferredMediaURL: nil,
                   timestamp: Date())
   
var mediaBiometry = [OZMedia]()
mediaBiometry.append(refMedia)
mediaBiometry.append(contentsOf: mediaToAnalyze)
let analysisRequest = AnalysisRequestBuilder()
let analysisBiometry = Analysis.init(media: mediaBiometry, type: .biometry, mode: .serverBased)
let analysisQuality = Analysis.init(media: mediaToAnalyze, type: .quality, mode: .serverBased)
analysisRequest.addAnalysis(analysisBiometry)
analysisRequest.addAnalysis(analysisQuality)
analysisRequest.uploadMedia(mediaBiometry)
analysisRequest.run(
    scenarioStateHandler: { state in }, // scenario steps progress handler
    uploadProgressHandler: { (progress) in } // file upload progress handler
) { (analysisResults : [OzAnalysisResult], error) in
    // receive and handle analyses results here
    for result in analysisResults {
        print(result.resolution)
        print(result.folderID)
    }
}

For on-device analyses, you can change the analysis mode from mode: .serverBased to mode: .onDevice

Check also the iOS sample app source code.

Final notes for all SDKs

You will be able to access your media and analysis results in Web UI via browser or programmatically via API.

Oz API methods as well as Mobile and Web SDK methods can be combined with great flexibility. Explore the options available in the Developer Guide section.

This guide outlines the steps for integrating the Oz Liveness Web SDK into a customer web application for capturing facial videos and subsequently analyzing them on a server.

The SDK implements the ready-to-use face capture user interface that is essential for seamless customer experience and accurate liveness results. Under the hood, it communicates with Oz API.

Oz Liveness Web SDK detects both presentation and injection attacks. An injection attack is an attempt to feed pre-recorded video into the system using a virtual camera.

Finally, while the cloud-based service provides the fully-fledged functionality, we also offer an on-premise version with the same functions but no need for sending any data to our cloud. We recommend starting with the SaaS mode and then reconnecting your web app to the on-premise Web Adapter and Oz API to ensure seamless integration between your front end and back end. With these guidelines in mind, integrating the Oz Liveness Web SDK into your web application can be a simple and straightforward process.

1. Get your Web Adapter

Tell us domain names of the pages from which you are going to call Web SDK and email for admin access, e.g.:

2. Add Web Plugin to your web pages

Add the following tags to your HTML code. Use Web Adapter URL received before:

<script src="https://<web-adapter-url>/plugin_liveness.php"></script>

3. Implement your logic around Web Plugin

Add the code that opens the plugin and handles the results:

OzLiveness.open({
  lang: 'en',
  action: [
    // 'photo_id_front', // request photo ID picture
    'video_selfie_blank' // request passive liveness video
  ],
  on_complete: function (result) {
    // This callback is invoked when the analysis is complete
    console.log('on_complete', result);
  }
});

• Customizing plugin look-and-feel

• Adding custom language pack

• Tuning plugin behavior

• Plugin parameters and callbacks

• Security recommendations

For Angular and React, replace https://web-sdk.sandbox.ohio.ozforensics.com in index.html.

Oz API is the most important component of the system. It makes sure all other components are connected with each other. Oz API:

• provides the unified Rest API interface to run the Liveness and Biometry analyses

• processes authorization and user permissions management

• tracks and records requested orders and analyses to the database

• archives the inbound media files

• collects telemetry from connected mobile apps

• provides settings for specific device models

• generates reports with analyses results

Description of the Rest API scheme:

In this section, you will find the description of both API and SDK components of Oz Forensics Liveness and face biometric system. API is the backend component of the system, it is needed for all the system modules to interact with each other. SDK is the frontend component that is used to:

1) take videos or images which are then processed via API,

2) display results.

We provide two versions of API.

With full version, we provide you with all functionality of Oz API.

The Lite version is a simple and lightweight version with only the necessary functions included.

The SDK component consists of web SDK and mobile SDK.

Web SDK is a plugin that you can embed into your website page and the adapter for this plugin.

Mobile SDK is SDK for iOS and Android.

This guide describes how to match a liveness video with a reference photo of a person that is already stored in your database.

However, if you prefer to include a photo ID capture step to your liveness process instead of using a stored photo, then you can refer to in this section.

By this time you should have already implemented liveness video recording and liveness check. If not, please refer to these guides:

In this scenario, you upload your reference image to the same folder where you have a liveness video, initiate the BIOMETRY analysis, and poll for the results.

1. Get folder_id

Given that you already have the liveness video recorded and uploaded, you will be working with the same Oz API folder where your liveness video is. Obtain the folder ID as described below, and pass it to your back end.

• For a video recorded by Android or iOS SDK, retrieve the folder_id from the analysis’ results as shown below:

Android:

AnalysisRequest.Builder()
        ...
        .run(object : AnalysisRequest.AnalysisListener {
            override fun onSuccess(result: List<OzAnalysisResult>) {
                // save folder_id that is needed for the next step
                val folderId = result.firstOrNull()?.folderId
            }
            ...
        })

private void analyzeMedia(List<OzAbstractMedia> mediaList) {
    new AnalysisRequest.Builder()
            ...
            .run(new AnalysisRequest.AnalysisListener() {
                @Override public void onStatusChange(@NonNull AnalysisRequest.AnalysisStatus analysisStatus) {}
                @Override
                public void onSuccess(@NonNull List<OzAnalysisResult> list) {
                    String folderId = list.get(0).getFolderId();
                    }
                }
                ...
    });
}

iOS:

analysisRequest.run(
scenarioStateHandler: { state in }, 
uploadProgressHandler: { (progress) in }  
)   { (analysisResults : [OzAnalysisResult], error) in 
        // save folder_id that is needed for the next step
        let folderID = analysisResults.first?.folderID
    }
}

2. Upload your reference photo

Set the appropriate tags in the payload field of the request, depending on the nature of a reference photo that you have.

{
  "media:tags": { 
    "photo1": [
        "photo_id", "photo_id_front" // for the front side of an ID
        // OR
        "photo_selfie" // for a non-ID photo
    ]
  }
}

3. Initiate the analysis

{
    "analyses": [
        {
            "type": "biometry"
        }
    ]
}

4. Poll for the results

• get the qualitative result from resolution (SUCCESS or DECLINED).

• get the quantitative results from analyses.results_data.min_confidence

Here is the Postman collection for this guide.

With these steps completed, you are done with adding face matching via Oz API. You will be able to access your media and analysis results in Web UI via browser or programmatically via API.

The "Best shot" algorithm is intended to choose the most high-quality and well-tuned frame with a face from a video record. This algorithm works as a part of the liveness analysis, so here, we describe only the best shot part.

Processing steps

1. Initiate the analysis similar to Liveness, but make sure that the "extract_best_shot" is set to True as shown below:

{
  "analyses": [{
    "type": "quality",
    "source_media": ["1111aaaa-11aa-11aa-11aa-111111aaaaaa"], // // optional; omit to include all media from the folder
    "params" : {
      "extract_best_shot": true // the mandatory part for the best shot analysis
    }
  }]
}

If you want to use a webhook for response, add it to the payload at this step, as described here.

2. Check and interpret results in the same way as for the pure Liveness analysis.

3. The URL to the best shot is located in the results_media -> output_images -> original_url response.

The Biometry algorithm is intended to compare two or more photos and detect the level of similarity of the spotted faces. As a source media, the algorithm takes photos, videos, and documents (with photos).

Requirements

1. You're authorized.

2. You have already created a folder and added your media marked by correct tags into this folder.

Processing steps

1. Initiate the analysis for the folder: POST /api/folders/{{folder_id}}/analyses/

If you want to use a webhook for response, add it to the payload at this step, as described here.

{
  "analyses": [{
    "type": "biometry",
    "source_media": ["1111aaaa-11aa-11aa-11aa-111111aaaaaa"], // // optional; omit to include all media from the folder
  }]
}

You'll needanalyse_id or folder_id from response.

2. If you use a webhook, just wait for it to return the information needed. Otherwise, initiate polling:

• GET /api/analyses/{{analyse_id}} – for the analyse_id you have from the previous step.

• GET /api/folders/{{folder_id}} – for all analyses performed on media in the folder with the folder_id you have from the previous step.

Repeat until the resolution_status and resolution fields change status to any other except PROCESSING, and treat this as a result.

Check the response for the min_confidence value. It is a quantitative result of matching the people on the media uploaded.

[
  {
    // you may have multiple analyses in the list
    // pick the one you need by analyse_id or type
    "analyse_id": "1111aaaa-11aa-11aa-11aa-111111aaaaaa",
    "type": "BIOMETRY",
    "results_media": [
      {
        // if you have multiple media in one analysis, match score with media by source_video_id/source_shots_set_id 
        "source_video_id": "1111aaaa-11aa-11aa-11aa-111111aaaaab", // for shots_set media, the key would be source_shots_set_id 
        "results_data": 
        {
          "max_confidence": 0.997926354, 
          "min_confidence": 0.997926354 // quantitative score for this media
        }
      ...
    ]
    "resolution_status": "SUCCESS", // qualitative resolution (based on all media)
    ...
  }
  ...
]

To launch one or more analyses for your media files, you need to create a folder via Oz API (or use an existing folder) and put the files into this folder. Each file should be marked by tags: they describe what's pictured in a media and determine the applicable analyses.

To create a folder and upload media to it, call POST /api/folders/

To add files to the existing folder, call POST /api/folders/{{folder_id}}/media/

Add the files to the request body; tags should be specified in the payload.

Here's the example of the payload for a passive Liveness video and ID front side photo.

{
    "media:tags": { // this section sets the tags for the media files that you upload
    // media files are referenced by the keys in a multipart form
        "video1": [ // your file key
        // a typical set of tags for a passive Liveness video
            "video_selfie", // video of a person
            "video_selfie_blank", // no gesture used
            "orientation_portrait" // video orientation
        ],
        "photo1": [
        // a typical set of tags for an ID front side
            "photo_id",
            "photo_id_front"
        ]
    }
}

An example of usage (Postman):

The successful response will return the folder data.

Getting an Access Token

To get an access token, call POST /api/authorize/auth/ with credentials (which you've got from us) containing the email and password needed in the request body. The host address should be the API address (the one you've also got from us).

{
	"credentials": {
		"email": "{{user_email}}", // your login
		"password": "{{user_password}}" // your password
	}
}

The successful response will return a pair of tokens:access_token and expire_token.

access_token is a key that grants you access to system resources. To access a resource, you need to add your access_token to the header.

headers = {‘ X-Forensic-Access-Token’: <access_token>}

access_token is time-limited, the limits depend on the account type.

• service accounts – OZ_SESSION_LONGLIVE_TTL (5 years by default),

• other accounts – OZ_SESSION_TTL (15 minutes by default).

expire_token is the token you can use to renew your access token if necessary.

Automatic session extension

If the value ofexpire_date > current date, the value of current sessionexpire_date is set to current date + time period that is defined as shown above (depending on the account type).

Token Renewal

To renewaccess_token and expire_token, call POST /api/authorize/refresh/. Add expire_token to the request body and X-Forensic-Access-Token to the header.

{
    "expire_token": "{{expire_token}}"
}

In case of success, you'll receive a new pair of access_token and expire_token. The "old" pair will be deleted upon the first authentication with the renewed tokens.

Errors

The blacklist check algorithm is designed to check the presence of a person using a database of preloaded photos. A video fragment and/or a photo can be used as a source for comparison.

Prerequisites:

1. You're authorized.

2. You have already created a folder and added your media marked by correct tags into this folder.

Processing steps:

1. Initiate the analysis: POST/api/folders/{{folder_id}}/analyses/

If you want to use a webhook for response, add it to the payload at this step, as described here.

{
  "analyses": [{
    "type": "collection",
    "source_media": ["1111aaaa-11aa-11aa-11aa-111111aaaaaa"], // // optional; omit to include all media from the folder
  }]
}

You'll needanalyse_id or folder_id from response.

2. If you use a webhook, just wait for it to return the information needed. Otherwise, initiate polling:

• GET /api/analyses/{{analyse_id}} – for the analyse_id you have from the previous step.

• GET /api/folders/{{folder_id}} – for all analyses performed on media in the folder with the folder_id you have from the previous step.

Wait for the resolution_status and resolution fields to change the status to anything other than PROCESSING and treat this as a result.

If you want to know which person from your collection matched with the media you have uploaded, find the collection analysis in the response, check results_media, and retrieve person_id. This is the ID of the person who matched with the person in your media. To get the information about this person, use GET /api/collections/{{collection_id}}/persons/{{person_id}} with IDs of your collection and person.

The webhook feature simplifies getting analyses' results. Instead of polling after the analyses are launched, add a webhook that will call your website once the results are ready.

When you create a folder, add the webhook endpoint (resolution_endpoint) into the payload section of your request body:

{    
  "resolution_endpoint": "address.com", // use address of your website here
    ... // other request details - folder etc.
}

You'll receive a notification each time the analyses are completed for this folder. The webhook request will contain information about the folder and its corresponding analyses.

This article describes how to create a collection via API, how to add persons and photos to this collection and how to delete them and the collection itself if you no longer need it. You can do the same in Web console, but this article covers API methods only.

Collection in Oz API is a database of facial photos that are used to compare with the face from the captured photo or video via the Black list analysis

Person represents a human in the collection. You can upload several photos for a single person.

How to Create a Collection

The collection should be created within a company, so you require your company's company_id as a prerequisite.

If you don't know your ID, callGET /api/companies/?search_text=test, replacing "test" with your company name or its part. Save the company_id you've received.

Now, create a collection via POST /api/collections/. In the request body, specify the alias for your collection and company_id of your company:

{
  "alias": "blacklist",
  "company_id": "your_company_id"
}

In a response, you'll get your new collection identifier: collection_id.

How to Add a Person or a Photo to a Collection

To add a new person to your collection, call POST /api/collections/{{collection_id}}/persons/, usingcollection_id of the collection needed. In the request body, add a photo or several photos. Mark them with appropriate tags in the payload:

{
    "media:tags": {
        "image1": [
            "photo_selfie",
            "orientation_portrait"
        ]
    }
}

The response will contain the person_id which stands for the person identifier within your collection.

If you want to add a name of the person, in the request payload, add it as metadata:

    "person:meta_data": {
        "person_info": {
            "first_name": "John",
            "middle_name": "Jameson",
            "last_name": "Doe"
        }
    },

To add more photos of the same person, call POST {{host}}/api/collections/{{collection_id}}/persons/{{person_id}}/images/ using the appropriate person_id. The request body should be filled as you did it before with POST /api/collections/{{collection_id}}/persons/.

To obtain information on all the persons within the single collection, call GET /api/collections/{{collection_id}}/persons/.

To obtain a list of photos for a single person, call GET /api/collections/{{collection_id}}/persons/{{person_id}}/images/. For each photo, the response will containperson_image_id. You'll need this ID, for instance, if you want to delete the photo.

How to Remove a Photo or a Person from a Collection

To delete a person with all their photos, call DELETE /api/collections/{{collection_id}}/persons/{{person_id}} with the appropriate collection and person identifiers. All the photos will be deleted automatically. However, you can't delete a person entity if it has any related analyses, which means the Black list analysis used this photo for comparison and found a coincidence. To delete such a person, you'll need to delete these analyses using DELETE /api/analyses/{{analyse_id}} with analyse_id of the collection (Black list) analysis.

To delete all the collection-related analyses, get a list of folders where the Black list analysis has been used: call GET /api/folders/?analyse.type=COLLECTION. For each folder from this list (GET /api/folders/{{folder_id}}/), find the analyse_id of the required analysis, and delete the analysis – DELETE /api/analyses/{{analyse_id}}.

To delete a single photo of a person, call DELETE /api/collections/{{collection_id}}/persons/{{person_id}}/images/{{person_image_id}} with collection, person, and image identifiers specified.

How to Delete a Collection

Delete the information on all the persons from this collection as described above, then call DELETE /api/collections/{{collection_id}}/ to delete the remaining collection data.

Using Oz API, you can perform one of the following analyses:

• biometry,

• quality (liveness, best shot),

• documents,

• blacklist.

Biometry

Purpose

The Biometry algorithm allows comparing several media and check if the people on them are the same person or not. As sources, you can use images, videos, and scans of documents (with photo). To perform the analysis, the algorithm requires at least two media (for details, please refer to Rules of Assigning Analyses).

Output

After comparison, the algorithm provides a number that represents the similarity level. The number varies from 100 to 0% (1 to 0), where:

• 100% (1) – faces are similar, media represent the same person,

• 0% (0) – faces are not similar and belong to different people

Quality (Liveness, Best Shot)

Purpose

The Liveness detection (Quality) algorithm aims to check whether a person in a media is a real human acting in good faith, not a fake of any kind.

The Best Shot algorithm checks for the best shot from a video (a best-quality frame where the face is seen the most properly). It is an addition to liveness.

Output

After checking, the analysis shows the chance of a spoofing attack in percents.

• 100% (1) – an attack is detected, the person in the video is not a real living person,

• 0% (0) – a person in the video is a real living person.

*Spoofing in biometry is a kind of scam when a person disguises as another person using both program and non-program tools like deepfake, masks, ready-made photos, or fake videos.

Documents

Purpose

The Documents analysis aims to recognize the document and check if its fields are correct according to its type.

Output

As an output, you'll get a list of document fields with recognition results for each field and a result of checking that can be:

• The documents passed the check successfully,

• The documents failed to pass the check.

Additionally, the result of Biometry check is displayed.

Blacklist

Purpose

The Blacklist checking algorithm is used to determine whether the person on a photo or video is present in the database of pre-uploaded images. This base can be used as a blacklist or whitelist. In the former case, the person's face is being compared with the faces of known swindlers; in the latter case, it might be a list of VIPs.

Output

After comparison, the algorithm provides a number that represents the similarity level. The number varies from 100 to 0% (1 to 0), where:

• 100% (1) – the person in an image or video matches with someone in the blacklist,

• 0% (0) – the person is not found in the blacklist.

Analyses in Oz system can be applied in two ways:

• manually, for instance, when you choose the Liveness scenario in our demo application;

• automatically, when you don’t choose anything and just assign all possible analyses (via API or SDK).

The automatic assignment means that Oz system decides itself what analyses to apply to media files based on its tags and type. If you upload files via the web console, you select the tags needed; if you take photo or video via Web SDK, the SDK picks the tags automatically. As for the media type, it can be IMAGE (a photo)/VIDEO/SHOTS_SET, where SHOTS_SET is a .zip archive equal to video.

Below, you will find the tags and type requirements for all analyses. If a media doesn’t match the requirements for the certain analysis, this media is ignored by algorithms.

The rules listed below act by default. To change the mapping configuration, please contact us.

Quality (Liveness)

This analysis is applied to all media, regardless of the gesture recorded (gesture tags begin from video_selfie).

Important: to process a photo in API 4.0.8 and below, pack it into a .zip archive, apply the SHOTS_SET type, and mark it with video_*. Otherwise, it will be ignored.

Biometry

This analysis is applied to all media.

If the folder contains less than two matching media files, the system will return an error. If there are more than two files, then all pairs will be compared, and the system will return a result for the pair with the least similar faces.

Blacklist

This analysis works only when you have a pre-made image database, which is called the blacklist. The analysis is applied to all media in the folder (or the ones marked as source media).

Best Shot

Best Shot is an addition to the Quality (Liveness) analysis. It requires the appropriate option enabled. The analysis is applied to all media files that can be processed by the Quality analysis.

Documents

The Documents analysis is applied to images with tags photo_id_front and photo_id_back (documents), and photo_selfie (selfie). The result will be positive if the system finds the selfie photo and matches it with a photo on one of the valid documents from the following list:

• personal ID card

• driver license

• foreign passport

Tag-Related Errors

HTTP Response Codes

• Response codes 2XX indicate a successfully processed request (e.g., code 200 for retrieving data, code 201 for adding a new entity, code 204 for deletion, etc.).

• Response codes 4XX indicate that a request could not be processed correctly because of some client-side data issues (e.g., 404 when addressing a non-existing resource).

• Response codes 5XX indicate that an internal server-side error occurred during the request processing (e.g., when database is temporarily unavailable).

Response Body with Errors

Each response error includes HTTP code and JSON data with error description. It has the following structure:

• error_code – integer error code;

• error_message– text error description;

• details – additional error details (format is specified to each case). Can be empty.

Sample error response:

{
    "error_code": 0,
    "error_message": "Unknown server side error occurred",
    "details": null
}

Error codes:

• 0 – UNKNOWN Unknown server error.

• 1 - NOT ALLOWED An unallowed method is called. Usually is followed by the 405 HTTP status of response. For example, trying to request the PATCH method, while only GET/POST ones are supported.

• 2 - NOT REALIZED The method is documented but is not realized by any temporary or permanent reason.

• 3 - INVALID STRUCTURE Incorrect structure of request. Some required fields missing or a format validation error occurred.

• 4 - INVALID VALUE Incorrect value of the parameter inside request body or query.

• 5 - INVALID TYPE The invalid data type of the request parameter.

• 6 - AUTH NOT PROVIDED Access token not specified.

• 7 - AUTH INVALID The access token does not exist in the database.

• 8 - AUTH EXPIRED Auth token is expired.

• 9 - AUTH FORBIDDEN Access denied for the current user.

• 10 - NOT EXIST the requested resource is not found (alternative of HTTP status_code = 404).

• 11 - EXTERNAL SERVICE Error in the external information system.

• 12 – DATABASE Critical database error on the server host.

Oz API Lite is the lightweight yet powerful version of Oz API. The Lite version is less resource-demanding, more productive, and easier to work with. The analyses are made within the API Lite image. As Oz API Lite doesn't include any additional services like statistics or data storage, this version is the one to use when you need a high performance.

Examples of methods

To check the Liveness processor, call GET /v1/face/liveness/health.

To check the Biometry processor, call GET /v1/face/pattern/health.

To perform the liveness check for an image, call POST /v1/face/liveness/detect (it takes an image as an input and displays the evaluation of spoofing attack chance in this image)

To compare two faces in two images, call POST /v1/face/pattern/extract_and_compare (it takes two images as an input, derives the biometry templates from these images, and compares them).

To compare an image with a bunch of images, call POST /v1/face/pattern/extract_and_compare_n.

For the full list of Oz API Lite methods, please refer to API Methods.

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.

OzLivenessSDK.init(context,
    listOf(
        LicenseSource.LicenseAssetId(R.raw.your_license_name),
        LicenseSource.LicenseFilePath("absolute_path_to_your_license_file")
    ),
    object : StatusListener<LicensePayload> {
        override fun onSuccess(result: LicensePayload) { /*check the license payload*/ }
        override fun onError(error: OzException) { /*handle the exception */ }
    }
  )

OzLivenessSDK.INSTANCE.getConfig().setBaseURL(BASE_URL);
OzLivenessSDK.INSTANCE.init(context,
    Arrays.asList(
        new LicenseSource.LicenseAssetId(R.raw.forensics),
        new LicenseSource.LicenseFilePath("absolute_path_to_your_license_file")
    ),
    new StatusListener<LicensePayload>() {
        @Override public void onStatusChanged(@Nullable String s) {}
        @Override public void onSuccess(LicensePayload licensePayload) { /*check the license payload*/ }
        @Override public void onError(@NonNull OzException e) { /*handle the exception */ }
    }
);

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.

Possible License Errors

Since Android and iOS 8.0.0, we have introduced the hybrid Liveness analysis mode. It is a combination of the on-device and server-based analyses that sums up the benefits of these two modes. If the on-device analysis is uncertain about the real human presence, the system initiates the server-based analysis, otherwise, no additional analyses are done.

Benefits of the Hybrid Liveness

• You need less computational capacity: in the majority of cases there's no need to apply the server-side analyses and fewer requests are being sent back and forth. On Android, only 8-9% of analyses require an additional server check, on iOS, it's 4.5-5.5%.

• The accuracy is similar to the one of the server-based analysis: if the on-device analysis result is uncertain, the server analysis is launched. We offer the hybrid analysis as one of the default analysis modes, but you can also implement your own logic of hybrid analysis by combining the server-based and on-device analyses in your code.

• Since the 8.3.0 release, you get the analysis result faster, and less data will be transmitted (by up to 10 times): the on-device analysis is enough in the majority of cases so that you don’t need to upload the full video to analyze it on the server, and, therefore, don’t send or receive the additional data. The customer journey gets shorter.

How to Enable Hybrid Liveness

The hybrid analysis has been available in our native (mobile) SDKs since 8.0.0. As we mentioned before, the server-based analysis is launched in the minority of cases, as if the analysis on your device has finished with a certain answer, there’s no need for a second check. This results in less server resources involved.

To enable hybrid mode on Android, when you launch the analysis, set Mode to HYBRID. To do the same on iOS, you need to set mode to hybrid. That’s all, as easy as falling off a log.

If you have any questions left, we’ll be happy to answer them.

This article describes the main types of analyses that Oz software is able to perform.

• Liveness checks whether a person in a media is a real human.

• Face Matching examines two or more media to identify similarities between the faces depicted in them.

• Black list looks for resemblances between an individual featured in a media and individuals in a pre-existing photo database.

These analyses are accessible in the Oz API for both SaaS and On-Premise models. Liveness and Face Matching are also offered in the On-Device model. Please visit this page to learn more about the usage models.

Liveness

The Liveness check is important to protect facial recognition from the two types of attacks.

A presentation attack, also known as a spoofing attack, refers to the attempt of an individual to deceive a facial recognition system by presenting into a camera video, photo, or any other type of media that mimics the appearance of a genuine user. These attacks can include the use of realistic masks or make up.

An injection attack is an attempt to deceive a facial recognition system by replacing physical camera input with a prerecorded image or video, manipulating physical camera output before it becomes input to a facial recognition, or injectiong some malicious code. Virtual camera software is the most common tool for injection attacks.

Oz Liveness is able to detect both types of attacks. Any component can detect presentation attacks, and for injection attack detection, use Oz Liveness SDK. To learn about how to use Oz components to prevent attacks, check our integration quick start guides:

• How to integrate server-based liveness into your web application,

• How to integrate server-based liveness into your mobile application,

• How to check your media for liveness without Oz front end.

Once the Liveness check is finished, you can check both qualitative and quantitative analysis results.

Asking users to perform a gesture, such as smiling or turning their head, is a popular requirement when recording a Liveness video. With Oz Liveness Mobile and Web SDK, you can also request gestures from users. However, our Liveness check relies on other factors, analyzed by neural networks, and does not depend on gestures. For more details, please check Passive and Active Liveness.

Liveness check also can return the best shot from a video: a best-quality frame where the face is seen the most properly.

Face Matching

The Biometry algorithm allows comparing several media and check if the people on them are the same person or not. As sources, you can use images, videos, and scans of documents (with photo). To perform the analysis, the algorithm requires at least two media.

Wonder how to integrate face matching into your processes? Check our integration quick start guides.

Black List

In Oz API, you can configure one or more black lists, or face collections. These collections are databases of people depicted in photos. When the Black list analysis is being conducted, Oz software compares the face in a photo or video taken with faces of this pre-made database and shows whether a face exists in a collection.

For additional information, please refer to this article.

To connect SDK to Oz API, specify the API URL and access token as shown below.

OzLivenessSDK.setApiConnection(OzConnection.fromServiceToken(host, token))

OzLivenessSDK.INSTANCE.setApiConnection(
        OzConnection.Companion.fromServiceToken(host, token), 
        null
);

Alternatively, you can use the login and password provided by your Oz Forensics account manager:

OzLivenessSDK.setApiConnection(
    OzConnection.fromCredentials(host, username, password),
    statusListener(
        { token -> /* token */ },
        { ex -> /* error */ }
    )
)

OzLivenessSDK.INSTANCE.setApiConnection(
        OzConnection.Companion.fromCredentials(host, username, password),
        new StatusListener<String>() {
            @Override
            public void onStatusChanged(@Nullable String s) {}
            @Override
            public void onSuccess(String token) { /* token */ }
            @Override
            public void onError(@NonNull OzException e) { /* error */ }
        }
);

Although, the preferred option is authentication via access token – for security reasons.

By default, logs are saved along with the analyses' data. If you need to keep the logs distinct from the analysis data, set up the separate connection for telemetry as shown below:

OzLivenessSDK.setEventsConnection(
    OzConnection.fromCredentials(
        "https://tm.ozforensics.com/",
        "<your_telemetry_user_eg_tm@company.com>",
        "your_telemetry_password"
    )
)

OzLivenessSDK.setEventsConnection(
        OzConnection.fromCredentials(
                "https://tm.ozforensics.com/",
                "<your_telemetry_user_eg_tm@company.com>",
                "your_telemetry_password"
        )
);

Clearing authorization:

OzLivenessSDK.setApiConnection(null)

OzLivenessSDK.INSTANCE.setApiConnection(null, null);

Other Methods

Check for the presence of the saved Oz API access token:

val isLoggedIn = OzLivenessSDK.isLoggedIn

boolean isLoggedIn = OzLivenessSDK.INSTANCE.isLoggedIn();

LogOut:

OzLivenessSDK.logout()

OzLivenessSDK.INSTANCE.logout();

We offer different usage models for the Oz software to meet your specific needs. You can either utilize the software as a service from one of our cloud instances or integrate it into your existing infrastructure. Regardless of the usage model you choose, all Oz modules will function equally. It’s only up to you what to pick, depending on your needs.

When to Choose SaaS

With the SaaS model, you can access one of our clouds without having to install our software in your own infrastructure.

Choose SaaS when you want:

• Faster start as you don’t need to procure or allocate hardware within your company and set up a new instance.

• Zero infrastructure cost as server components are located in Oz cloud.

• Lower maintenance cost as Oz maintains and upgrades server components.

• No cross-border data transfer for the regions where Oz has cloud instances.

When to Choose On-Premise

The on-premise model implies that all the Oz components required are installed within your infrastructure. Choose on-premise for:

• Your data not leaving your infrastructure.

• Full and detailed control over the configuration.

When to Choose On-Device

We also provide an opportunity of using the on-device Liveness and Face matching. This model is available in Mobile SDKs.

Consider the on-device option when:

• You can’t transmit facial images to any server due to privacy concerns

• The network conditions whereon you plan using Oz products are extremely poor.

The choice is yours to make, but we're always available to provide assistance.

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.

Here’s an example of performing a check:

analysisCancelable = AnalysisRequest.Builder()
 // mediaToAnalyze is an array of OzAbstractMedia that were captured or otherwise created 
    .addAnalysis(Analysis(Analysis.Type.QUALITY, Analysis.Mode.SERVER_BASED, mediaToAnalyze))// or ON_DEVICE if you want the on-device analysis
    .build()
//initiating the analyses and setting up a listener
    .run(object : AnalysisRequest.AnalysisListener {
        override fun onStatusChange(status: AnalysisRequest.AnalysisStatus) { handleStatus(status) // or your status handler
        }
        override fun onSuccess(result: RequestResult) {
            handleResults(result) // or your result handler
        }
        override fun onError(error: OzException) { handleError(error) // or your error handler 
        }
    })

analysisCancelable = new AnalysisRequest.Builder()
// mediaToAnalyze is an array of OzAbstractMedia that were captured or otherwise created 
        .addAnalysis(new Analysis(Analysis.Type.QUALITY, Analysis.Mode.SERVER_BASED, mediaToAnalyze)) // or ON_DEVICE if you want the on-device analysis
        .build()
//initiating the analyses and setting up a listener
        .run(new AnalysisRequest.AnalysisListener() { 
            @Override
            public void onSuccess(@NonNull RequestResult list) { handleResults(list); } // or your result handler
            @Override
            public void onError(@NonNull OzException e) { handleError(e); } // or your error handler
            @Override
            public void onStatusChange(@NonNull AnalysisRequest.AnalysisStatus analysisStatus) { handleStatus(analysisStatus); } // or your status handler
        })

To delete media files after the checks are finished, use the clearActionVideos method.

Adding Metadata

To add metadata to a folder, use the addFolderMeta method.

    .addFolderMeta(
        mapOf(
            "key1" to "value1",
            "key2" to "value2"
        )
    )

.addFolderMeta(Collections.singletonMap("key", "value")) 

Extracting the Best Shot

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.

mapOf("extract_best_shot" to true)

Using Media from Another SDK

To use a media file that is captured with another SDK (not Oz Android SDK), specify the path to it in OzAbstractMedia:

       val file = File(context.filesDir, "media.mp4") // use context.getExternalFilesDir(null) instead of context.filesDir for external app storage
       val media = OzAbsractMedia.OzVideo(OzMediaTag.VideoSelfieSmile, file.absolutePath)

Adding Media to a Certain Folder

If you want to add your media to the existing folder, use the setFolderId method:

    .setFolderId(folderId)

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.

OzLivenessSDK.config.customization = UICustomization(
    // customization parameters for the toolbar
    toolbarCustomization = ToolbarCustomization(
        closeIconTint = Color.ColorHex("#FFFFFF"),
        backgroundColor = Color.ColorHex("#000000"),
        backgroundAlpha = 100,
    ),
    // customization parameters for the center hint
    centerHintCustomization = CenterHintCustomization(
        verticalPosition = 70
    ),
    // customization parameters for the hint animation
    new HintAnimation(
        hideAnimation = true
    ),
    // customization parameters for the frame around the user face
    faceFrameCustomization = FaceFrameCustomization(
        strokeDefaultColor = Color.ColorHex("#EC574B"),
        strokeFaceInFrameColor = Color.ColorHex("#00FF00"),
        strokeWidth = 6,
    ),
    // customization parameters for the background outside the frame
    backgroundCustomization = BackgroundCustomization(
        backgroundAlpha = 100
    ),
)

OzLivenessSDK.INSTANCE.getConfig().setCustomization(new UICustomization(
// customization parameters for the toolbar
new ToolbarCustomization(
    R.drawable.ib_close,
    new Color.ColorHex("#FFFFFF"),
    new Color.ColorHex("#000000"),
    100, // toolbar text opacity (in %)
    ),
// customization parameters for the center hint
new CenterHintCustomization(
    70, // vertical position (in %)
),
// customization parameters for the hint animation
new HintAnimation(
    true, // hide animation
),
// customization parameters for the frame around the user face
new FaceFrameCustomization(     
    new Color.ColorHex("#EC574B"), 
    new Color.ColorHex("#00FF00"),
    6, // frame stroke width (in dp)
 ),
// customization parameters for the background outside the frame
new BackgroundCustomization(
    100 // background opacity (in %)
),
  )
);

Download and install the Postman client from this page. Then download the JSON file needed:

Oz API Postman collections

5.3 and 5.2

5.0

Oz API 5.1.0 works with the same collection.

4.0

3.33

How to Import a Postman Collection:

Launch the client and import Oz API collection for Postman by clicking the Import button:

Click files, locate the JSON needed, and hit Open to add it:

The collection will be imported and will appear in the Postman interface:

To start using Oz Android SDK, follow the steps below.

1. Embed Oz Android SDK into your project as described here.

2. Get a trial license for SDK on our website or a production license by email. We'll need your application id. Add the license to your project as described here.

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

4. Capture videos using methods described here. You'll send them for analysis afterward.

5. Analyze media you've taken at the previous step. The process of checking liveness and face biometry is described here.

6. If you want to customize the look-and-feel of Oz Android SDK, please refer to this section.

Resources

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.

What Are Tags for

To work properly, the resolution algorithms need each uploaded media to be marked with special tags. For video and images, the tags are different. They help algorithms to identify what should be in the photo or video and analyze the content.

Tags for Video Files

The following tag types should be specified in the system for video files.

• To identify the data type of the video:

  • video_selfie

• To identify the orientation of the video:

  • orientation_portrait – portrait orientation;

  • orientation_landscape – landscape orientation.

• To identify the action on the video:

  • video_selfie_left – head turn to the left;

  • video_selfie_right – head turn to the right;

  • video_selfie_down – head tilt downwards;

  • video_selfie_high – head raise up;

  • video_selfie_smile – smile;

  • video_selfie_eyes – blink;

  • video_selfie_scan – scanning;

  • video_selfie_oneshot – a one-frame analysis;

  • video_selfie_blank – no action.

Important: in API 4.0.8 and below, to launch the Quality analysis for a photo, pack the image into a .zip archive, apply the SHOTS_SET type, and mark it with video_*. Otherwise, it will be ignored by algorithms.

Example of the correct tag set for a video file with the “blink” action:

"video1": [
  "video_selfie",
  "video_selfie_eyes",
  "orientation_portrait"
]

Tags for Photo Files

The following tag types should be specified in the system for photo files:

• A tag for selfies:

  • photo_selfie – to identify the image type as “selfie”.

• Tags for photos/scans of ID cards:

  • photo_id – to identify the image type as “ID”;

  • photo_id_front – for the photo of the ID front side;

Important: in API 4.0.8 and below, to launch the Quality analysis for a photo, pack the image into a .zip archive, apply the SHOTS_SET type, and mark it with video_*. Otherwise, it will be ignored by algorithms.

Example of the correct tag set for a “selfie” photo file:

"photo1": [
  "photo_selfie"
]

Example of the correct tag set for a photo file with the face side of an ID card:

"photo1": [
  "photo_id",
  "photo_id_front"
]

Example of the correct set of tags for a photo file of the back of an ID card:

"photo1": [
  "photo_id",
  "photo_id_back"
]

Download and install the Postman client from this page. Then download the JSON file needed:

1.2.0

1.1.1

How to Import a Postman Collection:

Launch the client and import Oz API Lite collection for Postman by clicking the Import button:

Click files, locate the JSON needed, and hit Open to add it:

The collection will be imported and will appear in the Postman interface:

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.

The Oz API is a comprehensive Rest API that enables facial biometrics, allowing for both face matching and liveness checks. This write-up provides an overview of the essential concepts that one should keep in mind while using the Oz API.

Authentication, Roles, and Access Management

To ensure security, every Oz API call requires an access token in its HTTP headers. To obtain this token, execute the POST /api/authorize/auth method with login and password provided by us. Pass this token in X-Forensics-Access-Token header in subsequent Oz API calls.

This article provides comprehensive details on the authentication process. Kindly refer to it for further information.

Furthermore, the Oz API offers distinct user roles, ranging from CLIENT, who can perform checks and access reports but lacks administrative rights, e.g., deleting folders, to ADMIN, who enjoys nearly unrestricted access to all system objects. For additional information, please consult this guide.

Persistence

The unit of work in Oz API is a folder: you can upload interrelated media to a folder, run analyses on them, and check for the aggregated result. A folder can contain the unlimited number of media, and each of the media can be a target of several analyses. Also, analyses can be performed on a bunch of media.

Media Types and Tags

Media OZ API works with photos and videos. Video can be either a regular video container, e.g., MP4 or MOV, or a ZIP archive with a sequence of images. Oz API uses the file mime type to define whether media is an image, a video, or a shot set.

It is also important to determine the semantics of a content, e.g., if an image is a photo of a document or a selfie of a person. This is achieved by using tags. The selection of tags impacts whether specific types of analyses will recognize or ignore particular media files. The most important tags are:

• photo_id_front – for the front side of a photo ID

• photo_selfie – for a non-document reference photo

• video_selfie_blank – for a liveness video recorded beyond Oz Liveness SDK

• if a media file is captured using the Oz Liveness SDK, the tags are assigned automatically.

The full list of Oz media tags with their explanation and examples can be found here.

Asynchronous analyses

Since video analysis may take a few seconds, the analyses are performed asynchronously. This implies that you initiate an analysis (/api/folders/{{folder_id}}/analyses/) and then monitor the outcomes by polling until processing is complete (/api/analyses/{{analyse_id}} for a single analysis or /api/folders/{{folder_id}}/analyses/ for all folder’s analyses). Alternatively, there is a webhook option available. To see an example of how to use both the polling and webhook options, please check this guide.

These were the key concepts of Oz API. To gain a deeper understanding of its capabilities, please refer to the Oz API section of our developer guide.

This section contains the most common cases of integrating the Oz Forensics Liveness and face Biometry system.

The scenarios can be combined together, for example, integrating liveness into both web and mobile applications or integrating liveness with face matching.

Server-Based Liveness:

On-Device Liveness

Face Matching

Configuration

We recommend applying these settings when starting the app.

// connecting to the API server
OzLivenessSDK.setApiConnection(OzConnection.fromServiceToken(HOST, TOKEN))
// settings for the number of attempts to detect an action
OzLivenessSDK.config.attemptSettings = attemptSettings 
// the possibility to display additional debug information (you can do it by clicking the SDK version number)
OzLivenessSDK.config.allowDebugVisualization = allowDebugVisualization 
// logging settings
OzLivenessSDK.config.logging = ozLogging 

OzConfig config = OzLivenessSDK.INSTANCE.getConfig();
// connecting to the API server
OzLivenessSDK.setApiConnection(OzConnection.fromServiceToken(HOST, TOKEN));
// settings for the number of attempts to detect an action
config.setAttemptSettings(attemptSettings); 
// the possibility to display additional debug information (you can do it by clicking the SDK version number)
config.setAllowDebugVisualization(allowDebugVisualization); 
// logging settings
config.setLogging(ozLogging); 

Interface Customization

To customize the Oz Liveness interface, use UIcustomization as shown below. For the description of customization parameters, please refer to .

OzLivenessSDK.config.customization = UICustomization(
    // customization parameters for the toolbar
    toolbarCustomization = ToolbarCustomization(
        closeIconRes = R.drawable.ib_close,
        closeIconTint = Color.ColorRes(R.color.white),
        titleTextFont = R.font.roboto,
        titleTextSize = 18,
        titleTextAlpha = 100,
        titleTextColor = Color.ColorRes(R.color.white),
        backgroundColor = Color.ColorRes(R.color.black),
        backgroundAlpha = 60,
        isTitleCentered = true,
        title = "Analysis"
    ),
    // customization parameters for the center hint
   centerHintCustomization = CenterHintCustomization(
        textFont = R.font.roboto,
        textColor = Color.ColorRes(R.color.text_color),
        textSize = 20,
        verticalPosition = 50,
        textStyle = R.style.Sdk_Text_Primary,
        backgroundColor = Color.ColorRes(R.color.color_surface),
        backgroundOpacity = 56,
        backgroundCornerRadius = 14,
        textAlpha = 100
    ),
    // customization parameters for the hint animation
    hintAnimation = HintAnimation(
    hintGradientColor = Color.ColorRes(R.color.red),
    hintGradientOpacity = 80,
    animationIconSize = 120,
    hideAnimation = false
),
    // customization parameters for the frame around the user face
    faceFrameCustomization = FaceFrameCustomization(
        geometryType = GeometryType.Rectangle(10), // 10 is the corner radius
        strokeDefaultColor = Color.ColorRes(R.color.error_red),
        strokeFaceInFrameColor = Color.ColorRes(R.color.success_green),
        strokeAlpha = 100,
        strokeWidth = 5,
        strokePadding = 3,
    ),
    // customization parameters for the background outside the frame
    backgroundCustomization = BackgroundCustomization(
        backgroundColor = Color.ColorRes(R.color.black),
        backgroundAlpha = 60
    ),
    // customization parameters for the SDK version text
    versionTextCustomization = VersionTextCustomization(
        textFont = R.font.roboto,
        textSize = 12,
        textColor = Color.ColorRes(R.color.white),
        textAlpha = 100,
    ),
    // customization parameters for the antiscam protection text
    antiScamCustomization = AntiScamCustomization(
        textMessage = "",
        textFont = R.font.roboto,
        textSize = 14,
        textColor = Color.ColorRes(R.color.text_color),
        textAlpha = 100,
        backgroundColor = Color.ColorRes(R.color.color_surface),
        backgroundOpacity = 100,
        cornerRadius = 20,
        flashColor = Color.ColorRes(R.color.green)
    ),
    // custom logo parameters
    // should be allowed by license
    logoCustomization = LogoCustomization(
    image = Image.Drawable(R.drawable.ic_logo),
    size = Size(176, 64),
    )
)

OzLivenessSDK.INSTANCE.getConfig().setCustomization(new UICustomization(
// customization parameters for the toolbar
new ToolbarCustomization(
    R.drawable.ib_close,
    new Color.ColorRes(R.color.white),
    R.style.Sdk_Text_Primary,
    new Color.ColorRes(R.color.white),
    R.font.roboto,
    Typeface.NORMAL,
    100, // toolbar text opacity (in %)
    18, // toolbar text size (in sp)
    new Color.ColorRes(R.color.black),
    60, // toolbar alpha (in %)
    "Liveness", // toolbar title
    true // center toolbar title
    ),
// customization parameters for the center hint
new CenterHintCustomization(
    R.font.roboto,
    new Color.ColorRes(R.color.text_color),
    20,
    50,
    R.style.Sdk_Text_Primary,
    new Color.ColorRes(R.color.color_surface),
    100, // background opacity
    14, // corner radius for background frame   
    100 // text opacity
    ),
// customization parameters for the hint animation
new HintAnimation(
    new Color.ColorRes(R.color.red), // gradient color
    80, // gradient opacity (in %)
    120, // the side size of the animation icon square
    false // hide animation
    ),
// customization parameters for the frame around the user face
new FaceFrameCustomization(
    GeometryType.RECTANGLE,
    10, // frame corner radius (for GeometryType.RECTANGLE)
    new Color.ColorRes(R.color.error_red), 
    new Color.ColorRes(R.color.success_green),
    100, // frame stroke alpha (in %)
    5, // frame stroke width (in dp)
    3 // frame stroke padding (in dp)
    ),
// customization parameters for the background outside the frame
new BackgroundCustomization(
    new Color.ColorRes(R.color.black),
    60 // background alpha (in %)
    ),
 // customization parameters for the SDK version text
 new VersionTextCustomization(
     R.style.Sdk_Text_Primary,
     R.font.roboto,
     12, // version text size
     new Color.ColorRes(R.color.white),
     100 // version text alpha
     ),
 // customization parameters for the antiscam protection text
 new AntiScamCustomization(
    "Recording .. ",
    R.font.roboto,
    12,
    new Color.ColorRes(R.color.text_color),
    100,
    R.style.Sdk_Text_Primary,
    new Color.ColorRes(R.color.color_surface),
    100,
    14,
    new Color.ColorRes(R.color.green)
    )
// custom logo parameters
 new LogoCustomization(
    new Image.Drawable(R.drawable.ic_logo),
    new Size(176, 64)
    )
  )
);

By default, SDK uses the locale of the device. To switch the locale, use the code below:

OzLivenessSDK.config.localizationCode = OzLivenessSDK.OzLocalizationCode.EN

OzLivenessSDK.INSTANCE.getConfig().setLocalizationCode(OzLivenessSDK.OzLocalizationCode.EN)

Add the following URL to the build.gradle of the project:

allprojects {
  repositories {
    maven { url "https://ozforensics.jfrog.io/artifactory/main" }
  }
}

Add this to the build.gradle of the module (VERSION is the version you need to implement. Please refer to ):

for the server-based version only

Please note: this is the default version.

dependencies {
  implementation 'com.ozforensics.liveness:sdk:VERSION'
}

for both server-based and on-device versions

Please note: the resulting file will be larger.

dependencies {
implementation 'com.ozforensics.liveness:full:VERSION'
}

Also, regardless of the mode chosen, add:

android {
  compileOptions {
    sourceCompatibility JavaVersion.VERSION_1_8
    targetCompatibility JavaVersion.VERSION_1_8
  }
}

Oz API is a rich Rest API for facial biometry, where you can do liveness checks and face matching. Oz API features are:

• Persistence: your media and analysis are stored for future reference unless you explicitly delete it,

• Ability to work with videos as well as images,

• Asynchronous analyses,

• Authentication,

• Roles and access management.

The unit of work in Oz API is a folder: you can upload interrelated media to a folder, run analyses on them, and check for the aggregated result.

This step-by-step guide describes how to perform a liveness check on a facial image or video that you already have with Oz backend: create a folder, upload your media to this folder, initiate liveness check and poll for the results.

For better accuracy and user experience, we recommend that you use our Web and/or Native SDK on your front end for face capturing. Please refer to the relevant guides:

1. Get the access token

{
    "credentials": {
        "email": "<login>", // your admin access email
        "password": "<password>" // the password you’ve got from us
     }
}

Get the access_token from the response and add it to the X-Forensic-Access-Token of all subsequence requests.

2. Convert a single image to an archive (for API 4.0.8 and below)

This step is not needed for API 5.0.0 and above.

With API 4.0.8 and below, Oz API requires video or archived sequence of images in order to perform liveness check. If you want to analyze a single image, you need to transform it into a ZIP archive. Oz API will treat this archive as a video.

Make sure that you use corresponding video-related tags later on.

3. Upload media to a folder

In the payload field, set the appropriate tags:

{
    "media:tags": {
        "video1": [
            "video_selfie",
            "video_selfie_blank",
            "orientation_portrait"
        ],
    }
}

The successful response will return code 201 and the folder_id you’ll need later on.

4. Initiate the analysis

{
    "analyses": [
        {
            "type": "quality"
        }
    ]
}

The results will be available in a short while. The method will return analyse_id that you’ll need at the next step.

5. Poll for the results

• get the qualitative result from resolution (SUCCESS or DECLINED).

• get the quantitative results from results_media[0].results_data.confidence_spoofing. confidence_spoofing ranges from 0.0 (real person) to 1.0 (spoofing).

Here is the Postman collection for this guide.

With these steps completed, you are done with Liveness check via Oz API. You will be able to access your media and analysis results in Web UI via browser or programmatically via API.

License

You can generate the trial license here or contact us by email 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.

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

2. During the runtime: when initializing SDK, use the following method.

OZSDK(licenseSources: [.licenseFileName(“forensics.license”)]) { licenseData, error in
      if let error = error {
        print(error)
      }
    }

or

OZSDK(licenseSources: [.licenseFilePath(“path_to_file”)]) { licenseData, error in
      if let error = error {
        print(error)
      }
    }

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.

Possible License Errors

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.

Generating Keys

This section describes the process of creating your private and public keys.

Creating a Private Key

To create a private key, run the commands below one by one.

openssl genpkey -algorithm RSA -outform DER -out privateKey.der -pkeyopt rsa_keygen_bits:2048
# for MacOS
base64 -i privateKey.der -o privateKey.txt
# for Linux 
base64 -w 0 privateKey.der > privateKey.txt

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:

The OpenSSL command specification: https://www.openssl.org/docs/man1.1.1/man1/openssl-pkcs8.html

Creating a Public Key

To create a public key, run this command.

openssl rsa -pubout -in privateKey.der -out publicKey.pub

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 Integration

SDK initialization:

OZSDK(licenseSources: [LicenseSource], masterLicenseSignature: String? = nil, completion: @escaping ((LicenseData?, LicenseError?) -> Void))

License setting:

setLicense(licenseSource: LicenseSource, masterLicenseSignature: String? = nil)

Prior to the SDK initializing, create a base64-encoded signature for the host app bundle_id using the private key.

Signature creation example:

private func getSignature() -> String? {
    let privateKeyBase64String = "the string copied from the privateKey.txt file"
    // with key example:
    // let privateKeyBase64String = "MIIEogIBAAKCAQEAvxpyONpif2AjXiiG8fs9pQkn5C9yfiP0lD95Z0UF84t0Ox1S5U1UuVE5kkTYYGvS2Wm7ykUEGuHhqt/PyOAxrrNkAGz3OcVTsvcqPmwcf4UNdYZmug6EnQ5ok9wxYARS0aYqJUdzUb4dKOYal6WpHZE4yLx08R0zQ5jPkg5asT2u2PLB7JHZNnXwBcvdUonAgocNzdakUbWTNHKMxjwdAvwdIICdIneLZ9nCqe1d0cx7JBIhLzSPu/DVRANF+DOsE9JM8DT/Snnjok2xXzqpxBs1GwqiMJh98KYP78AVRWFuq3qbq0hWpjbq+mWl8xa7UMv8WxVd4PvQkWVYq/ojJwIDAQABAoIBAEvkydXwTMu/N2yOdcEmAP5I25HQkgysZNZ3OtSbYdit2lQbui8cffg23MFNHA125L65Mf4LWK0AZenBhriE6NYzohRVMf28cxgQ9rLhppOyGH1DCgr79wiUj02hVe6G6Qkfj39Ml+yvrs7uS0NMZBQ89yspRNv4t8IxrsWXc8cNQr33fdArlZ021Z12u2wdamaagiFwTa6ZYcQ5OYl3d/xL+oAwf9ywHwRrVM2JksGCxrcLJ7JCOL6lLyjp8rRrIG4iZ1V8YDfUNHmwD4w1fl30H6ejA+Cy5qge7CBZK+hqKr+hOcfBfakfOtgcEbFq2L8DqHoSaTeY6n9wjPJiFrkCgYEA8fc/Cg+d0BN98aON80TNT+XLEZxXMH+8qdmJYe/LB2EckBj1N0en87OEhqMFm9BjYswGf/uO+q2kryEat1n3nejbENN9XaO36ahlXTpQ6gdHO3TuO+hnnUkXeUNgiGYs+1L8Ot6PuNykwL0BZ09U0iBVoawEjTAg9tLNfVW2upsCgYEAyi/75YFT3ApxfSf/9XR74a0aKrfGGlBppcGvxuhVUC2aW2fPEZGXo4qlEhP2tyVTfj78F2p0Fnf3NSyvLZAzSwKo4w8EyZfXn1RI4sM95kzIMhH3Gz8VxCZWKEgr7cKNU5Zhs8un/VFd9Mc0KyZfmVy4VrZ5JumgahBRzSn9zGUCgYA7TTt3/cfRvVU6qbkajBw9nrYcRNLhogzdG+GdzSVXU6eqcVN4DunMwoySatXvEC2rgxF8wGyUZ4ZbHaPsl/ImE3HNN+gb0Qo8C/d719UI5mvA2LGioRzz4XwNTkQUaeZQWlBTJUTYK8t9KVV0um6xaRdTnlMnP0p088lFFILKTQKBgDsR98selKyF1JBXPl2s8YCGfU2bsWIAukz2IG/BcyNgn2czFfkxCxd5qy5z7LGnUxRgPHBu5oml9PBxJKDwLzwsA8GKosBu/00KZ9zwY8ZECn0uaH5qWOacuLE+HK9zFq0kE1lfF65XtlaMWH5+0JFS2HxlBVJMEVTLfcquCPtNAoGAG6ytPm24AS1satPwlKnZODQEg0kc7d5S42jbt4X7lwICY/7gORSdbNS8OmrqYhP/8tDOAUtzPQ20fEt43/VA87bq88BVzoSp4GVQcSL44MzRBQHQwTVkoVnbCXSD9K9gZ71wii+m+8rZZ0EMdiTR3hsRXRuSmw4t8y3CuzlZ9k4="
    guard let data = Data(base64Encoded: privateKeyBase64String, options: [.ignoreUnknownCharacters]) else {
      return nil
    }
     
    let sizeInBits = data.count * 8
    let keyDict: [CFString: Any] = [
      kSecAttrKeyType: kSecAttrKeyTypeRSA,
      kSecAttrKeyClass: kSecAttrKeyClassPrivate,
      kSecAttrKeySizeInBits: NSNumber(value: sizeInBits)
    ]
     
    var error: Unmanaged<CFError>?
    guard let secKey = SecKeyCreateWithData(data as CFData, keyDict as CFDictionary, &error) else {
      return nil
    }
     
    guard let bundleID = Bundle.main.bundleIdentifier else {
      return nil
    }
    guard let signature = SecKeyCreateSignature(secKey,
                          .rsaSignatureMessagePKCS1v15SHA512,
                          Data(bundleID.utf8) as CFData,
                          &error) else {
      return nil
    }
    return (signature as Data).base64EncodedString()
  }

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.

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:

1. Go to the folder for the locale needed, or create a new folder. Proceed to this guide for the details.

2. Create the file called strings.xml.

3. Copy the strings from the attached file to your freshly created file.

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

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.

Generating Keys

This section describes the process of creating your private and public keys.

Creating a Private Key

To create a private key, run the commands below one by one.

openssl genpkey -algorithm RSA -outform DER -out privateKey.der -pkeyopt rsa_keygen_bits:2048
# for MacOS
base64 -i privateKey.der -o privateKey.txt
# for Linux 
base64 -w 0 privateKey.der > privateKey.txt

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:

The OpenSSL command specification: https://www.openssl.org/docs/man1.1.1/man1/openssl-pkcs8.html

Creating a Public Key

To create a public key, run this command.

openssl rsa -pubout -in privateKey.der -out publicKey.pub

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 Integration

SDK initialization:

fun init(
    context: Context,
    licenseSources: List<LicenseSource>,
    masterLicenseSignature: String,
    statusListener: StatusListener<LicensePayload>? = null,
)

Prior to the SDK initializing, create a base64-encoded signature for the host app bundle_id using the private key.

Signature creation example:

private fun getMasterSignature(): String {
    Security.insertProviderAt(org.spongycastle.jce.provider.BouncyCastleProvider(), 1)

    val privateKeyBase64String = "the string copied from the privateKey.txt file"
    // with key example:
    // val privateKeyBase64String = "MIIEpAIBAAKCAQEAxnpv02nNR34uNS0yLRK1o7Za2hs4Rr0s1V1/e1JZpCaK8o5/3uGV+qiaTbKqU6x1tTrlXwE2BRzZJLLQdTfBL/rzqVLQC/n+kAmvsqtHMTUqKquSybSTY/zAxqHF3Fk59Cqisr/KQamPh2tmg3Gu61rr9gU1rOglnuqt7FioNMCMvjW7ciPv+jiawLxaPrzNiApLqHVN+xCFh6LLb4YlGRaNUXlOgnoLGWSQEsLwBZFkDJDSLTJheNVn9oa3PXg4OIlJIPlYVKzIDDcSTNKdzM6opkS5d+86yjI1aTKEH3Zs64+QoEuoDfXUxS3TOUFx8P+wfjOR5tYAT+7TRN4ocwIDAQABAoIBAATWJPV05ZCxbXTURh29D/oOToZ0FVn78CS+44Vgy1hprAcfG9SVkK8L/r6X9PiXAkNJTR+Uivly64Oua8//bNC7f8aHgxRXojFmWwayj8iOMBncFnad1N2h4hy1AnpNHlFp3I8Yh1g0RpAZOOVJFucbTxaup9Ev0wLdWyGgQ3ENmRXAyLU5iUDwUSXg59RCBFKcmsMT2GmmJt1BU4P3lL9KVyLBktqeDWR/l5K5y8pPo6K7m9NaOkynpZo+mHVoOTCtmTj5TC/MH9YRHlF15VxQgBbZXuBPxlYoQCsMDEcZlMBWNw3cNR6VBmGiwHIc/tzSHZVsbY0VRCYEbxhCBZkCgYEA+Uz0VYKnIWViQF2Na6LFuqlfljZlkOvdpU4puYTCdlfpKNT3txYzO0T00HHY9YG9k1AW78YxQwsopOXDCmCqMoRqlbn1SBe6v49pVB85fPYU2+L+lftpPlx6Wa0xcgzwOBZonHb4kvp1tWhUH+B5t27gnvRz/rx5jV2EfmWinycCgYEAy8/aklZcgoXWf93N/0EZcfzQo90LfftkKonpzEyxSzqCw7B9fHY68q/j9HoP4xgJXUKbx1Fa8Wccc0DSoXsSiQFrLhnT8pE2s1ZWvPaUqyT5iOZOW6R+giFSLPWEdwm6+BeFoPQQFHf8XH3Z2QoAepPrEPiDoGN1GSIXcCwoe9UCgYEAgoKj4uQsJJKT1ghj0bZ79xVWQigmEbE47qI1u7Zhq1yoZkTfjcykc2HNHBaNszEBks45w7qo7WU5GOJjsdobH6kst0eLvfsWO9STGoPiL6YQE3EJQHFGjmwRbUL7AK7/Tw2EJG0wApn150s/xxRYBAyasPxegTwgEj6j7xu7/78CgYEAxbkI52zG5I0o0fWBcf9ayx2j30SDcJ3gx+/xlBRW74986pGeu48LkwMWV8fO/9YCx6nl7JC9dHI+xIT/kk8OZUGuFBRUbP95nLPHBB0Hj50YRDqBjCBh5qaizSEGeGFFNIfFSKddri3U8nnZTNiKLGCx7E3bjE7QfCh5qoX8ZF0CgYAtsEPTNKWZKA23qTFI+XAg/cVZpbSjvbHDSE8QB6X8iaKJFXbmIC0LV5tQO/KT4sK8g40m2N9JWUnaryTiXClaUGU3KnSlBdkIA+I77VvMKMGSg+uf4OdfJvvcs4hZTqZRdTm3dez8rsUdiW1cX/iI/dJxF4964YIFR65wL+SoRg=="
    val sig = Signature.getInstance("SHA512WithRSA")
    val keySpec = PKCS8EncodedKeySpec(Base64.decode(privateKeyBase64String, Base64.DEFAULT))
    val keyFactory = KeyFactory.getInstance("RSA")
    sig.initSign(keyFactory.generatePrivate(keySpec))
    sig.update(packageName.toByteArray(Charsets.UTF_8))
    return Base64.encodeToString(sig.sign(), Base64.DEFAULT).replace("\n", "")
}

KohJ1rsUgLMzZHpHGAZDK2efHPnMj9tw9VIedBLvyZt0B2JH3SWfJLJ8X6JNz3bR2sce6PR2wdEIFln0r1pUnD+6WBCgexKIHAv7esiRVQZoZOEANDBwDvJVv73H/0qL2LGlhxKzbBg5CxGPClTBQdLo1P+7HsTXHHG/Hf6m3rdu1OUeGXVPoaS2NzE8kiRH6gb8Nhr7PBLTUeMKTeLoiX13hvwjOqhV1ANhgS97T4hC2+ZilZt4RektgRY/+fGmWnOqErNeYuz/WSInfaJS0YEWhJW3gXKPjdCzNGIBIqbxaFSjU46wu/alh2+tBRFnrYFl1dRQVcTlW0VwwZHcug==

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.

The Liveness detection algorithm is intended to detect a real living person in a media.

Requirements

1. You're authorized.

2. You have already created a folder and added your media marked by correct tags into this folder. For API 4.0.8 and below, please note: the Liveness analysis works with videos and shotsets, images are ignored. If you want to analyze an image, upload it as a shotset (archive) with a single image and mark with the video_selfie_blank tag.

Processing Steps

1. Initiate the analysis for the folder: POST /api/folders/{{folder_id}}/analyses/

If you want to use a webhook for response, add it to the payload at this step, as described here.

{  
  "analyses": [
    {
      "type": "quality",
      "source_media": ["1111aaaa-11aa-11aa-11aa-111111aaaaaa"], // optional; omit to include all media from the folder
      ...
    }
  ]
}

You'll needanalyse_id or folder_id from response.

2. If you use a webhook, just wait for it to return the information needed. Otherwise, initiate polling:

• GET /api/analyses/{{analyse_id}} – for the analyse_id you have from the previous step.

• GET api/folders/{{folder_id}}/analyses/ – for all analyses performed on media in the folder with the folder_id you have from the previous step.

Repeat the check until theresolution_status and resolution fields change status to any other except PROCESSING and treat this as a result.

For the Liveness Analysis, seek the confidence_spoofing value related to the video you need. It indicates a chance that a person is not a real one.

[
  {
    // you may have multiple analyses in the list
    // pick the one you need by analyse_id or type
    "analyse_id": "1111aaaa-11aa-11aa-11aa-111111aaaaaa",
    "type": "QUALITY",
    "results_media": [
      {
        // if you have multiple media in one analysis, match score with media by source_video_id/source_shots_set_id 
        "source_video_id": "1111aaaa-11aa-11aa-11aa-111111aaaaab", // for shots_set media, the key would be source_shots_set_id 
        "results_data": 
        {
          "confidence_spoofing": 0.05790174 // quantitative score for this media
        }
      "resolution_status": "SUCCESS", // qualitative resolution (based on all media)
      ...
    ]
    ...
  }
  ...
]

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.

// customization parameters for the toolbar
let toolbarCustomization = ToolbarCustomization(
   closeButtonColor: .white,
   backgroundColor: .black)

// customization parameters for the center hint
let centerHintCustomization = CenterHintCustomization(
   verticalPosition: 70)
   
// customization parameters for the center hint animation
let hintAnimationCustomization = HintAnimationCustomization(
    hideAnimation: true)

// customization parameters for the frame around the user face
let faceFrameCustomization = FaceFrameCustomization(
   strokeWidth: 6,
   strokeFaceAlignedColor: .green,
   strokeFaceNotAlignedColor: .red)

// customization parameters for the background outside the frame
let backgroundCustomization = BackgroundCustomization(
   backgroundColor: .clear)

OZSDK.customization = OZCustomization(toolbarCustomization: toolbarCustomization,
   centerHintCustomization: centerHintCustomization,
   hintAnimationCustomization: hintAnimationCustomization,
   faceFrameCustomization: faceFrameCustomization,
   versionCustomization: vesrionCustomization,
   backgroundCustomization: backgroundCustomization)

To connect SDK to Oz API, specify the API URL and access token as shown below.

OZSDK.setApiConnection(Connection.fromServiceToken(host: "https://sandbox.ohio.ozforensics.com", token: token)) { (token, error) in
}

Alternatively, you can use the login and password provided by your Oz Forensics account manager:

OZSDK.setApiConnection(Connection.fromCredentials(host: “https://sandbox.ohio.ozforensics.com”, login: login, password: p)) { (token, error) in
    // Your code to handle error or token
}

By default, logs are saved along with the analyses' data. If you need to keep the logs distinct from the analysis data, set up the separate connection for telemetry as shown below:

let eventsConnection = Connection.fromCredentials(host: https://tm.ozforensics.com/,
                                login: <your_telemetry_user_eg_tm@company.com>,
                                password: your_telemetry_password)
OZSDK.setEventsConnection(eventsConnection) { (token, error) in
}

Create a controller that will capture videos as follows:

let actions: [OZVerificationMovement] = [.selfie]
let ozLivenessVC: UIViewController = OZSDK.createVerificationVCWithDelegate(self, actions: actions)
self.present(ozLivenessVC, animated: true)

action – a list of user’s actions while capturing the video.

Once video is captured, the system calls the onOZLivenessResult method:

extension viewController: OZLivenessDelegate {
 func onError(status: OZVerificationStatus?) {
        // show error
   }
 }
 func onOZLivenessResult(results: [OZMedia]) {
   // proceed to the checks step
 }
}

The method returns the results of video capturing: the [OZMedia] objects. The system uses these objects to perform checks.

If a user closes the capturing screen manually, the failedBecauseUserCancelled error appears.

To customize the Oz Liveness interface, use OZCustomization as shown below. For the description of customization parameters, please refer to iOS SDK Methods and Properties.

// customization parameters for the toolbar
let toolbarCustomization = ToolbarCustomization(
   closeButtonIcon: UIImage(named: "example"),
   closeButtonColor: .black.withAlphaComponent(0.8),
   titleText: "",
   titleFont: .systemFont(ofSize: 18, weight: .regular),
   titleColor: .gray,
   backgroundColor: .lightGray)

// customization parameters for the center hint
let centerHintCustomization = CenterHintCustomization(
   textColor: .white,
   textFont: .systemFont(ofSize: 22, weight: .regular),
   verticalPosition: 42,
   backgroundColor: UIColor.init(hexRGBA: "1C1C1E8F")!,
   hideTextBackground: false,
   backgroundCornerRadius: 14)
   
// customization parameters for the center hint animation
let hintAnimationCustomization = HintAnimationCustomization(
    hideAnimation: false,
    animationIconSize: 80,
    toFrameGradientColor: UIColor.red)

// customization parameters for the frame around the user face
let faceFrameCustomization = FaceFrameCustomization(
   strokeWidth: 4,
   strokeFaceAlignedColor: .green,
   strokeFaceNotAlignedColor: .red,
   geometryType: .rect(cornerRadius: 10),
   strokePadding: 3)

// customization parameters for the SDK version text
let versionCustomization = VersionLabelCustomization(
   textFont: .systemFont(ofSize: 12, weight: .regular),
   textColor: .gray
)

// customization parameters for the background outside the frame
let backgroundCustomization = BackgroundCustomization(
   backgroundColor: .lightGray
)

// customization parameters for the antiscam protection text
let antiscamCustomization: AntiscamCustomization = AntiscamCustomization(
  customizationEnableAntiscam: false,
  customizationAntiscamTextMessage: "Face recognition",
  customizationAntiscamTextFont: UIFont.systemFont(ofSize: 15, weight: .semibold),
  customizationAntiscamTextColor: UIColor.black,
  customizationAntiscamBackgroundColor: UIColor.init(hexRGBA: "F2F2F7FF")!,
  customizationAntiscamCornerRadius: 18,
  customizationAntiscamFlashColor: UIColor.init(hexRGBA: "FF453AFF")!)

// customization parameters for your logo
// should be allowed by license
let logoCustomization = LogoCustomization(image: UIImage(), size: CGSize(width: 100, height: 100))

OZSDK.customization = Customization(toolbarCustomization: toolbarCustomization,
                   antiscamCustomization: antiscamCustomization,
                   centerHintCustomization: centerHintCustomization,
                   hintAnimationCustomization: hintAnimationCustomization,
                   faceFrameCustomization: faceFrameCustomization,
                   versionCustomization: vesrionCustomization,
                   backgroundCustomization: backgroundCustomization,
                  logoCustomization: logoCustomization)

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.

Below, you'll see the example of performing a check and its description.

let analysisRequest = AnalysisRequestBuilder()
// create one or more analyses
let analysis = Analysis.init(
	media: mediaToAnalyze, // mediaToAnalyze is an array of OzMedia that were captured or otherwise created
	type: .quality, // check the analysis types in iOS methods
	mode: .serverBased) // or .onDevice if you want the on-device analysis
analysisRequest.uploadMedia(mediaToAnalyze)
analysisRequest.addAnalysis(analysis)
// initiate the analyses
analysisRequest.run(
	statusHandler: { state in }, // scenario steps progress handler
	errorHandler: { _ in }  
) { result in
    // receive and handle analyses results here 
}

To delete media files after the checks are finished, use the cleanTempDirectory method.

Adding Metadata

To add metadata to a folder, use AnalysisRequest.addFolderMeta.

let analysis = Analysis.init(media: mediaToAnalyze, type: .quality, mode: .serverBased)
var folderMeta: [String: Any] = ["key1": "value1"]
analysisRequest.addFolderMeta(folderMeta)
...

Extracting the Best Shot

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.

let analysis = Analysis.init(media: mediaToAnalyze, type: .quality, mode: .serverBased, params: [“extract_best_shot” : true])

Using Media from Another SDK

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

let referenceMedia = OZMedia.init(movement: .selfie,
                  mediaType: .movement,
                  metaData: ["meta":"data"],
                  videoURL: nil,
                  bestShotURL: imageUrl,
                  preferredMediaURL: nil,
                  timestamp: Date())

Adding Media to a Certain Folder

If you want to add your media to the existing folder, use the addFolderId method:

let analysis = Analysis.init(media: mediaToAnalyze, type: .quality, mode: .serverBased)
analysisRequest.addFolderId(IdRequired)

CocoaPods

To integrate OZLivenessSDK into an Xcode project via the CocoaPods dependency manager, add the following code to Podfile:

pod 'OZLivenessSDK', :git => 'https://gitlab.com/oz-forensics/oz-liveness-ios', :tag => 'VERSION'

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:

// for the latest version
pod ‘OZLivenessSDK’
// OR, for the specific version
// pod ‘OZLivenessSDK’, ‘8.10.0’

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:

pod 'OZLivenessSDK/Core', :git => 'https://gitlab.com/oz-forensics/oz-liveness-ios.git',  :tag => 'VERSION'

For 8.1.0 and higher:

pod ‘OZLivenessSDK/Core’
// OR
// pod ‘OZLivenessSDK/Core’, ‘8.1.0’

SPM

Please note: installation via SPM is available for versions 8.7.0 and above.

Add the following package dependencies via SPM: https://gitlab.com/oz-forensics/oz-mobile-ios-sdk (if you need a guide on adding the package dependencies, please refer to the Apple documentation). OzLivenessSDK is mandatory. If you don't need the on-device analyses, skip the OzLivenessSDKOnDevice file.

Manual Installation

You can also add the necessary frameworks to your project manually.

1. Download the SDK files from here and add them to your project.

• OZLivenessSDK.xcframework,

• OZLivenessSDKResources.bundle,

• OZLivenessSDKOnDeviceResources.bundle (if you don't need the on-device analyses, skip this file).

1. Download the TensorFlow framework 2.11 from here.

2. Make sure that:

• both xcframework are in Target-Build Phases -> Link Binary With Libraries and Target-General -> Frameworks, Libraries, and Embedded Context;

• the bundle file(s) are in Target-Build Phases -> Copy Bundle Resources.

In this section, there's a guide for the integration of the on-device liveness check.

To start using Oz iOS SDK, follow the steps below.

1. Embed Oz iOS SDK into your project as described here.

2. Get a trial license for SDK on our website or a production license by email. We'll need your bundle id. Add the license to your project as described here.

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

4. Capture videos by creating the controller as described here. You'll send them for analysis afterwards.

5. Upload and analyze media you've taken at the previous step. The process of checking liveness and face biometry is described here.

6. If you want to customize the look-and-feel of Oz iOS SDK, please refer to this section.

Resources

Minimal iOS version: 11.

Minimal Xcode version: 15 for versions 8.10.0 and newer.

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.

In this section, we listed the guides for the face matching checks.

When you perform an analysis, the result you get is a number. For biometry, it reflects a chance that the two or more people represented in your media are the same person. For liveness, it shows a chance of deepfake or a spoofing attack: that the person in uploaded media is not a real one. You can get these numbers via API from a JSON response.

1. .

2. Make a request to the or to get a JSON response. Set the with_analyses parameter to True.

3. For the Biometry analysis, check the response for the min_confidence value:

"items": 
 [
  {
   "analyses": 
    [
     {
      "analyse_id": "biometry_analysis_id"
      "folder_id": "some_folder_id", 
      "type": "BIOMETRY", 
      "state": "FINISHED", 
      "results_data": 
       {
        "max_confidence": 0.997926354, 
        "min_confidence": 0.997926354
       }

This value is a quantitative result of matching the people on the media uploaded.

4. For the Liveness Analysis, seek the confidence_spoofing value related to the video you need:

"items": 
 [
  {
   "analyses": 
    [
     {
      "source_media": 
       [
        {
        "media_id": "your_media_id", 
        "media_type": "VIDEO_FOLDER",
        }
       ]
      "results_media": 
       [
        "analyse_id": "liveness_analysis_id",
        "results_data": 
         {
          "confidence_spoofing": 0.55790174
         }

This value is a chance that a person is not a real one.

To process a bunch of analysis results, you can parse the appropriate JSON response.

Liveness is checking that a person on a video is a real living person.

Biometry compares two or more faces from different media files and shows whether the faces belong to the same person or not.

Best shot is an addition to the Liveness check. The system chooses the best frame from a video and saves it as a picture for later use.

Blacklist checks whether a face on a photo or a video matches with one of the faces in the pre-created database.

The Quantitative Results section explains where and how to find the numeric results of analyses.

To learn what each analysis means, please refer to .

Objects Hierarchy

System objects on Oz Forensics products are hierarchically structured as shown in the picture below.

On the top level, there is a Company. You can use one copy of Oz API to work with several companies.

Object parameters

Common parameters

Besides these parameters, each object type has specific ones.

Company

User

Folder