Hands-on Example

Introduction

MobbScan uses a set of methods and listeners to allow flexibility during the integration of the library in a Xamarin application.

The basic workflow consists on:

1. Initialize the API
2. Configure the API
3. Start a document scanning
4. Scan a document

Basic example

In this section we will be making use of the code of our demo application to explain this basic workflow. The application displays a screen with buttons to trigger every one of the workflow steps.

The first step is initializating the MobbScan API. We add a property in our MainPage class to keep a reference to the API object.

/* MainPage.xaml.cs */

private IXMobbScanAPI MobbScanAPI { set; get; };

The property is assigned the IXMobbScanAPI implementation resolved by the dependency service of Xamrin.Forms. Now it is time to init the API. All this happens within the click event handler of the Init API button:

/* MainPage.xaml.cs */

BtnInitApi.Clicked += (sender, e) => 
{
    MobbScanAPI = DependencyService.Get<IXMobbScanAPI>();
    MobbScanAPI.Init("your_license", this);
}

Almost every feature in MobbScan API is asynchronous and thus they need a listener to callback when the action is done. In the previous code we use this as the second argument passed in to the initialization method. Our MainPage class implements this listener as follows:

/* MainPage.xaml.cs */

public partial class MainPage : ContentPage, IXLicenseStatusListener, IXScanStartListener, IXIdDocumentDetectionListener, IXIdDocumentScanListener
{
    ...

    void IXLicenseStatusListener.LicenseStatusChecked(XMobbScanLicenseResult result, DateTime validTo)
    {
        if (result == XMobbScanLicenseResult.Valid)
        {
            MobbScanAPI.BaseUrl = "https://demo.mobbeel.com";
            MobbScanAPI.APIMode = XMobbScanAPIMode.Online;

            BtnStartScan.IsEnabled = true;
        }
    }

As you may have noticed, if the initialization was successful we followed the workflow by configuring the API and enabling the third step to be carried out.

Now it is time to start a scanning process. The Start Scan button is set to handle the click event like this:

/* MainPage.xaml.cs */

BtnStartScan.Clicked += (sender, e) =>
{
    MobbScanAPI.StartScan(XMobbScanDocumentType.ESPIDCard, XMobbScanOperationMode.ScanBothSides, this);
};

Likewise the Init method, our MainPage class is implementing the IXScanStartListener and it can be passed in to the StartScan method as the third argument.

/* MainPage.xaml.cs */

public partial class MainPage : ContentPage, IXLicenseStatusListener, IXScanStartListener, IXIdDocumentDetectionListener, IXIdDocumentScanListener
{
    ...

    void IXScanStartListener.ScanStarted(XMobbScanStartScanResult result, string scanId, XMobbScanAPIError? error)
    {        
        if (result == XMobbScanStartScanResult.Ok)
        {
            this.scanId = scanId;
            BtnScanFront.IsEnabled = true;
            BtnScanBack.IsEnabled = true;
        }
        ...
    }

If the start scanning processs is started successfully, we store the received scanId in a class field as it will be needed later. Besides, we enable the buttons to trigger the last step.

Our Scan Front Side and Scan Back Side buttons will handle their click event this way:

/* MainPage.xaml.cs */

BtnScanFront.Clicked += (sender, e) =>
{
    MobbScanAPI.ScanDocument(XMobbScanDocumentSide.Front, scanId, this, this);
};
BtnScanBack.Clicked += (sender, e) =>
{
    MobbScanAPI.ScanDocument(XMobbScanDocumentSide.Back, scanId, this, this);
};

In the case of ScanDocument method, our MainPage instance is passed in twice. The reason is that this method will callback in two events: the moment the document is detected and when the document scanning is finished. The implementation of both listeners is displayed below:

/* MainPage.xaml.cs */
    
void IXIdDocumentDetectionListener.IdDocumentDetected(XMobbScanDetectionResult result, XMobbScanDetectionResultData? data, XMobbScanAPIError? error)
{
    if (result == XMobbScanDetectionResult.Ok)
    {
        XMobbScanDetectionResultData resultData = data.Value;
        if (resultData.documentSide == XMobbScanDocumentSide.Front)
        {
            ImgFront.Source = resultData.image;
        }
        else
        {
            ImgBack.Source = resultData.image;
        }
    }
    ...
}

void IXIdDocumentScanListener.IdDocumentScanned(XMobbScanScanResult result, XMobbScanScanResultData? data, XMobbScanAPIError? error)
{
    if (result == XMobbScanScanResult.Completed)
    {
        XIdDocument idDocument = data.Value.idDocument;
        LblData.Text = $"Document number: {idDocument.documentNumber}" + Environment.NewLine +
            $"Personal number: {idDocument.personalNumber}" + Environment.NewLine +
            $"MRZ: {idDocument.mrz}" + Environment.NewLine +
            $"Expiry date: {idDocument.dateOfExpiry}" + Environment.NewLine +
            $"Issuing state: {idDocument.issuingState}" + Environment.NewLine +
            $"Name: {idDocument.name}" + Environment.NewLine +
            $"Surname: {idDocument.surname}" + Environment.NewLine +
            $"First surname: {idDocument.firstSurname}" + Environment.NewLine +
            $"Second surname: {idDocument.secondSurname}" + Environment.NewLine +
            $"Nationality: {idDocument.nationality}" + Environment.NewLine +
            $"Birth date: {idDocument.dateOfBirth}" + Environment.NewLine +
            $"Gender: {idDocument.gender}" + Environment.NewLine;
    }
    ...
}

The instant the document is detected MobbScan API callbacks providing us with the capture of the document. We use this picture as the source of an Image that we display on our page.

The scanning process goes on until it finishes and IXIdDocumentScanListener is notified of this event. At this point, we are provided with the data extracted from our document. We display the scanned data in a label to show the result.

This is a simple example of how MobbScan can be integrated in your application. Please, visit the rest of documents within the Usage section for further details.