ID Capture

The IDCapture module offers you the opportunity to automatically capture the document and upload it. According to the upload result, you can listen whether the document is approved or not.

Flow overviewFlowchart of this module's usage within the SDK flow. Expand to view it, click the chart to enlarge.

Configure with ID_CAPTURE and NFC_SCAN, set the event listener with AmaniEvent().setListener(...) (the verdicts arrive there, asynchronously, during the whole session), then start the session.
N1: set the manual button timeout with setManualCropTimeOut(...), then capture the ID front and back. No bitmap yet means the user has not captured yet; the module stays open. After the timeout set with setManualCropTimeOut(...), the user can capture with the manual button. If there is still no capture, count 20–30 seconds on your side after the button appears and handle the process as you need.
N2: read the MRZ with getMRZ(...); if it fails, let the user type it or capture the ID again.
N3: if the device has NFC turned on, enable the foreground dispatch in onResume and disable it in onPause; otherwise skip the chip.
N4: onNewIntent brings the tag when the card touches the phone; start ScanNFC().start(...) there with the MRZ values from getMRZ (they are String?: check them in N2); retry if it fails.
N5, or N6 + N7: upload the chip on its own, or merge it into the ID upload with withNFC(true). On V2 a successful upload means the document reached the server; its verdict arrives later in stepsResult. If the upload fails or the step is REJECTED, do not call upload() again: the data is cleared after it. Open the ID capture and the chip scan again (a new fragment, or the old one with your own fragment handling, e.g. popBackStack), capture, then upload, up to your own max attempt.

Starting the Capture

↑ Flow step N1

start method returns a Fragment of the IDCapture.

note

docType parameter here is supplied by Amani to it's customers.

Add the imports below:

import ai.amani.sdk.Amani
import android.graphics.Bitmap
import androidx.fragment.app.Fragment
import java.io.File

Then start the capture and get its Fragment as shown below:

val fragment: Fragment? = Amani.sharedInstance().IDCapture().start(
    this, //Context of the Application
    frameLayout, //FrameLayout where the current IDCapture fragment will be fit in
    docType, // Type of the document
    false // Boolean value for frontSide/backSide, set true for frontSide, set false for backSide
) { bitmap: Bitmap?, b: Boolean?, file: File? ->

    bitmap?.let {
        //Current document is captured, upload method of current module can be triggered.
        
    }
}
replaceFragmentWithBackStack(R.id.id_frame_layout, fragment!!)

Configuration Settings

The hologramDetection(hologramDetection: Boolean = false) function enables or disables the detection of holograms during the ID capture process. When hologram detection is enabled, the system will actively analyze the document for holograms, improving the accuracy of detection in cases where holographic elements are present. This feature is particularly useful for documents with security features that may otherwise affect the capture process. If disabled, the capture process will proceed without checking for holograms, allowing for faster processing but with less accuracy for documents containing holograms. It should be called just before the Amani.sharedInstance().IDCapture().start(...) function.

Add the imports below:

import ai.amani.sdk.Amani

Then enable hologram detection as shown below:

  Amani.sharedInstance().IDCapture().hologramDetection(true)

The videoRecord(isRecording: Boolean = true) function enables or disables the video recording feature during the ID capture process. When video recording is enabled, the system will continuously record the capture session, which can be useful for auditing or additional analysis. If disabled, the capture will proceed without recording, allowing for a streamlined process without the overhead of video storage.

  Amani.sharedInstance().IDCapture().videoRecord(true)

The setManualCropTimeOut() sets the manual capture button of the IDCapture fragment for the situations where AutoCapture can fail. When the manual crop button is enabled, user will have a chance to capture the document manually for unexpected situations. It must be called just before the Amani.sharedInstance().IDCapture().start(...) function.

If you did not called this method. It will use the default value as 30 seconds.

warning

You must not set a value lower than 15 seconds for setManualCropTimeOut().
The Amani SDK requires a minimum timeout of 15 seconds.

// You don't need to call this as the default manual crop timeout is
// 30 seconds.
  Amani.sharedInstance().IDCapture().setManualCropTimeOut(30)

The setIsMRZReaderEnabled(enable: Boolean = true) function controls whether the MRZ (Machine Readable Zone) reader is enabled during the ID capture process. When enabled, the system will scan and extract data from the MRZ section of the document, improving accuracy and efficiency for documents with this feature. If disabled, MRZ scanning is skipped, allowing for a simplified capture process in cases where MRZ data is not required. It must be called just before the Amani.sharedInstance().IDCapture().start(...) function.

  Amani.sharedInstance().IDCapture().setIsMRZReaderEnabled(true)

The withNFC(withNFC: Boolean = false) function determines whether NFC data should be combined with the ID capture data during the upload process. When enabled, the system will merge both NFC and captured ID data into a single document for upload, ensuring that all available information is consolidated. If disabled, only the ID capture data is uploaded without the additional NFC data. It must be called just before the Amani.sharedInstance().IDCapture().upload(...) function. In this way, the relevant upload process is carried out with NFC.

  Amani.sharedInstance().IDCapture().withNFC(true)

Getting the MRZ Data for Scanning the NFC

↑ Flow step N2

The getMRZ() method fetches the required data groups for scanning the NFC.

note

This method is used to capture the NFC Data Group required for the NFC Scanning in cases where only the back side is taken. It is optional as you don't need the call this method if you have the required data for scanning the NFC.

note

docType is supplied by Amani to it's customers.

Add the imports below:

import ai.amani.sdk.Amani

Then fetch the MRZ data as shown below:

        Amani.sharedInstance().IDCapture().getMRZ(
            type = docType,
            onComplete = { mrz ->
                /* Mrz model will be fetched in this section. This data model contains required values
                for scanning NFC.

                For scanning NFC with the response of Mrz request, the following values can be used in ScanNFC.start(_,_,_) function ->

                    mrz.mRZBirthDate, 
                    mrz.mRZExpiryDate, 
                    mrz.mRZDocumentNumber
                   
                */
            },
            onError = {

            }

        )

Uploading the captured document

↑ Flow steps N6 N7

The upload method has to be called after both front and back sides, and if using nfc capture, after the nfc capture process is completed. Otherwise, you'll encounter with an Error() object after the upload function is called.

[!IMPORTANT]
If the captured identity document contains NFC and this document is desired to be uploaded together with NFC, the following withNFC(true) method is set to true before upload, ensuring that the NFC data and the captured document are uploaded together as a single document.

Add the imports below:

import ai.amani.sdk.Amani

Then upload the captured document as shown below:

Amani.sharedInstance().IDCapture().withNFC(true/false)

Amani.sharedInstance().IDCapture().upload(                 
    this,                                                  
    docType                                                
) { isSuccess ->                                           
    if (isSuccess) {                                       
        Log.i(TAG, "ID upload succeeded")                       
    } else {                                               
        Log.i(TAG, "ID upload did not succeed")         
    }                                                      
}                                                          

note

A true result means different things per backend version. V2: the document reached the server, not that it was approved; verification runs asynchronously on the backend, so the outcome arrives later through the event listener rather than here. V1: the upload response status was OK or PENDING_REVIEW, so true already carries the verdict.

Alternatively, if you need the ID of the uploaded document, pass the uploadCallBack { ... } helper instead of the callback above. Everything else stays the same:

import ai.amani.sdk.interfaces.uploadCallBack

Amani.sharedInstance().IDCapture().upload(
    this,
    docType,
    uploadCallBack { isSuccess, documentID ->
            // isSuccess is true when the document is uploaded
            // documentID is the ID of the uploaded document
    }
)

Starting the Capture​

Configuration Settings​

Getting the MRZ Data for Scanning the NFC​

Uploading the captured document​

Starting the Capture

Configuration Settings

Getting the MRZ Data for Scanning the NFC

Uploading the captured document