cordova-plugin-onyx

This is not free software. This plugin uses the Onyx sofware development kits (SDKs) for Android and iOS. It requires a license agreement with:

Diamond Fortress Technologies, Inc.

cordova-plugin-onyx

This plugin defines a global navigator.onyx object, which provides an API for capturing a fingerprint image, for in-app fingerprint enrollment and verification, and for fingerprint template generation for server side fingerprint authentication.

Although the object is attached to the global scoped navigator, it is not available until after the deviceready event.

document.addEventListener("deviceready", onDeviceReady, false);
function onDeviceReady() {
    console.log(navigator.onyx);
}

Installation

Contact Diamond Fortress Technologies, Inc. and sign a license agreement to obtain a license key.

This requires cordova 5.0+

cordova plugin add cordova-plugin-onyx

meteor add cordova:cordova-plugin-onyx@5.0.0

Additonal steps for iOS

Run the app for a device to build the app. From your meteor project directory

meteor run ios-device

Install the CocoaPod dependencies Open a terminal and navigate to the folder containing the project that was just created. From your meteor project directory

cd .meteor/local/cordova-build/platforms/ios/

pod install

Then open the project .xcworkspace file to run the app on an iOS device from XCode.

Quick Use Example

MeteorJS applications

Create a settings.json file to load at runtime.

{
    "public": {
        "onyxLicense": "xxxx-xxxx-xxxx-x-x"
    }
}

Reference the Onyx license when you execute an Onyx action.

var onyxOptions = {
    onyxLicense = Meteor.settings.public.onyxLicense;
    action = Onyx.ACTION.CAPTURE;
}
navigator.onyx.exec(onyxOptions, onyxSuccessCallback, onyxErrorCallback);

Run the application on a mobile device

meteor run android-device --settings settings.json

API Reference

• onyx

  • .exec(options, successCallback, errorCallback)
  • .onError : Function
  • .onSuccess : Function

• Onyx

  • .OnyxOptions : JSON Object
  • .ACTION : Enum
  • .RETICLE_ORIENTATION : Enum
  • .LAYOUT_PREFERENCE : Enum
  • .IMAGE_ROTATION : Enum
  • .FINGER_DETECT_MODE : Enum
  • .OnyxResult : JSON Object
  • .CaptureMetrics : JSON Object
  • .NfiqMetrics : JSON Object
  • .FillProperties : JSON Object

---

onyx

onyx.exec(options, successCallback, errorCallback)

Executes onyx with the specified options.

Supported Platforms

• Android
• iOS

Kind: static method of [onyx](#module_onyx)

Param	Type	Description
options	[OnyxOptions](#module_onyx.OnyxOptions)	Parameters telling onyx what to execute.
successCallback	[onSuccess](#module_onyx.onSuccess)
errorCallback	[onError](#module_onyx.onError)

Example

navigator.onyx.exec(onyxOptions, onyxSuccess, onyxError);

onyx.onError : function

Callback function that provides an error message.

Kind: static typedef of [onyx](#module_onyx)

Param	Type	Description
error	Object	An error object containing an error code and message.

onyx.onSuccess : function

Callback function that provides the image data.

Kind: static typedef of [onyx](#module_onyx)

Param	Type	Description
onyxResult	[onyx](#module_onyx.OnyxResult)	Object containing the results of the executed action.

Example

// Display an image of the processed fingerprint
function onyxSuccess(onyxResult) {
    if (onyxResult.action === Onyx.ACTION.CAPTURE) {
        var image = document.getElementById('myImage');
           image.src = onyxResult.processedFingerprintDataUri;    
    }
}

Onyx

Onyx.OnyxOptions : JSON Object

Optional parameters to customize onyx configuration.

Kind: static typedef of [onyx](#module_onyx)
Properties

Name	Type	Default	Platform	Description
onyxLicense	string	xxxx-xxxx-xxxx-x-x	Both	Required Your license key for Onyx.
action	[Action](#module_Onyx.ACTION)	undefined	Both	Required Choose the action for onyx to execute.
returnRawImage	boolean	false	Both	Indicates if the raw fingerprint image will be returned.
returnGrayRawImage	boolean	false	iOS	Indicates if the gray raw fingerprint image will be returned.
returnProcessedImage	boolean	false	Both	Indicates if the processed fingerprint image will be returned.
returnEnhancedImage	boolean	false	Both	Indicates if the enhanced fingerprint image will be returned.
returnBlackWhiteProcessedImage	boolean	false	iOS	Indicates if the black and white processed fingerprint image will be returned.
returnFingerprintTemplate	boolean	false	Both	Indicates if the base64 encoded fingerprint template will be returned.
returnWSQ	boolean	false	Both	Indicates if the base64 encoded WSQ fingerprint will be returned.
returnGrayRawWSQ	boolean	false	iOS	Indicates if the base64 encoded gray raw WSQ fingerprint will be returned.
shouldSegment	boolean	false	Android	Indicates if the fingerprint image should be segmented to remove background noise from the fingerprint image.
shouldConvertToISOTemplate	boolean	false	Android	Indicates that the fingerprint template should be returned in ISO format.
imageRotation	number	IMAGE_ROTATION.NONE	Both	Integer value of 90 degrees (0, 90, 180, or 270) to rotate the fingerprint image output.
fingerDetectMode	number	FINGER_DETECT_MODE.LIVE_FINGER	Both	Integer value of 0 or 1. Determines threshold level of finger coloration for autocapture.
wholeFingerCrop	boolean	false	Android	Will crop less of the image to return more of the fingerprint.
useManualCapture	boolean	false	Both	Disables the auto-capture feature. User must tap the screen to trigger capture.
useOnyxLive	boolean	false	Both	Will send the raw fingerprint image to the Onyx Liveness service to receive a liveness confidence score.
useFlash	boolean	true	Both	Sets the flash to torch mode to illuminate the finger and help determine alignment with the reticle.
showLoadingSpinner	boolean	false	Both	Shows a loading spinner while Onyx is doing asynchronous requests before the capture screen is presented.
reticleOrientation	string	RETICLE_ORIENTATION.LEFT	Both	Sets the direction of the finger reticle on the capture screen.
reticleAngle	number	0	Android	Requires LAYOUT_PREFERENCE.FULL Integer value. Adjusts the angle of the finger reticle.
reticleScale	number	1.0	Android	Float value from 0 to 1. Adjusts the scale of the finger reticle.
backgroundColorHexString	string	#3698D3	Both	Hex color value for the background color of the bottom two-thirds of the capture screen.
showBackButton	boolean	false	Android	Displays a back button on the capture screen.
backButtonText	string	"Back"	Both	Set text to use for back button (localization).
showManualCaptureText	boolean	true	Both	Show or hide the manual capture text.
manualCaptureText	string	"Touch the screen to capture."	Both	Set custom text to use for manual capture (localization).
infoText	string	undefined	Both	Set custom text to display on the capture screen.
infoTextColorHexString	string	undefined	Both	Set the color of the text to display on the capture screen. Defaults to black or white depending on the tint of backgroundColorHexString
base64ImageData	string	undefined	Both	Base64 encoded data string of image to display on the capture screen.
cropFactor	float	0.8	Both	Adjusts the zoom level of the fingerprint image. Higher numbers increase the zoom level.
cropSize	JSON Object { width: number, height: number }	width: 512 height: 300	Both	Sets the dimensions of the fingerprint image.
layoutPreference	string	LAYOUT_PREFERENCE.UPPER_THIRD	Both	Sets the display of the camera view.
probe	string	undefined	Both	Required for Onyx.ACTION.MATCH Base64 encoded WSQ data to match against a reference fingerprint template.
reference	string	undefined	Both	Required for Onyx.ACTION.MATCH Base64 encoded fingerprint template to match against a probe fingerprint template.
pyramidScales	Array<string>	["0.8", "1.0", "1.2"]	Both	Optional for Onyx.ACTION.MATCH Array of string representations of float values for image pyramiding during matching.

Example Interface

export interface IOnyxConfiguration {
  action?: string,
  onyxLicense?: string,
  returnRawImage?: boolean,
  returnGrayRawImage?: boolean,
  returnProcessedImage?: boolean,
  returnEnhancedImage?: boolean,
  returnBlackWhiteProcessedImage?: boolean,
  returnFingerprintTemplate?: boolean,
  returnWSQ?: boolean,
  returnGrayRawWSQ?: boolean,
  shouldSegment?: boolean,
  shouldConvertToISOTemplate?: boolean,
  imageRotation?: number,
  fingerDetectMode?: number,
  wholeFingerCrop?: boolean,
  useManualCapture?: boolean,
  useOnyxLive?: boolean,
  useFlash?: boolean,
  showLoadingSpinner?: boolean,
  reticleOrientation?: string,
  reticleAngle?: number,
  reticleScale?: number,
  backgroundColorHexString?: string,
  showBackButton?: boolean,
  showManualCaptureText?: boolean,
  manualCaptureText?: string,
  backButtonText?: string,
  infoText?: string,
  infoTextColorHexString?: string,
  base64ImageData?: string,
  cropFactor?: number,
  cropSize?: { width?: number, height?: number },
  layoutPreference?: string,
  probe?: string,
  reference?: string,
  pyramidScales?: Array<string>
}

Onyx.ACTION : Enum

Kind: static constants for actions of [Onyx](#module_Onyx)
Properties

Name	Type	Value	Description
CAPTURE	string	"capture"	Launches the Onyx Camera to capture a fingerprint and return an [OnyxResult](#module_onyx.OnyxResult) object. Requires OnyxOptions.onyxLicense
MATCH	string	"match"	Performs on-device matching of the probe and reference fingerprint templates. Requires OnyxOptions.reference and OnyxOptions.probe

Onyx.RETICLE_ORIENTATION : Enum

Kind: static constants for reticleOrientation of [OnyxOptions](#module_Onyx.OnyxOptions)
Properties

Name	Type	Value	Description
LEFT	string	"LEFT"	default Finger reticle on the capture screen will be oriented for a left hand capture.
RIGHT	string	"RIGHT"	Finger reticle on the capture screen will be oriented for a right hand capture.

Onyx.LAYOUT_PREFERENCE : Enum

Kind: static constants for layoutPreference of [OnyxOptions](#module_Onyx.OnyxOptions)
Properties

Name	Type	Value	Description
UPPER_THRID	string	"UPPER_THRID"	The camera view will only occupy the top third of the capture screen.
FULL	string	"FULL"	The camera view will be full screen.

Onyx.IMAGE_ROTATION : Enum

Kind: static constants for imageRotation of [OnyxOptions](#module_Onyx.OnyxOptions)
Properties

Name	Type	Value	Description
ROTATE_NONE	number	0	Default Does not rotate the image.
ROTATE_90_COUNTER_CLOCKWISE	number	90	Rotates the image 90 degrees counter clockwise.
ROTATE_180	number	180	Rotates the image 180 degrees.
ROTATE_90_CLOCKWISE	number	270	Rotates the image 90 degrees clockwise (270 degrees counter clockwise).

Onyx.IMAGE_ROTATION : Enum

Kind: static constants for fingerDetectMode of [OnyxOptions](#module_Onyx.OnyxOptions)
Properties

Name	Type	Value	Description
DEAD_FINGER	number	0	Color threshold for dead fingers.
LIVE_FINGER	number	1	default Color threshold for live fingers.

Onyx.OnyxResult : JSON Object

Results return by Onyx.

Kind: Return type of [onyx.onSuccess](#module_onyx.onSuccess)
Properties

Name	Type	Description
action	string	The Onyx.ACTION that was specified in the OnyxOptions
rawFingerprintDataUri	string	DataUri prefixed, base64 encoded string representation of the raw fingerprint image.
grayRawFingerprintDataUri	string	DataUri prefixed, base64 encoded string representation of the gray raw fingerprint image.
processedFingerprintDataUri	string	DataUri prefixed, base64 encoded string representation of the processed fingerprint image.
enhancedFingerprintDataUri	string	DataUri prefixed, base64 encoded string representation of the enhanced fingerprint image.
blackWhiteProcessedFingerprintDataUri	string	DataUri prefixed, base64 encoded string representation of the black and white processed fingerprint image.
base64EncodedWsqBytes	string	Base64 encoded bytes of the WSQ fingerprint image.
base64EncodedGrayRawWsqBytes	string	Base64 encoded bytes of the gray raw WSQ fingerprint image.
base64EncodedFingerprintTemplate	string	Base64 encoded bytes of the fingerprint template.
captureMetrics	[Onyx.CaptureMetrics](#module_Onyx.CaptureMetrics)	JSON Object containing the capture metrics.
isVerified	boolean	Indicates if the proble fingerprint template matched the reference fingerprint template
matchScore	number	Match score of the compared probe and reference fingerprint templates.

Example Interface

export interface IOnyxResult {
    action?: string,
    rawFingerprintDataUri?: string,
    grayRawFingerprintDataUri?: string,
    processedFingerprintDataUri?: string,
    enhancedFingerprintDataUri?: string,
    blackWhiteProcessedFingerprintDataUri?: string,
    base64EncodedFingerprintTemplate?: string,
    base64EncodedWsqBytes?: string,
    base64EncodedGrayRawWsqBytes?: string,
    captureMetrics?: {
        nfiqMetrics?: {
            nfiqScore?: number,
            mlpScore?: number
        },
        livenessConfidence?: number,
        focusQuality?: number,
        distanceToCenter?: number,
        fillProperties?: {
            heightRatio?: number,
            overlapRatio?: number
        }
    },
    isVerified?: boolean,
    matchScore?: number
}

Onyx.CaptureMetrics : JSON Object

Kind: static typedef for [Onyx](#module_Onyx)
Properties

Name	Type	Description
nfiqMetrics	[Onyx.NfiqMetrics](#module_Onyx.NfiqMetrics)	JSON Object containing the NFIQ Metrics of nfiqScore and mlpScore.
livenessConfidence	number	Float value 0 - 1 indicating the percent confidence that the image captured was a real live fingerprint. Greater than 0.5 (50%) would suggest the finger was more real than fake. Less than 0.5 (50%) would suggest the finger was more fake than real.
focusQuality	number
distanceToCenter	number
fillProperties	[Onyx.FillProperties](#module_Onyx.FillProperties)	Android only JSON Object containg the fill properties of heightRatio and overlapRatio.

Onyx.NfiqMetrics : JSON Object

Kind: static typedef for [Onyx](#module_Onyx)
Properties

Name	Type	Description
nfiqScore	number	NIST Fingerprint Image Quality. Integer value 1 - 5. A value of 5 being the lowest quality fingerprint image and should not be used for matching or saved as a biometric enrollment.
mlpScore	number	Multi-Layer Perceptrons (MLP) Score is a float value from 0 - 1 describing the percent certainty of the NFIQ Score.

Onyx.FillProperties : JSON Object

Kind: static typedef for [Onyx](#module_Onyx)
Properties

Name	Type	Description
heightRatio	number
overlapRatio	number