MRZ Scanner Guide

For

Xamarin

SDK v.1.10.x

Installation guide

Xamarin.Android

Please follow these simple steps to integrate our SDK v.1.10.x into your Xamarin.Android project:

  1. Copy MRZScannerAndroidBinding.dll in your project
  2. Add reference to MRZScannerAndroidBinding.dll file in your project references
  3. Add the following code to the layout.xml of the activity where you want the scanner to be shown: (It is recommended that the scanner takes full screen)

<fragment
           android:id="@+id/scannerFragment"
           android:name="com.scansolutions.mrzscannerlib.MRZScanner"
           android:layout_width="match_parent"
           android:layout_height="match_parent" />

  1. Use this code to configure the scanner. The code should be added in the activity where the scanning will take place

MRZScanner mrzScanner = (MRZScanner)SupportFragmentManager.FindFragmentById(Resource.Id.scannerFragment);
               mrzScanner.SetScannerType(type);          // Options: [ScannerTypeMrz, ScannerTypeDocImageId, ScannerTypeDocImagePassport]. Default: MRZ.
               MRZScanner.SetIDActive(true);             // Enable/disable the ID document type. Default: true.
               MRZScanner.SetPassportActive(true);   // Enable/disable the Passport document type. Default: true.
               MRZScanner.SetVisaActive(true);           // Enable/disable the Visa document type. Default: true.
               MRZScanner.SetMaxThreads(2);              // Set the max CPU threads that the scanner can use. Default: 2.
               MRZScanner.RegisterWithLicenseKey(this, "licenseKey", this);

  1. Implement the IMRZScannerListener interface as a listener for a successful MRZ scan:
    public class ScannerActivity : AppCompatActivity, IMRZScannerListener
  2. Implement the IMRZLicenceResultListener interface as a listener to get result from registration process
    public class ScannerActivity : AppCompatActivity, IMRZScannerListener, IMRZLicenceResultListener

API description

/**

* Specify which scanner type you want to use. There are two options: "MRZ Scanner" and "Document Image scanner".

* The "MRZ Scanner" option is used to scan for MRZ.

* The "Document image scanner" is used for capturing front and back image of the ID documents.

*

* @param scannerType [ScannerTypeMrz, ScannerTypeDocImageId, ScannerTypeDocImagePassport]. Default value is ScannerTypeMrz

*/

void SetScannerType(ScannerType scannerType)

/**

* Resume scanning after the scanner has been paused/stopped. Usually after a successful scan.

*/

static void ResumeScanning()

/**

* @return the currently set date format in which the parsed dates are formatted.

*/

/**

* Set the date format in which the parsed dates are formatted.

*

* @param dateFormat the pattern describing the date format. Example: "dd.MM.yyyy"

*/

string dateFormat = "dd.MM.yyyy";
void set(string dateFormat) {
MRZScanner.DateFormat = dateFormat;
}

/**

* @return the current SDK Version.

*/

static string SdkVersion()

/**

* Specify whether the scanner should detect and return result for IDs.

*

* @param isIDActive [true, false]. The default value is true.

*/

static void SetIDActive(bool isIDActive)

/**

* Specify whether the scanner should detect and return result for passports.

*

* @param isPassportActive [true, false]. The default value is true.

*/

static void SetPassportActive(bool isPassportActive)

/**

* Specify whether the scanner should detect and return result for visas.

*

* @param isVisaActive [true, false]. Default value is true.

*/

static void SetVisaActive(bool isVisaActive)

/**

* Specify the maximum number of CPU threads that the scanner can use during the scanning process.

*

* @param maxThreads number of CPU threads. Default value is 2.

*/

static void SetMaxThreads(int maxThreads)

/**

* Register with the licence key provided to remove the asterisks (*) from the result.

*

* @param context the activity's context.

* @param key         the provided licence key.

* @return 0 for success, -1 if registration failed.

* @deprecated use {@link MRZScanner#registerWithLicenseKey(Context, String,

MRZLicenceResultListener)} instead.

*/

static int RegisterWithLicenseKey(Context context, string key)

/**

* Register with the licence key provided to remove the asterisks (*) from the result.

*

* @param context the activity's context.

* @param key         the provided licence key.

* @param listener mrzLicenceResultListener  register result callback where int @result is 0 when

registration is successful <0 when registration failed.

*                                      @errorMessage is null when registration is successful, otherwise

@errorMessage is an error description String.

* @return 0 for success, -1 if registration failed.

*/

static int RegisterWithLicenseKey(Context context, string key, IMRZLicenceResultListener listener)

/**

* Scan for a single bitmap.

*

* @param bitmap  the image to be scanned.

* @param activity the initialisation activity context.

* @param listener result listener.

*/

static void ScanBitmap(Bitmap bitmap, Activity activity, IMRZScannerListener listener)

/**

* Trigger an image picker.

*

* @param activity the initialisation activity context.

* @param listener result listener

*/

static void ScanFromGallery(Activity activity, IMRZScannerListener listener)

/**

* Show a warning alert dialog if the camera's resolution is lower than 5 MP and if the camera lacks the

AutoFocus feature.

*

* @param shouldWarn  [true, false]. Default value is true.

*/

static void WarnIncompatibleCamera (bool shouldWarm)

/**

* Set valid issuing country codes. Successful scans with country codes not included in the array will be

ignored.

*

* @param validIssuingCountries  array with active country codes. Example value: new

String[]{"foo", "bar"}.

*/

static void SetValidIssuingCountries (string[] validIssuingCountries)

/**

* Set custom overlay image for the scanner.

*

* @param customImage bitmap representation of the overlay image

*/

void SetCustomImageOverlay (Bitmap customImage)

/**

* Set custom overlay image for the scanner.

*

* @param customImage bitmap representation of the overlay image

*/

void SetCustomImageOverlay (Bitmap customImage)

/**

* Enable scan from gallery. If enabled, a "scan from gallery" button will appear in the scanner preview.

*

* @param enabled indicates whether the "scan from gallery"  is enabled. Default value: false.

*/

void enableScanFromGallery (bool enabled)

/**

* Enable upside-down scanning. If enabled, the scanner will also try the upside-down format of the preview.

*

* @param enabled indicates whether the "upside-down" feature  is enabled. Default value: false.

*/

void SetEnableUpsideDownScanning (bool enabled)

/**

* Set valid nationality and issuing country codes. Successful scans with country codes not included in the array will be ignored.

*

* @param validCountryCodes array with active country codes. Example value: new string[]{"GBR", "USA"}. Default: {} (ALL).

*/

static void SetValidCountryCodes (string[] validCountryCodes)

/**

* Specify whether validation of country codes is enabled.

*

* @param enabled indicates whether validation is enabled. Default: true.

*/

static void SetValidateCountryCodesEnabled (bool enabled)

/**

* Turn flash on or off.

*

* @param on true = on, false = off. Default value: false.

*/

void ToggleFlash (bool on)

/**

* Enable vibration on successful scan.

*

* @param enabled indicates whether the vibration feature  is enabled. Default value: true.

*/

static void SetEnableVibrationOnSuccess (bool enabled)

/**

* Continuous scanning. If enabled, after successful scan, the scanner view will not be paused.

*

* @param enabled indicates whether the scanner should stay active after a successful scan.

*/

void SetContinuousScanningEnabled (bool enabled)

/**

* Ignore duplicates when scanning continuously.

*

* @param ignore indicates whether the scanner should repeat the last successful scan. Default value: true.

*/

void SetIgnoreDuplicates (bool ignore)

/**

* Set the scanning rectangle to limit the scanning area. The parameters' values are representing percentages of the scanning preview.

*

* @param x the top left point of the scanning rectangle. [0,...,100] Default value: 5.

* @param y the top left point of the scanning rectangle. [0,...,100] Default value: 20.

* @param width width the width of the scanning rectangle. [0,...,100] Default value: 90.

* @param height height the height of the scanning rectangle. [0,...,100] Default value: 60.

*/

void SetScanningRectangle(int x, int y, int width, int height)

Xamarin.iOS

Please follow these simple steps to integrate our SDK v.1.9.x into your Xamarin.iOS project:

  1. Copy MRZScanneriOSBinding.dll in your project
  2. Add reference to MRZScanneriOSBinding.dll file in your project references
  3. Start the scanner with the following code:

mrzScannerController = new MRZScannerController();

               // Options: [Mrz, DocumentImage, DocumentImagePassport]. Default: Mrz.
               mrzScannerController.SetScannerType(MRZScannerType.Mrz);
               // Enable/disable the ID document type. Default: true.
               MRZScannerController.SetIDActive(true);
               // Enable/disable the Passport document type. Default: true.
               MRZScannerController.SetPassportActive(true);
               // Enable/disable the Visa document type. Default: true.
               MRZScannerController.SetVisaActive(true);
               // Set the max CPU threads that the scanner can use. Default: 2.
               mrzScannerController.SetMaxCPUCores(2);
               // Set license key
               MRZScannerController.RegisterLicenseWithKey("License_key", (result, error) =>
               {
                   if (error != null)
                   {
                       Console.WriteLine("Result code: " + result + ". " + error);
                   }
                   else
                   {
                       Console.WriteLine("Result code: " + result + ". Registration successful.");
                   }
               });

               mrzScannerController.WeakDelegate = this;

               UIViewController currentViewController = NavigationController;
               if (currentViewController == null)
                   currentViewController = this;

               currentViewController.AddChildViewController(mrzScannerController);
               mrzScannerController.InitUI(currentViewController);

  1. To get the result, implement IMRZScannerDelegate:
    public partial class ViewController : UIViewController, IMRZScannerDelegate
  2. Add the following row in your Info.plist file:
    key: NSCameraUsageDescription
    value: MRZ Scanner requires using camera

API description



/**

*Specify the state of night mode. Night mode is used for increasing the ISO and brightness so the scanner performs better in dark environments.

@param active [true, false]. Default value is false.

*/

void SetNightModeActive(bool active)

/**

* Specify whether the scanner should detect and return result for IDs.

@param active [true, false]. Default value is true.

*/

static void SetIDActive(bool active)

/**

* Specify whether the scanner should detect and return result for Passports.

@param active [true, false]. Default value is true.

*/

static void SetPassportActive(bool active)

/**

* Specify whether the scanner should detect and return result for Visas.

@param active [true, false]. Default value is true.

*/

static void SetVisaActive(bool active)

/**

Specify the maximum number of CPU threads that the scanner can use during the scanning process.

@param maxCPUCores Number of CPU threads. Default value is 2.

*/

void SetMaxCPUCores(int maxCPUCores)

/**

Specify which scanner type you want to use. There are two options: "MRZ Scanner" and "Document Image scanner".

The "MRZ Scanner" option is used to scan for MRZ.

The "Document image scanner" is used for capturing front and back image of the ID documents.

@param scannerType [Mrz, DocumentImageId, DocumentImagePassport]. Default value is Mrz

*/

void SetScannerType(MRZScannerType scannerType)

/**

Set the date format in which the parsed dates are formatted.

@param dateFormat The pattern describing the date format. Example: "dd.MM.YYYY"

*/

static void SetDateFormat(string dateFormat)

/**

Resume scanning after the scanner has been paused/stopped. Usually after a successful scan.

*/

void ResumeScanner()

/**

Stop and close the MRZ Scanner

*/

void CloseScanner()

/**

Register with the licence key provided to remove the asterisks (*) from the result.

@param key The provided licence key.

@return Returns 0 for success, -1 if registration failed

*/

static int RegisterLicenseWithKey(string key)

/**

@return The current MRZScannerSDK Version.

*/

static string SDKVersion

/**

Scan a single image

@param image The UIImage to be scanned.

@return The result data model.

*/

static MRZResultDataModel ScanImage(UIIMage image)

/**

Scan from gallery

@param context current ViewController.

@param mrzDelegate result delegate

*/

static void ScanFromGallery(NSObject context, MRZScannerDelegate mrzDelegate)

/**

Set the scanning rectangle to limit the scanning area. The parameters' values are representing percentages of the scanning preview.

@param x the top left point of the scanning rectangle. [0,...,100] Default value: 5.

@param y the top left point of the scanning rectangle. [0,...,100] Default value: 20.

@param width the width of the scanning rectangle. [0,...,100] Default value: 90.

@param height the height of the scanning rectangle. [0,...,100] Default value: 60.

*/

static void SetScanningRectangle(x: float, y: float, width: float,  height: float)

/**

* Set valid nationality and issuing country codes. Successful scans with country codes not included in the array will be ignored.

*

* @param validIssuingCountries array with active country codes. Example value: new string[]{"GBR", "USA"}. Default: {} (ALL).

*/

static void SetValidIssuingCountries (string[] validIssuingCountries)

/**

* Specify whether validation of country codes is enabled.

*

* @param enabled indicates whether validation is enabled. Default: true.

*/

static void SetValidateCountryCodesEnabled (bool enabled)

/**

* Successful scans with documents that are expired will be ignored and the scanning process will continue until a valid document is found.

*

* @param ignore whether the result should be ignored. Default value: false.

*/

static void IgnoreResultIfDocumentIsExpired (bool ignore)

/**

* Set custom overlay image for the scanner.

*

* @param customImage the image to be shown on top of the scanner preview.

*/

static void SetCustomOverlayImage (UIImage cutomImage)

/**

* Enable minimizing of the scanner preview

*

* @param enableMinimized indicates whether the minimizing is enabled. Default value: false.

*/

void EnableMinimizedView (bool enableMinimized)

/**

* Enable scan from gallery. If enabled, a "scan from gallery" button will appear in the scanner preview

*

* @param enabled indicates whether the "scan from gallery"  is enabled. Default value: false.

*/

void EnableScanFromGallery (bool enabled)

/**

* Enable upside-down scanning. If enabled, the scanner will also try the upside-down format of the preview.

*

* @param enabled indicates whether the "upside-down" feature  is enabled. Default value: false.

*/

 static void EnableUpsideDownScanning (bool enabled)

/**

* Turn flash on or off.

*

* @param on true = on, false = off. Default value: false.

*/

 void ToggleFlash (bool on)

/**

* If enabled, after successful scan, the scanner view will not be paused.

*

* @param enabled indicates whether the scanner should stay active after a successful scan. Default value: false.

*/

void SetContinuousScanningEnabled (bool enabled)

/**

* Ignore duplicates when scanning continuously.

*

* @param ignore indicates whether the scanner should repeat the last successful scan. Default value: false.

*/

void SetIgnoreDuplicates (bool ignore)

Xamarin.Froms

Please follow these simple steps to integrate our SDK v.1.10.x into your Xamarin.Forms project:

  1. Before we start to work in Portable (Shared) project we must to configure platform specific projects (Android and iOS):

    • Android platform specific project

    - Copy     MRZScannerAndroidBinding.dll in your Android platform specific project
    - Add reference to     MRZScannerAndroidBinding.dll file in your Android platform specific project references
    - Create one layout.axml file and add the following code:
    (It is recommended that the scanner takes full screen.)
    <fragment
                android:id="@+id/scannerFragment"
                android:name="com.scansolutions.mrzscannerlib.MRZScanner"
                android:layout_width="match_parent"
                android:layout_height="match_parent" />

    - Create     ViewRenderer that will help us to port our native fragment as control in portable project:

      public class ScannerControlRenderer : ViewRenderer
        {
           public ScannerControlRenderer(Context context) : base(context) { }

           MRZScanner mrzScanner;

           protected override void OnElementChanged(ElementChangedEventArgs<Xamarin.Forms.View> e)
        .....

- Implement the IMRZScannerListener interface as a listener for a successful MRZ scan in

MainActivity:

     public class MainActivity : 

global::Xamarin.Forms.Platform.Android.FormsAppCompatActivity, IMRZScannerListener, IMRZLicenceResultListener


• iOS platform specific project

- Copy MRZScanneriOSBinding.dll in your Android platform specific project

- Add reference to MRZScanneriOSBinding.dll file in your Android platform specific project

references

- Create ViewRenderer that will help us to port our native fragment as control in portable project and

implement IMRZScannerDelegate for a successful MRZ scan:

     public class ScannerControlRenderer : ViewRenderer, IMRZScannerDelegate
    {
     MRZScannerController mrzSannerController;

           protected override void OnElementChanged(ElementChangedEventArgs<View> e)

        ....

- Add the following row in your Info.plist file:

key: NSCameraUsageDescription
        value: MRZ Scanner requires using camera

  1. Now let’s go back in Portable project and create ScannerControl class that will inherit from Xamarin.Forms.View

      public class ScannerControl : View
     {
            public ScannerControl() { }
        
            .....


Here we can create bindable properties, event handlers, enums, etc. like we have in our sample applications.

  1. Use this custom control in you xamarin forms page where you want the scanner to be shown

<local:ScannerControl x:Name="scannerControl" HorizontalOptions="FillAndExpand" VerticalOptions="FillAndExpand" ScannerType="Mrz" IDActive="True"

PassportActive="True" VisaActive="True" MaxThreads="2"

ScanningFinished="scannerControl_ScanningFinished"

ScannerDismissed="scannerControl_ScannerDismissed"

LicenseResult="scannerControl_LicenseResult" />


CHANGELOG

- v1.10:

- v1.9:

- v1.5: