Skip to content

Upgrading to v5.x and earlier

Jump to bottom
richardsimongreen edited this page Nov 8, 2022 · 1 revision

⚠️ This document relates to deprecated or obsolete SDK versions. For details regarding upgrading to the latest SDK version, consult the main Upgrade Guide.

Upgrading to v5.2.2

Exceptions

v5.2.2 improves IProovExceptions with subclasses and removes Reason enum for convenience.

  • IProovException has moved package from com.iproov.sdk to com.iproov.sdk.core.exception
    • Reason enum replaced with Error string constants
  • New subclasses of IProovException, which are also found in com.iproov.sdk.core.exception, that encapsulate the new Error string constants
    • CameraException
    • CameraPermissionException
    • CaptureAlreadyActiveException
    • EncoderException
    • FaceDetectorException
    • LightingModelException
    • MultiWindowException
    • ServerException
    • StreamingException
    • UnsupportedDeviceException

Upgrading to v5.2.0

There is a new item added to the Reason enum called CAPTURE_ALREADY_ACTIVE_ERROR. The purpose of this error is to inform when the previous IProov is still running. The details are as follows:

  • IProov will still be running, after its Activity has closed and the user is returned to the calling Activity, until a terminating event is sent through the IProov.Listener (such events are: onSuccess(), onError(), onCancelled() and onFailure()).
  • If IProov.launch() is called before such a terminating event then onError() will be called with Reason.CAPTURE_ALREADY_ACTIVE_ERROR.

Upgrading to v5.1.0

Launching the SDK

The launch() method in 5.0.0 which passed the listener as the final parameter has been deprecated in favor of a launch() method without the listener. All other parameters remain the same, You should now register the listener with a call to IProov.registerListener(listener) in your Activity onCreate() method, and call IProov.unregisterListener() in onDestroy(). Consult the README for further details.

Logo image API change

Options.ui.logoImage has been removed and replaced with two new options:

  • Options.ui.logoImageResource - pass a drawable resource ID
  • Options.ui.logoImageDrawable - pass a drawable directly

Upgrading to v5.0.0

This has been a major revision.

  1. Tokens (logging in, enrolment and validation) no longer form part of the SDK
  2. You no longer need to use Intents (and ActivityResults)
  3. Android SDK 16-18 is NO LONGER supported. Now requires a minimum of Android SDK 19+ (v4.4 Kitkat).
  4. Options have changed
  5. How you launch iProov has been greatly simplified

Tokens

For security reasons, the old three-step flow has been separated out. Logging in, enrolment and validation are now done via our API only. The SDK now only provides the scanner function. This allows for a more secure flow. You are expected to secure your apiKey and secret on your own API servers (and no longer have to ship them inside your app) behind suitable end points. There your servers will call our API when called upon by your app.

For convenience, and certainly NOT for production, we provide sample client api code to help you to test your app out before you have suitable server endpoints created. Indeed, the "Waterloo Bank" sample app uses this, so you can look at that for sample usage.

Launching

Note that if you are using Kotlin then the "Waterloo Bank" sample app demonstrates both Java and Kotlin for you to compare and contrast.

Old Method (v4.4.0)

Intent i = new IProov.NativeClaim.Builder(actvity)
.setMode(IProov.Mode.Verify)
.setServiceProvider("{{api-key}}")
.setUsername("{{username}}")
.getIntent();
startActivityForResult(i, 0);

New Method (v5.0.0)

Note the new hierarchical structure of the options.

IProov.Options options = new IProov.Options();
	options.ui.autoStartDisabled = false;
        options.ui.logoImage = R.mipmap.ic_launcher;
        options.ui.fontPath = "Merriweather-Bold.ttf";

IProov.launch(context, token, options, new IProov.Listener() {
    @Override
    public void onSuccess(String token) {
        // Successfully registered (enrol) or iProoved (verify)
    }

    @Override
    public void onFailure(String reason, String feedback) {
        // Failed to registered (enrol) or iProoved (verify)
        // This is usually due to lighting conditions or face movement
    }

    @Override
    public void onProcessing( double progress, String message) {
        // Scanning is in progress, providing a message/prompt/title for the user and a value 0.0 to 1.0 indicating how far through the process we are
    }

    @Override
    public void onError(IProovException e) {
        // An unrecoverable error occurred e.g. network problems. See IProovException.Reason.
    }

    @Override
    public void onCancelled() {
        // The user hit back or home and cancelled the scan
    }
});
val options = new IProov.Options()
    .apply {
        ui.autoStartDisabled = false
        ui.fontPath = "Merriweather-Bold.ttf"
        ui.logoImage = R.mipmap.ic_launcher
    }

IProov.launch(context, token, createOptions(), object : IProov.Listener {
    override fun onSuccess(token: String) {
        // Successfully registered (enrol) or iProoved (verify)
    }
    override fun onFailure(reason: String?, feedback: String?) {
        // Failed to registered (enrol) or iProoved (verify)
        // This is usually due to lighting conditions or face movement
    }
    override fun onProcessing(progress: Double, message: String) {
        // Scanning is in progress, providing a message/prompt/title for the user and a value 0.0 to 1.0 indicating how far through the process we are
    }
    override fun onError(e: IProovException) {
        // An unrecoverable error occurred e.g. network problems. See IProovException.Reason.
    }
    override fun onCancelled() {
        // The user hit back or home and cancelled the scan
    }
})

IProov.launch() is overloaded: from the simplest with just the parameters: context, token and listener, the next has those and adds options also; and the full one which also adds a streamingUrl.

Old Options (v4.4.0)

Required

  • String baseURL; - removed and added as an optional parameter to a connection

Optional

  • boolean autoStart = false;

  • String localeOverride = "";

  • boolean messageDisabled = false;

  • int startingBackgroundColor;

  • int startingEdgeColor;

  • int lowLightBackgroundColor; - removed

  • int lowLightEdgeColor; - removed

  • boolean enableScreenshots;

  • boolean enableRemoteLogging; - removed

  • String regularFont; - removed

  • String boldFont; - removed

  • boolean swapMessagePosition; - removed

  • int connectingOvalColor;

  • int notReadyOvalColor;

  • int readyOvalColor;

  • int logoImage;

  • int notificationImage; - removed

  • String notificationTitle; - removed

  • String pushToken; - removed

  • boolean pinningDisabled = false;

  • int[] certificateFiles;

  • int maxPitchAngle;

  • int maxYawAngle;

  • int maxRollAngle;

New Options (v5.0.0)

Optional

Under the ".ui" hierarchy:

  • Boolean autoStartDisabled - was called autoStart and inverted in meaning
  • String title; - replaces messageDisabled, allowing title (message) to be changed, otherwise set by system if null
  • Integer backgroundColor; - was called startingBackgroundColor
  • Integer lineColor; - was called startingEdgeColor
  • Integer loadingTintColor; - was called connectingOvalColor
  • Integer notReadyTintColor; - was called notReadyOvalColor
  • Integer readyTintColor; - was called readyOvalColor
  • Boolean enableScreenshots;
  • String fontAsset; - was called regularFont (boldFont removed), from asset folder
  • String fontResource; - new resource based font method
  • Integer logoImage;
  • Boolean scanLineDisabled; - new, was under .capture
  • Filter filter; - new, one of {CLASSIC, SHADED, VIBRANT}
  • Orientation orientation; - new, one of {PORTRAIT, REVERSE_PORTRAIT, LANDSCAPE, REVERSE_LANDSCAPE}

Under the ".capture" hierarchy:

  • Integer maxPitchAngle;
  • Integer maxYawAngle;
  • Integer maxRollAngle;
  • Camera camera; - new, select camera to use, FRONT or EXTERNAL (usb)

Under the ".network" hierarchy:

  • List<Integer> certificates; - was called certificateFiles, was array
  • Boolean disableCertificatePinning - was called pinningDisabled
  • Integer timeoutSecs; - new, control over network
  • String path; - new, control over network

Reason enum changes

The following reasons no longer exist, because both registration and enrolment are no longer in the SDK: UNKNOWN_IDENTITY, ALREADY_ENROLLED. Also Reason codes have been consolidated and simplified overall.

Old Reasons (v4.4.0)

public enum Reason {
    GENERAL_ERROR, -- Removed, now handled by ENCODER_ERROR and STREAMING_ERROR
    NETWORK_ERROR, -- Removed, now handled by ENCODER_ERROR and STREAMING_ERROR
    STREAMING_ERROR,
    UNKNOWN_IDENTITY,
    ALREADY_ENROLLED, -- Removed, no longer handling fetching the token
    USER_PRESSED_BACK, -- Removed, now handled by onCancelled()
    USER_PRESSED_HOME, -- Removed, now handled by onCancelled()
    UNSUPPORTED_DEVICE,
    CAMERA_PERMISSION_DENIED,
    SSL_EXCEPTION, -- Removed, now handled by STREAMING_ERROR
    SERVER_ABORT; -- Renamed to SERVER_ERROR
 }

New Reasons (v5.0.0)

public enum Reason {
        ENCODER_ERROR,
        STREAMING_ERROR,
        UNSUPPORTED_DEVICE,
        CAMERA_PERMISSION_DENIED,
        SERVER_ERROR,
        MULTI_WINDOW_MODE_UNSUPPORTED,
        CAMERA_ERROR,
        LIGHTING_MODEL_ERROR
     }

Upgrading to SDK v4.4.0

NB: the UIOptions class has been renamed to IProovConfig. IProovConfig now also includes setPrivacyPolicyDisabled, setInstructionsDialogDisabled and setMessageDisabled, which have been moved from NativeClaim.Builder

Upgrading to SDK v3.4.x

There are now some additional options available to customize the interface presented by the SDK. See the "Configuration Options" section of Readme for more info.

Upgrading to SDK v3.3

In SDK v3.1.0, we moved to explicit Intents with methods to build the Intent for you. We had feedback from users that they wanted more customisation options when creating an iProov request, so we have now moved to a builder-style approach for building the intent which allows a much greater degree of flexibility.

Old method (v3.2):

Intent i = IProov.newVerifyUsernameIntent(this, "{{api-key}}", "{{username}}");
startActivityForResult(i, 0);

New method (v3.3):

Intent i = new IProov.NativeClaim.Builder(this)
.setMode(IProov.Mode.Verify)
.setServiceProvider("{{api-key}}")
.setUsername("{{username}}")
.getIntent();
startActivityForResult(i, 0);

Consult the documentation for the full set of builders and available options that they can accept.

Upgrading to SDK v3.2

Previously, iProov was launched by starting an Intent with the action IProov.INTENT_IPROOV. We have now moved to using explicit Intents.

We have also taken this opportunity to simplify the process of launching iProov, so we provide a series of IProov.newIntent() methods that builds the Intent for you, via a simple, clean API.

For further information, see the Launch Modes section. An example of the new approach versus the old one is as follows:

Old method (pre-v3.2):

Intent i = new Intent(IProov.INTENT_IPROOV);
i.putExtra(IProov.EXTRA_MODE, IProov.Mode.Verify.ordinal());
i.putExtra(IProov.EXTRA_SERVICE_PROVIDER, "{{api-key}}");
i.putExtra(IProov.EXTRA_USERNAME, "{{username}}");
startActivityForResult(i, 0);

New method (v3.2):

Intent i = IProov.newVerifyUsernameIntent(this, "{{api-key}}", "{{username}}");
startActivityForResult(i, 0);

The delivery of the iProov result to your Activity via onActivityResult() is unchanged.

Upgrading from SDK v2.6.5 and earlier

You are no longer required to explicitly initialise iProov with a call IProov.init(context) before using iProov in your application, which was introduced in SDK v2.6.4.

You should remove any calls to IProov.init(context) from your application.

Clone this wiki locally