Upgrading to v8.x

Proguard Files for 8.0.x

This was missing in the consumer Proguard rules and MUST be added to your Proguard rules. We will be adding this to the consumer rules in the next release, so just for 8.0.x add these yourself:

-keep class com.google.protobuf.** { *; }
-keep class com.google.protobuf.**$* { *; }

Streaming URL

The SDK now streams over WebSockets instead of Socket.IO. In practice, this means that you should replace any references to https://*.rp.secure.iproov.me with wss://*.rp.secure.iproov.me/ws when passing the streamingURL parameter to IProov.launch().

Further guidance will be forthcoming in due course for any customers making use of reverse proxies. In the meantime, please contact us to discuss your requirements further.

Changes to Options

The structure of Options has been simplified and flattened. Many existing options have been re-mapped to the new hierarchy, while others have been removed as they are no longer applicable to the new user experience.

The following table maps all SDK v7 options to their v8 equivalents:

SDK v7	SDK v8
ui.filter	filter (see below)
ui.lineColor	Removed (now handled via the LineDrawingFilter)
ui.backgroundColor	Removed (now handled via the LineDrawingFilter)
ui.title	title
ui.fontPath	font as PathFont
ui.fontResource	font as ResourceFont
ui.logoImageResource	logo as ResourceIcon
ui.logoImageDrawable	logo as DrawableIcon
ui.enableScreenshots	enableScreenshots
ui.orientation	orientation
ui.activityCompatibilityRequestCode	Removed
ui.headerBackgroundColor	Removed
ui.footerBackgroundColor	Removed
ui.headerTextColor	titleTextColor
ui.footerTextColor	Removed
ui.promptTextColor	promptTextColor
ui.floatingPromptEnabled	Removed
ui.floatingPromptRoundedCorners	promptRoundedCorners
ui.closeButtonImageResource	closeButton.icon as ResourceIcon
ui.closeButtonImageDrawable	closeButton.icon as DrawableIcon
ui.closeButtonTintColor	closeButton.colorTint
ui.livenessAssurance.secondaryTintColor	Removed
ui.livenessAssurance.primaryTintColor	Removed
ui.livenessAssurance.overlayStrokeColor	livenessAssurance.ovalStrokeColor
ui.livenessAssurance.floatingPromptBackgroundColor	promptBackgroundColor
ui.genuinePresenceAssurance.notReadyTintColor	Removed
ui.genuinePresenceAssurance.readyTintColor	Removed
ui.genuinePresenceAssurance.notReadyOverlayStrokeColor	genuinePresenceAssurance.notReadyOvalColor
ui.genuinePresenceAssurance.readyOverlayStrokeColor	genuinePresenceAssurance.readyOvalStrokeColor
ui.genuinePresenceAssurance.notReadyFloatingPromptBackgroundColor	promptBackgroundColor
ui.genuinePresenceAssurance.readyFloatingPromptBackgroundColor	promptBackgroundColor
ui.genuinePresenceAssurance.progressBarColor	Removed
ui.genuinePresenceAssurance.autoStartDisabled	Removed
network.certificates	certificates
network.timeoutSecs	timeoutSecs
network.path	Removed
capture.camera	camera
capture.faceDetector	faceDetector (deprecated)
capture.genuinePresenceAssurance.maxYaw	genuinePresenceAssurance.maxYaw (deprecated)
capture.genuinePresenceAssurance.maxRoll	genuinePresenceAssurance.maxRoll (deprecated)
capture.genuinePresenceAssurance.maxPitch	genuinePresenceAssurance.maxPitch (deprecated)

In addition to the above, the following new options have been added:

Name	Description
closeButton.icon as BitmapIcon	A third way to define the close button image
livenessAssurance.completedOvalStrokeColor	Color for oval stroke after LA scan completes.
surroundColor	Color applied to the area outside the oval.

Changes to filter

In prior SDK versions, the permitted filter options were SHADED (default), CLASSIC and VIBRANT.

These filter options still exist, but are now grouped under a LineDrawingFilter class, and are set via the style property. For example:

options.filter = LineDrawingFilter(LineDrawingStyle.SHADED, Color.BLACK, Color.WHITE)

SDK v8 also introduces a new NaturalFilter which is available in both CLEAR and BLUR styles:

options.filter = NaturalFilter(NaturalStyle.CLEAR)

Note: NaturalFilter is only available for Liveness Assurance claims. Attempting to use NaturalFilter with Genuine Presence Assurance claims will result in an error.

Deprecation of Face Detector

The 'faceDetector' option is a deprecated feature which will be removed from a future SDK version along with Blazeface and MLKit support.

If you believe you may be affected by the future removal of pose control, please contact us to discuss further.

Deprecation of Pose Control

The genuinePresenceAssurance.maxYaw, genuinePresenceAssurance.maxRoll & genuinePresenceAssurance.maxPitch options all relate to "pose control" which is a deprecated feature which will be removed from a future SDK version.

If you believe you may be affected by the future removal of pose control, please contact us to discuss further.

Changes to Callbacks

The first important change to mention is that IProov is no longer a Static Java Class but now a Kotlin interface for a new way of launching a claim (IProovFlowLauncher). This interface also contains all the Options and supporting classes for the API. A facade called IProovCallbackLauncher is also provided to closely copy the old v7 API.

You now have two ways to launch IProov by creating an instance of one of the following:

1. IProovCallbackLauncher

val iProovCallbackLauncher = IProovCallbackLauncher()

• this is the easiest upgrade path since it closely matches the v7 way of launch
• it feeds information back using a callback listener just like v7
• click the link in the title to find out how to create a listener

2. IProovFlowLauncher

val iProovFlowLauncher = IProovFlowLauncher()

• this is the more advanced path, requiring a knowledge of Kotlin Coroutines and Flows
• it feeds information back using a Flow of IProovSessionState events (instead of callback functions being called). Each event contains a Session and a IProovState, thus the one Flow provides information for many claims (Sessions)
• click the link in the title to find out how to collect from the Flow

Common changes affecting both mechanisms include:

• Every claim is now represented by a Session returned from launch

  1. val session = iProovCallbackLauncher.launch(...)
  2. val session = iProovFlowLauncher.launch(...)

• Cancel a claim - in addition to the user being able to cancel (using the back button), the app can cancel the claim now also

  • 'session.cancel()'

• Cancelled now includes canceller, to indicate if the user or the app cancelled

  1. fun onCancelled(canceller: IProov.Canceller) (in IProovCallbackLauncher.Listener)
  2. IProov.IProovState.Cancelled(val canceller: IProov.Canceller) (in IProovFlowLauncher)

• SuccessResult

  • this no longer contains the token property. This property is redundant, because the token is the same as the one passed to IProov.launch().

• FailureResult

  • this no longer contains the token property. This property is redundant, because the token is the same as the one passed to IProov.launch().

  • The reason property on FailureResult has been changed. It is no longer a String to be displayed to the user, instead it is now an enum of potential failure reasons.

  • Use failureResult.reason.description for a user-facing localized description of how to recover from the failure.

Strings

The SDK strings have been updated and are now available in 9 additional languages alongside English.

The following strings have been added:

Name	Default text (English)
iproov__failure_eyes_closed	Keep your eyes open
iproov__failure_face_too_close	Move your face farther from the screen
iproov__failure_face_too_far	Move your face closer to the screen
iproov__failure_misaligned_face	Keep your face in the oval
iproov__failure_not_supported	Device is not supported
iproov__failure_obscured_face	Remove any face coverings
iproov__failure_sunglasses	Remove sunglasses
iproov__failure_too_bright	Move somewhere darker
iproov__failure_too_dark	Move somewhere brighter
iproov__failure_too_much_movement	Keep still
iproov__failure_unknown	Try again
iproov__prompt_align_face	Put your face in the oval

The following string has been changed:

Name	v7	v8
iproov__failure_user_timeout	Your session has expired	Try again

The following strings have been removed:

Name	Rationale
iproov__debug_text_default	Relates to a debug value
iproov__prompt_tap_to_begin	"Tap to start" feature has been removed
iproov__prompt_liveness_align_face	Use iproov__prompt_align_face instead (see above)
iproov__prompt_liveness_no_target	Use iproov__prompt_align_face instead (see above)
iproov__prompt_genuine_presence_align_face	Use iproov__prompt_align_face instead (see above)
iproov__progress_streaming_slow	This can now be handled in your app instead
iproov__prompt_connecting	No longer used
iproov__failure_ambiguous_outcome	Use iproov__failure_unknown instead (see above)
iproov__failure_lighting_backlit	Use new failure cases instead (see above)
iproov__failure_lighting_face_too_bright	Use iproov__failure_too_bright instead (see above)
iproov__failure_lighting_flash_reflection_too_low	Use new failure cases instead (see above)
iproov__failure_lighting_too_dark	Use iproov__failure_too_dark instead (see above)
iproov__failure_motion_too_much_mouth_movement	Use iproov__failure_too_much_movement instead (see above)
iproov__failure_motion_too_much_movement	Use iproov__failure_too_much_movement instead (see above)

Native Bridge

If you are using the Android Biometrics SDK in conjunction with the Web Biometrics SDK via Native Bridge, you are recommended to upgrade to Web SDK v4.0+ as the Native Bridge protocol has been updated.

Reverse Proxies

SDK v8 uses WebSockets rather than Socket.IO for network connectivity. Customers requiring additional support for reverse proxy configuration should contact us.