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

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.

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.

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.

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.

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.

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:

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

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.

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.

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.

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.

Asynchronous analyses

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

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.

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.

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

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

For security reasons, we recommend obtaining the access token instead of using the credentials. Call POST /api/authorize/auth with your login and password in the request body.

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

Omit this step 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

To create a folder and upload your media into it, call POST /api/folders/, adding the media you need to the body part of the request.

In the payload field, set the appropriate tags:

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

4. Initiate the analysis

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

5. Poll for the results

Repeat calling GET /api/analyses/{{analysis_id}} with the analysis_id from the previous step once a second until the state changes from PROCESSING to something else. For a finished analysis:

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

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

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.

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

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.

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.

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 */ }
        }
);

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

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
}

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:

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

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

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:

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

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

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.

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

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

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.

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

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.

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

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.

Android

1. Add SDK to your project

In the build.gradle of your project, add:

In the build.gradle of the module, add:

2. Initialize SDK

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

3. Add face recording

To start recording, use startActivityForResult:

To obtain the captured video, use onActivityResult:

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

iOS

1. Add our SDK to your project

2. Initialize SDK

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

3. Add face recording

Create a controller that will capture videos as follows:

The delegate object must implement OZLivenessDelegate protocol:

4. Run analyses

Use AnalysisRequestBuilder to initiate the Liveness analysis.

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.

Processing steps

3. The URL to the best shot is located in the results_media -> output_images -> original_url 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.

In API 6.0, we've implemented new analysis modes:

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.

An example of usage (Postman):

The successful response will return the folder data.

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

Requirements

Processing Steps

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

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

You'll needanalysis_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/{{analysis_id}} – for the analysis_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
    "analysis_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)
      ...
    ]
    ...
  }
  ...
]

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 (for example, in 6.0, the database size for 100 000 orders with analyses is ~4 GB),

• archives the inbound media files,

• collects telemetry from connected mobile apps,

• provides settings for specific device models,

• generates reports with analyses' results.

In API 6.0, we introduced two new operation modes: Instant API and single request.

In the Instant API mode – also known as non-persistent – no data is stored at any point. You send a request, receive the result, and can be confident that nothing is saved. This mode is ideal for handling sensitive data and helps ensure GDPR compliance. Additionally, it reduces storage requirements on your side.

Single request mode allows you to send all media along with the analysis request in one call and receive the results in the same response. This removes the need for multiple API calls – one is sufficient. However, if needed, you can still use the multi-request mode.

Please note: the database

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

Processing steps

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

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

You'll needanalysis_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/{{analysis_id}} – for the analysis_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
    "analysis_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)
    ...
  }
  ...
]

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:

Processing steps:

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

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

You'll needanalysis_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/{{analysis_id}} – for the analysis_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.

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

{
    "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/{{analysis_id}} with analysis_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 analysis_id of the required analysis, and delete the analysis – DELETE /api/analyses/{{analysis_id}}.

To delete a single photo of a person, call DELETE collections/<collection_id>/persons/<person_id>/images/<media_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.

Overview and Benefits

In version 6.0.1, we introduced a new feature which allows you to send all required data and receive the analysis result within a single request.

However, the new API operation mode significantly simplifies the process by allowing you to send a single request and receive the response synchronously. The key benefits are:

• Single request for everything – all data is sent in one package, eliminating the risk of data loss.

• Synchronous response – no need for polling or webhooks to retrieve results.

• High performance – supports up to 36 analyses per minute per instance.

Usage

Response Example

In response, you receive analysis results.

You're done.

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

Biometry

Purpose

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.

Each of the new API users should obtain a role to define access restrictions for direct API connections. Set the role in the user_type field when you create a new user.

• ADMIN is a system administrator, who has unlimited access to all system objects, but can't change the analyses' statuses;

• CLIENT is a regular consumer account, who can upload media files, process analyses, view results in personal folders, generate reports for analyses.
• CLIENT ADMIN is a company administrator that can manage their company account and users within it. Additionally, CLIENT ADMIN can view and edit data of all users within their company, delete files in folders, add or delete report templates with or without attachments, the reports themselves and single analyses, check statistics, add new blacklist collections.

• CLIENT OPERATOR is similar to OPERATOR within their company.

• CLIENT SERVICE is a service user account for automatic connection purposes. Authentication with this user creates a long-live access token (5 years by default). The token lifetime for regular uses is 15 minutes by default (parameterized) and, also by default, the lifetime of a token is extended with each request (parameterized).

Here's the detailed information on access levels.

Company

Folder

Report template

Report template attachments

Report

Analysis

Collection

Person

Person image

User

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

Media

Analysis

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

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.

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.

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.

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

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

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.

2. Make a request to the folder or folder list 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:

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:

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.

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
}