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	OzAction	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	[LicenseSource]	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	OzConnection	Connection type
statusListener	StatusListener<String?>	Listener

setEventsConnection

Connection to the telemetry server.

Parameter	Type	Description
connection	OzConnection	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).

generateSignedPayload

Generates the payload with media signatures.

Parameter	Type	Description
media	OzAbstractMedia	An array of media files
folderMeta (optional)	[string:any]	Additional folder metadata

Returns

Payload to be sent along with media files that were used for generation.

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	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	[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	[OzAbstractMedia]	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	OzAttemptsSettings	Sets the number of attempts

uploadMediaSettings

Settings for repeated media upload.

Parameter	Type	Description
uploadMediaSettings	OzUploadMediaSettings	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	OzLocalizationCode	A locale code

logging

Logging settings.

Parameter	Type	Description
logging	OzLogging	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	Color	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	Color	Toolbar title text color
backgroundColor	Color	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	Color	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	Color	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	Color	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	GeometryType	The frame type: oval, rectangle, circle, square
cornerRadius	Int	Rectangle corner radius (in dp, 0-20)
strokeDefaultColor	Color	Frame color when a face is not aligned properly
strokeFaceInFrameColor	Color	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	Color	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	Color	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	Color	Antiscam message text color
textAlpha	Int	Antiscam message text opacity (in %, 0-100)
backgroundColor	Color	Antiscam message background color
backgroundOpacity	Int	Antiscam message background opacity
cornerRadius	Int	Background frame corner radius (in px, 0-20)
flashColor	Color	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	OzMediaTag	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).
metaData	Map<String, String>	Media metadata

OzShotSet

A set of shots in an archive.

Parameter	Type	Description
tag	OzMediaTag	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)
metaData	Map<String, String>	Media metadata

OzVideo

A Liveness video.

Parameter	Type	Description
tag	OzMediaTag	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)
metaData	Map<String, String>	Media metadata

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	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	OzAbstractMedia	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	[OzAbstractMedia]	An array of the OzAbstractMedia objects
params (optional)	Map<String, Any>	Additional parameters
sizeReductionStrategy	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	OzAbstractMedia	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	Resolution	Consolidated analysis result
sourceMedia	SourceMedia	Source media
type	Type	Type of the analysis

class RequestResult

Consolidated result for all analyses performed.

Parameter	Type	Description
analysisResults	List<AnalysisResult>	Analysis result
folderId	String	Folder identifier
resolution	Resolution	Consolidated analysis result

class AnalysisResult

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

Parameter	Type	Description
resolution	Resolution	Consolidated analysis result
type	Type	Type of the analysis
mode	Mode	Resulting score
resultMedia	List<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	AnalysisError	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.