iProov.NET.MAUI 2.0.2

iProov Biometrics .NET MAUI SDK

Table of contents

• Requirements
• Introduction
• Get a token
• Launch the SDK
• Options
• Handling Errors
• Sample code

Requirements

• NET 8 (net8-android & net8-ios)
• iOS 13 and above
• Android API Level 26 (Android 8) and above

Introduction

The iProov .NET MAUI SDK enables you to integrate iProov into your .NET Android / iOS / MAUI projects. The iProov's native SDK for iOS (Swift) and Android (Java / Kotlin) are wrapped behind a .NET interface for their use within .NET apps. Given the differences in the implementation between these .NET interfaces, the iProov.NET.MAUI wraps both interfaces into a unified .NET version of the iProov API to ease the integration of the iProov Biometric SDKs in MAUI developments.

The full documentation on this package can be found here.

Get a Token

There are two types of tokens:

• A verify token for logging in an existing user
• An enrol token for registering a new user

See the REST API documentation for details about how to generate tokens.

TIP: In a production app you typically obtain tokens via a server-to-server back-end call.

For demos and testing, iProov provides .NET sample code for obtaining tokens via iProov API v2 with our open-source API Client.

Launch the SDK

1. Create an instance of IProovWrapper

	private IProovWrapper wrapper = new IProovWrapper();

2. Listening to IProovStates

To monitor the progress of an iProov claim and receive the result you need an instance of IProovWrapper.IStateListener interface. So, you will have to implement this interface in one of your classes, or create a new one, as shown in the following example.

public class IProovListener: IProovWrapper.IStateListener {

	public void OnConnecting()
	{
		// Called when the SDK is connecting to the server. You could provide an indeterminate
		// progress indication to let the user know that the connection is being established.
	}

	public void OnConnected()
	{
		// The SDK has connected and the iProov user interface is now displayed. You
		// could hide any progress indicator at this point.
	}

	public void OnProcessing(double progress, string? message)
	{
		// The SDK updates your app with the streaming progress to the server and the user authentication.
		// Called multiple times as the progress updates. You could update a determinate progress indicator.
	}

	public void OnCanceled(Canceler canceler)
	{
		// The user canceled iProov, either by pressing the close button at the top of the screen, or sending
		// the app to the background. (canceler == Canceler.User)
		// Or, the claim was cancelled by the integrator by calling the Cancel() method from the IProovWrapper instance (event.canceler == Canceler.Integration)
		// You should use this to determine the next step in your flow.
	}

	public void OnError(IProovException exception)
	{
		// The user was not successfully verified/enrolled due to an error (e.g. lost internet connection).
		// You will be provided with an Exception (see below).
		// It will be called once, or never.
		// An IProovException contains a title that describes the exception, and may also contain a message.
		string title = exception.title;
		string? message = exception.message;
	}

	public void OnFailure(IProovFailureResult failure)
	{
		// The user was not successfully verified/enrolled as their identity could not be verified.
		// Or there was another issue with their verification/enrollment.
		// You might provide feedback to the user as to how to retry. 
		// A FailureReason value is provided to identify the reason as to why the claim failed. Some reasons also provide an optional description (as a string).
		// When enabled for your service provider, failure.frame contains the bytes of an image containing a single frame of the user

		FailureReason reason = failure.reason;
		string? description = failure.description;
		byte[]? frame = failure.frame;
	}

	public void OnSuccess(byte[]? frame)
	{
		// The user was successfully verified/enrolled.
		// You must always independently validate the token server-side (using the /validate API call) before performing any authenticated user actions.
		// When enabled for your service provider, frame contains the bytes of an image containing a single frame of the user
	}
}

3. Launch a Claim

To launch a claim you need to provide a token, the websocket url of the service provider you are using and an IStateListener instance. Additionally you can provide an instance of IProovOptions (see below) to customize the user experience.

IProovWrapper wrapper = new IProovWrapper();
IProovListener listener = new IProovListener();

private void launchIProov(string token, string userId)
{
	var options = new IProovOptions();
	// Here you can customize any IProovOption

	wrapper.LaunchIProov(token, "wss://eu.rp.secure.iproov.me/ws", listener, options);
}

** Running on iOS

For iProov to work on iOS devices, you need to add a Privacy - Camera Usage Description entry to your Info.plist file (<Your_App_Folder>/Platforms/iOS/Info.plist) with the reason why your app requires camera access (e.g. "To iProov you in order to verify your identity.")

Canceling a Session

Under normal circumstances, the user will be in control of the completion of the iProov scan, i.e. they will either complete the scan, or use the close button to cancel. In some cases, you (the integrator) may wish to cancel the iProov scan programmatically, for example in response to a timeout or change of conditions in your app.

To cancel the iProov SDK, you first need to hold a reference to the IProovWrapper object and you can then call Cancel() on it.

IProovWrapper wrapper = new IProovWrapper();
IProovListener listener = new IProovListener();
var options = new IProovOptions();

wrapper.LaunchIProov(token, "wss://eu.rp.secure.iproov.me/ws", listener, options);

// Example - cancel the wrapper session after 10 sec
System.Timers.Timer timer = new System.Timers.Timer(10000);
timer.Elapsed += (sender, e) => 
{
    wrapper.Cancel(); // Will return true if the wrapper session was successfully canceled
};
timer.Enabled = true;

Options

The Options class allows iProov to be customized in various ways. These can be specified by passing an instance of IProovOptions in the LaunchIProov() method.

Most of these options are common to both Android and iOS, however, there are some options that are platform-specific.

For full documentation, please read the respective iOS and Android native SDK documentation.

A summary of the support for the various SDK options in iProov.NET.MAUI is provided below. All options are nullable and any options not set will default to their platform-defined default value.

Filter Options

The SDK supports two different camera filters:

LineDrawingFilter

LineDrawingFilter is iProov's traditional "canny" filter, which is available in 3 styles: .Shaded (default), .Classic and .Vibrant.

The foregroundColor and backgroundColor can also be customized.

Example:

var options = IProovOptions();

options.filter = new IProovOptions.LineDrawingFilter(
                style: LineDrawingFilterStyle.Shaded,
                foregroundColor: Colors.Black,
                backgroundColor: Colors.White);

NaturalFilter

NaturalFilter provides a more direct visualization of the user's face and is available in 2 styles: .Clear (default) and .Blur.

Example:

var options = IProovOptions();

options.filter = new IProovOptions.NaturalFilter(style: NaturalFilterStyle.Clear);

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

Handling errors

All errors from the native SDKs are re-mapped to IProovException exceptions:

Sample code

For a simple iProov experience that is ready to run out-of-the-box, check out the sample code available here for a .NET MAUI app that uses iProov.NET.MAUI.