Android SDK Methods and Properties

OzLivenessSDK

A singleton for Oz SDK.

clearActionVideos

Deletes all action videos from file system.

Parameters

-

Returns

-

createStartIntent

Creates an intent to start the Liveness activity.

Parameter

Type

Description

actions

A list of possible actions

Returns

-

getErrorFromIntent

Utility function to get the SDK error from OnActivityResult's intent.

Parameter

Type

Description

data

Intent

The object to test

Returns

The error text – String.

getLicensePayload

Retrieves the SDK license payload.

Parameters

-

Returns

The license payload (LicensePayload) – the object that contains the extended info about licensing conditions.

getResultFromIntent

Utility function to get SDK results from OnActivityResult's intent.

Parameter

Type

Description

data

Intent

The object to test

Returns

A list of OzAbstractMedia objects.

init

Initializes SDK with license sources.

Parameter

Type

Description

context

Context

The Context class

licenseSources

A list of license references

statusListener

StatusListener

Optional listener to check the license load result

Returns

-

log

Enables logging using the Oz Liveness SDK logging mechanism.

Parameter

Type

Description

tag

String

Message tag

log

String

Message log

Returns

-

setApiConnection

Connection to API.

Parameter

Type

Description

connection

Connection type

statusListener

StatusListener<String?>

Listener

setEventsConnection

Connection to the telemetry server.

Parameter

Type

Description

connection

Connection type

statusListener

StatusListener<String?>

Listener

logout

Deletes the saved token.

Parameters

-

Returns

-

getEventSessionId

Retrieves the telemetry session ID.

Parameters

-

Returns

The telemetry session ID (String parameter).

version

Retrieves the SDK version.

Parameters

-

Returns

The SDK version (String parameter).

AnalysisRequest

A class for performing checks.

run

The analysis launching method.

Parameter

Type

Description

onStatusChange

A callback function as follows:

onStatusChange(status: AnalysisRequest.AnalysisStatus) { handleStatus() }

The function is executed when the status of the AnalysisRequest changes.

onError

A callback function as follows:

onError(error: OzException) { handleError() }

The function is executed in case of errors.

onSuccess

A callback function as follows:

onSuccess(result: RequestResult) {

handleResults() }

The function is executed when all the analyses are completed.

class Builder

A builder class for AnalysisRequest.

build

Creates the AnalysisRequest instance.

Parameters

-

Returns

The AnalysisRequest class instance.

addAnalysis

Adds an analysis to your request.

Parameter

Type

Description

analysis

A structure for analysis

Returns

Error if any.

addAnalyses

Adds a list of analyses to your request. Allows executing several analyses for the same folder on the server side.

Parameter

Type

Description

analysis

A list of Analysis structures

Returns

Error if any.

addFolderMeta

Adds metadata to a folder you create (for the server-based analyses only). You can add a pair key-value as additional information to the folder with the analysis result on the server side.

Parameter

Type

Description

key

String

Key for metadata.

value

String

Value for metadata.

Returns

Error if any.

uploadMedia

Uploads one or more media to a folder.

Parameter

Type

Description

mediaList

An OzAbstractMedia object or a list of objects.

Returns

Error if any.

setFolderId

For the previously created folder, sets a folderId. The folder should exist on the server side. Otherwise, a new folder will be created.

Parameter

Type

Description

folderID

String

A folder identifier.

Returns

Error if any.

OzConfig

Configuration for OzLivenessSDK (use OzLivenessSDK.config).

setSelfieLength

Sets the length of the Selfie gesture (in milliseconds).

Parameter

Type

Description

selfieLength

Int

The length of the Selfie gesture (in milliseconds). Should be within 500-5000 ms, the default length is 700

Returns

Error if any.

allowDebugVisualization

The possibility to enable additional debug info by clicking on version text.

Parameter

Type

Description

allowDebugVisualization

Boolean

Enables or disables the debug info.

attemptSettings

The number of attempts before SDK returns error.

Parameter

Type

Description

attemptsSettings

Sets the number of attempts

uploadMediaSettings

Settings for repeated media upload.

Parameter

Type

Description

uploadMediaSettings

Sets the number of attempts and timeout between them

faceAlignmentTimeout

Timeout for face alignment (measured in milliseconds).

Parameter

Type

Description

faceAlignmentTimeout

Long

A timeout value

livenessErrorCallback

Interface implementation to retrieve error by Liveness detection.

Parameter

Type

Description

livenessErrorCallback

ErrorHandler

A callback value

localizationCode

Locale to display string resources.

Parameter

Type

Description

localizationCode

A locale code

logging

Logging settings.

Parameter

Type

Description

logging

Logging settings

useMainCamera

Uses the main (rear) camera instead of the front camera for liveness detection.

Parameter

Type

Description

useMainCamera

Boolean

True– rear camera, False– front camera

UICustomization

Customization for OzLivenessSDK (use OzLivenessSDK.config.customization).

hideStatusBar

Hides the status bar and the three buttons at the bottom. The default value is True.

toolbarCustomization

A set of customization parameters for the toolbar.

Parameter

Type

Description

closeIconRes

Int (@DrawableRes)

An image for the close button

closeIconTint

Close button color

titleTextFont

Int (@FontRes)

Toolbar title text font

titleTextFontStyle

Int (values from android.graphics.Typeface properties, e.g., Typeface.BOLD)

Toolbar title text font style

titleTextSize

Int

Toolbar title text size (in sp, 12-18)

titleTextAlpha

Int

Toolbar title text opacity (in %, 0-100)

titleTextColor

Toolbar title text color

backgroundColor

Toolbar background color

backgroundAlpha

Int

Toolbar background opacity (in %, 0-100)

isTitleCentered

Boolean

Defines whether the text on the toolbar is centered or not

title

String

Text on the toolbar

centerHintCustomization

A set of customization parameters for the center hint that guides a user through the process of taking an image of themselves.

Parameter

Type

Description

textFont

String

Center hint text font

textStyle

Int (values from android.graphics.Typeface properties, e.g.,Typeface.BOLD)

Center hint text style

textSize

Int

Center hint text size (in sp, 12-34)

textColor

Center hint text color

textAlpha

Int

Center hint text opacity (in %, 0-100)

verticalPosition

Int

Center hint vertical position from the screen bottom (in %, 0-100)

backgroundColor

Center hint background color

backgroundOpacity

Int

Center hint background opacity

backgroundCornerRadius

Int

Center hint background frame corner radius (in dp, 0-20)

hintAnimation

A set of customization parameters for the hint animation.

Parameter

Type

Description

hintGradientColor

Gradient color

hintGradientOpacity

Int

Gradient opacity

animationIconSize

Int

A side size of the animation icon square

hideAnimation

Boolean

A switcher for hint animation, if True, the animation is hidden

faceFrameCustomization

A set of customization parameters for the frame around the user face.

Parameter

Type

Description

geometryType

The frame type: oval, rectangle, circle, square

cornerRadius

Int

Rectangle corner radius (in dp, 0-20)

strokeDefaultColor

Frame color when a face is not aligned properly

strokeFaceInFrameColor

Frame color when a face is aligned properly

strokeAlpha

Int

Frame opacity (in %, 0-100)

strokeWidth

Int

Frame stroke width (in dp, 0-20)

strokePadding

Int

A padding from the stroke to the face alignment area (in dp, 0-10)

backgroundCustomization

A set of customization parameters for the background outside the frame.

Parameter

Type

Description

backgroundColor

Background color

backgroundAlpha

Int

Background opacity (in %, 0-100)

versionTextCustomization

A set of customization parameters for the SDK version text.

Parameter

Type

Description

textFont

Int (@FontRes)

SDK version text font

textSize

Int

SDK version text size (in sp, 12-16)

textColor

SDK version text color

textAlpha

Int

SDK version text opacity (in %, 20-100)

antiscamCustomization

A set of customization parameters for the antiscam message that warns user about their actions being recorded.

Parameter

Type

Description

textMessage

String

Antiscam message text

textFont

String

Antiscam message text font

textSize

Int

Antiscam message text size (in px, 12-18)

textColor

Antiscam message text color

textAlpha

Int

Antiscam message text opacity (in %, 0-100)

backgroundColor

Antiscam message background color

backgroundOpacity

Int

Antiscam message background opacity

cornerRadius

Int

Background frame corner radius (in px, 0-20)

flashColor

Color of the flashing indicator close to the antiscam message

logoCustomization

Logo customization parameters. Custom logo should be allowed by license.

Parameter

Type

Description

image

Bitmap (@DrawableRes)

Logo image

size

Size

Logo size (in dp)

Variables and Objects

enum OzAction

Contains the action from the captured video.

Case

Description

OneShot

The best shot from the video taken

Blank

A selfie with face alignment check

Scan

Scan

HeadRight

Head turned right

HeadLeft

Head turned left

HeadDown

Head tilted downwards

HeadUp

Head lifted up

EyeBlink

Blink

Smile

Smile

class LicensePayload

Contains the extended info about licensing conditions.

Parameter

Type

Description

expires

Float

The expiration interval

features

Features

License features

appIDS

[String]

An array of bundle IDs

sealed class OzAbstractMedia

A class for the captured media that can be:

OzDocumentPhoto

A document photo.

Parameter

Type

Description

tag

A tag for a document photo.

photoPath

String

An absolute path to a photo.

additionalTags (optional)

String

Additional tags if needed (including those not from the OzMediaTag enum).

OzShotSet

A set of shots in an archive.

Parameter

Type

Description

tag

A tag for a shot set

archivePath

String

A path to an archive

additionalTags (optional)

String

Additional tags if needed (including those not from the OzMediaTag enum)

OzVideo

A Liveness video.

Parameter

Type

Description

tag

A tag for a video

videoPath

String

A path to a video

bestShotPath (optional)

String

URL of the best shot in PNG

preferredMediaPath (optional)

String

URL of the API media container

additionalTags (optional)

String

Additional tags if needed (including those not from the OzMediaTag enum)

enum OzMediaTag

Contains an action from the captured video.

Case

Description

Blank

A video with no gesture

PhotoSelfie

A selfie photo

VideoSelfieOneShot

A video with the best shot taken

VideoSelfieScan

A video with the scanning gesture

VideoSelfieEyes

A video with the blink gesture

VideoSelfieSmile

A video with the smile gesture

VideoSelfieHigh

A video with the lifting head up gesture

VideoSelfieDown

A video with the tilting head downwards gesture

VideoSelfieRight

A video with the turning head right gesture

VideoSelfieLeft

A video with the turning head left gesture

PhotoIdPortrait

A photo from a document

PhotoIdBack

A photo of the back side of the document

PhotoIdFront

A photo of the front side of the document

sealed class LicenseSource

A class for license that can be:

LicenseAssetId

Contains the license ID.

Parameter

Type

Description

id

Int

License ID

LicenseFilePath

Contains the path to a license.

Parameter

Type

Description

path

String

An absolute path to a license

class AnalysisStatus

A class for analysis status that can be:

RunningAnalysis

This status means the analysis is launched.

Parameter

Type

Description

analysis

Contains information on what media to analyze and what analyses to apply.

UploadingMedia

This status means the media is being uploaded.

Parameter

Type

Description

media

The object that is being uploaded at the moment

index

Int

Number of this object in a list

from

Int

Objects quantity

percentage

Int

Completion percentage

enum Type

The type of the analysis.

Case

Description

BIOMETRY

The algorithm that allows comparing several media and check if the people on them are the same person or not

QUALITY

The algorithm that aims to check whether a person in a video is a real human acting in good faith, not a fake of any kind.

DOCUMENTS

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

Currently, the DOCUMENTS analysis can't be performed in the on-device mode.

enum Mode

The mode of the analysis.

Case

Description

ON_DEVICE

The on-device analysis with no server needed

SERVER_BASED

The server-based analysis

HYBRID

The hybrid analysis for Liveness: if the score received from an on-device analysis is too high, the system initiates a server-based analysis as an additional check.

class Analysis

Contains information on what media to analyze and what analyses to apply.

Parameter

Type

Description

type

Type

The type of the analysis

mode

Mode

The mode of the analysis

mediaList

An array of the OzAbstractMedia objects

params (optional)

Map<String, Any>

Additional parameters

sizeReductionStrategy

Defines what type of media is being sent to the server in case of the hybrid analysis once the on-device analysis is finished successfully

enum Resolution

The general status for all analyses applied to the folder created.

Case

Description

FAILED

One or more analyses failed due to some error and couldn't get finished

DECLINED

The check failed (e.g., faces don't match or some spoofing attack detected)

SUCCESS

Everything went fine, the check succeeded (e.g., faces match or liveness confirmed)

OPERATOR_REQUIRED

The result should be additionally checked by a human operator

class OzAttemptsSettings

Holder for attempts counts before SDK returns error.

Parameter

Type

Description

singleCount

Int

Attempts on a single action/gesture

commonCount

Int

Total number of attempts on all actions/gestures if you use a sequence of them

enum OzLocalizationCode

Contains the locale code according to ISO 639-1.

Case

Description

EN

English

HY

Armenian

KK

Kazakh

KY

Kyrgyz

TR

Turkish

ES

Spanish

PT-BR

Portuguese (Brazilian)

class OzLogging

Contains logging settings.

Parameter

Type

Description

allowDefaultLogging

Boolean

Allows logging to LogCat

allowFileLogging

Boolean

Allows logging to an internal file

journalObserver

StatusListener

An event listener to receive journal events on the application side

sealed class Color

A class for color that can be (depending on the value received):

ColorRes

Parameter

Type

Description

resId

Int

Link to the color in the Android resource system

ColorHex

Parameter

Type

Description

hex

String

Color hex (e.g., #FFFFFF)

ColorInt

Parameter

Type

Description

color

Int

The Int value of a color in Android

enum GeometryType

Frame shape settings.

Case

Description

Oval

Oval frame

Rectangle

Rectangular frame

Circle

Circular frame

Square

Square frame

class AnalysisError

Exception class for AnalysisRequest.

Parameter

Type

Description

apiErrorCode

Int

Error code

message

String

Error message

class SourceMedia

Structure that describes media used in AnalysisRequest.

Parameter

Type

Description

mediaId

String

Media identifier

mediaType

String

Type of the media

originalName

String

Original media name

ozMedia

Media object

tags

List<String>

Tags for media

class ResultMedia

Structure that describes the analysis result for the single media.

Parameter

Type

Description

confidenceScore

Float

Resulting score

isOnDevice

Boolean

Mode of the analysis

resolution

Consolidated analysis result

sourceMedia

Source media

type

Type of the analysis

class RequestResult

Consolidated result for all analyses performed.

Parameter

Type

Description

analysisResults

Analysis result

folderId

String

Folder identifier

resolution

Consolidated analysis result

class AnalysisResult

Result of the analysis for all media it was applied to.

Parameter

Type

Description

resolution

Consolidated analysis result

type

Type of the analysis

mode

Resulting score

resultMedia

A list of results of the analyses for single media

confidenceScore

Float

Resulting score

analysisId

String

Analysis identifier

params

@RawValue Map<String, Any>

Additional folder parameters

error

Error if any

serverRawResponse

String

Response from backend

class OzConnection

Defines the authentication method.

OzConnection.fromServiceToken

Authentication via token.

Parameter

Type

Description

host

String

API address

token

String

Access token

OzConnection.fromCredentials

Authentication via credentials.

Parameter

Type

Description

host

String

API address

username

String

User name

password

String

Password

class OzUploadMediaSettings

Defines the settings for the repeated media upload.

Parameter

Type

Description

attemptsCount

Int

Number of attempts for media upload

attemptsTimeout

Int

Timeout between attempts

enum SizeReductionStrategy

Defines what type of media is being sent to the server in case of the hybrid analysis once the on-device analysis is finished successfully. By default, the system uploads the compressed video.

Case

Description

UPLOAD_ORIGINAL

The original video

UPLOAD_COMPRESSED

The compressed video

UPLOAD_BEST_SHOT

The best shot taken from the video

UPLOAD_NOTHING

Nothing is sent (note that no folder will be created)

Error Description

Error Code

Error Message

Description

ERROR = 3

Error.

An unknown error has happened

ATTEMPTS_EXHAUSTED_ERROR = 4

Error. Attempts exhausted for liveness action.

The number of action attempts is exceeded

VIDEO_RECORD_ERROR = 5

Error by video record.

An error happened during video recording

NO_ACTIONS_ERROR = 6

Error. OzLivenessSDK started without actions.

No actions found in a video

FORCE_CLOSED = 7

Error. Liveness activity is force closed from client application.

A user closed the Liveness screen during video recording

DEVICE_HAS_NO_FRONT_CAMERA = 8

Error. Device has not front camera.

No front camera found

DEVICE_HAS_NO_MAIN_CAMERA = 9

Error. Device has not main camera.

No rear camera found

DEVICE_CAMERA_CONFIGURATION_NOT_SUPPORTED = 10

Error. Device camera configuration is not supported.

Oz Liveness doesn't support the camera configuration of the device

FACE_ALIGNMENT_TIMEOUT = 12

Error. Face alignment timeout in OzLivenessSDK.config.faceAlignmentTimeout milliseconds

Time limit for the face alignment is exceeded

ERROR = 13

The check was interrupted by user

User has closed the screen during the Liveness check.

Last updated