Generic Document Scanner | Cordova Document Scanner

The Scanbot SDK provides the ability to detect various types of documents in an image, crop them and recognize data fields via the Generic Document Scanner.

Currently, the Generic Document Scanner supports the following types of documents:

• German ID card
• German passport
• German driver's license

Integrating the Generic Document Scanner

The Generic Document Scanner is based on the OCR feature of the Scanbot SDK and thus requires the proper installation of the OCR language files deu.traineddata and eng.traineddata (aka. blob files).

Please refer to the OCR section for more details on how to set up OCR language files.

Use the plugin API method ScanbotSdk.UI.startGenericDocumentRecognizer() to start the Generic Document Scanner UI.

import ScanbotSdk, { GenericDocumentRecognizerConfiguration } from 'cordova-plugin-scanbot-sdk';

private SDK = ScanbotSdk.promisify();

// Always make sure you have a valid license on runtime via SDK.getLicenseInfo()
if (!licenseCheckMethod()) { return; }

const config: GenericDocumentRecognizerConfiguration = {
    // Customize colors, text resources, behavior, etc..
    orientationLockMode: "PORTRAIT",
    // see further configs...
};

const result = await this.SDK.UI.startGenericDocumentRecognizer({uiConfigs: config});

if (result.status === 'CANCELED') {
    // user has canceled the scanning operation
    return;
}

// handle the extracted data
// result.fields.surname
// result.fields.givenNames
// ...

Excluding fields from scanning

It is also possible to exclude certain fields from the scanning process altogether. When implemented, these excluded fields will not even be attempted to be recognized. This is useful for security and/or privacy reasons. All other fields will be scanned as usual. Fields should be set ONLY as normalized field names.

So to exclude the certain fields you need to use a new property excludedFieldTypes. The usage is:

const config: GenericDocumentRecognizerConfiguration = {
    ...
    excludedFieldTypes: [
        'DeIdCardFront.BirthDate',
        'DeIdCardFront.Birthplace',
    ]
};

Supported field names can be found below.

ID Card Front:

 "DeIdCardFront.BirthDate"
 "DeIdCardFront.Birthplace"
 "DeIdCardFront.ExpiryDate"
 "DeIdCardFront.GivenNames"
 "DeIdCardFront.ID"
 "DeIdCardFront.MaidenName"
 "DeIdCardFront.Nationality"
 "DeIdCardFront.PIN"
 "DeIdCardFront.Photo"
 "DeIdCardFront.Signature"
 "DeIdCardFront.Surname"

ID Card Back:

 "DeIdCardBack.Address"
 "DeIdCardBack.EyeColor"
 "DeIdCardBack.Height"
 "DeIdCardBack.IssueDate"
 "DeIdCardBack.IssuingAuthority"
 "DeIdCardBack.Pseudonym"
 "DeIdCardBack.RawMRZ"

German Passport:

 "DePassport.BirthDate"
 "DePassport.Birthplace"
 "DePassport.CountryCode"
 "DePassport.ExpiryDate"
 "DePassport.Gender"
 "DePassport.GivenNames"
 "DePassport.ID"
 "DePassport.IssueDate"
 "DePassport.IssuingAuthority"
 "DePassport.MaidenName"
 "DePassport.Nationality"
 "DePassport.PassportType"
 "DePassport.Photo"
 "DePassport.RawMRZ"
 "DePassport.Signature"
 "DePassport.Surname"

German Driver's License Front:

 "DeDriverLicenseFront.BirthDate"
 "DeDriverLicenseFront.Birthplace"
 "DeDriverLicenseFront.ExpiryDate"
 "DeDriverLicenseFront.GivenNames"
 "DeDriverLicenseFront.ID"
 "DeDriverLicenseFront.IssueDate"
 "DeDriverLicenseFront.IssuingAuthority"
 "DeDriverLicenseFront.LicenseCategories"
 "DeDriverLicenseFront.Photo"
 "DeDriverLicenseFront.Signature"
 "DeDriverLicenseFront.Surname"

German Driver's License Back:

 "DeDriverLicenseBack.Restrictions"
 "DeDriverLicenseBack.Category.Restrictions"
 "DeDriverLicenseBack.Category.ValidFrom"
 "DeDriverLicenseBack.Category.ValidUntil"

Handling the Result

The result object is described by the following interface:

export interface GenericDocumentRecognizerResult {
  documents: Array<
    | MRZDocument
    | DeIdCardFrontDocument
    | DeIdCardBackDocument
    | DePassportDocument
    | DeDriverLicenseFrontDocument
    | DeDriverLicenseBackDocument
  >;
}

The base interface which all results extend:

export interface GenericDocumentWrapper {
  /** The type of the document. */
  type: GenericDocumentNormalizedType;

  /** Confidence in result accuracy. The value ranges from 0 to 1, higher is better. */
  confidence: number;
}

DeDriverLicenseResult contains the following properties:

export interface DeDriverLicenseFrontDocument extends GenericDocumentWrapper {
    /** Surname */
    surname: Field;
    /** Given names */
    givenNames: Field;
    /** Birth date */
    birthDate: Field;
    /** Birthplace */
    birthplace: Field;
    /** Issue date */
    issueDate: Field;
    /** Issuing authority */
    issuingAuthority: Field;
    /** Expiry date */
    expiryDate: Field;
    /** Document ID number (in the top-right corner) */
    id: Field;
    /** Signature image */
    signature: Field;
    /** Driver's license categories */
    licenseCategories: Field;
}
/** German driver license (Führerschein), back side  */
export interface DeDriverLicenseBackDocument extends GenericDocumentWrapper {
    /** Restrictions applied for the driver's license */
    restrictions: Field;

    /**  Categories table row container  */
    categories: CategoriesDocument;
}

export interface CategoriesDocument extends GenericDocumentWrapper {
    /**  Contains the A sub-document. */
    a: ADocument;
    /**  Contains the A1 sub-document. */
    a1: A1Document;
    /**  Contains the A2 sub-document. */
    a2: A2Document;
    /**  Contains the B sub-document. */
    b: BDocument;
    /**  Contains the B1 sub-document. */
    b1?: B1Document;
    /**  Contains the BE sub-document. */
    be: BEDocument;
    /**  Contains the C sub-document. */
    c: CDocument;
    /**  Contains the C1 sub-document. */
    c1: C1Document;
    /**  Contains the C1E sub-document. */
    c1e: C1EDocument;
    /**  Contains the CE sub-document. */
    ce: CEDocument;
    /**  Contains the D sub-document. */
    d: DDocument;
    /**  Contains the D1 sub-document. */
    d1: D1Document;
    /**  Contains the D1E sub-document. */
    d1e: D1EDocument;
    /**  Contains the DE sub-document. */
    de: DEDocument;
    /**  Contains the L sub-document. */
    l: LDocument;
    /**  Contains the M sub-document. */
    m: MDocument;
    /**  Contains the T sub-document. */
    t: TDocument;
}

export interface CategoryDocument extends GenericDocumentWrapper {
    /** Valid from */
    validFrom: Field;
    /** Valid until */
    validUntil: Field;
    /** Restrictions */
    restrictions: Field;
}

DePassportResult contains the following properties:

export interface DePassportDocument extends GenericDocumentWrapper {
    /** Document ID number (in the top-right corner) */
    id: Field;
    /** Surname */
    surname: Field;
    /** Maiden name */
    maidenName?: Field;
    /** Given names */
    givenNames: Field;
    /** Birth date */
    birthDate: Field;
    /** Nationality */
    nationality: Field;
    /** Birthplace */
    birthplace: Field;
    /** Expiry date */
    expiryDate: Field;
    /** Passport type */
    passportType: Field;
    /** Country code */
    countryCode: Field;
    /** Gender */
    gender: Field;
    /** Signature image */
    signature: Field;
    /** Issue date */
    issueDate: Field;
    /** Issuing authority */
    issuingAuthority: Field;
    /** Raw MRZ text value */
    rawMRZ: Field;
    /**  Contains the MRZ sub-document. */
    mrz: MRZDocument;
}

MRZDocument contains the following properties

export interface MRZDocument extends GenericDocumentWrapper {
    /** Unknown */
    unknown?: Field;
    /** Document number */
    documentNumber?: Field;
    /** Issuing authority */
    issuingAuthority?: Field;
    /** Office of issuance */
    officeOfIssuance?: Field;
    /** Date of issuance */
    dateOfIssuance?: Field;
    /** Given names */
    givenNames: Field;
    /** Surname */
    surname: Field;
    /** Nationality */
    nationality: Field;
    /** Birth date */
    birthDate: Field;
    /** Gender */
    gender?: Field;
    /** Expiry date */
    expiryDate?: Field;
    /** Personal number */
    personalNumber?: Field;
    /** Travel document type */
    travelDocType?: Field;
    /** Travel document type variant */
    travelDocTypeVariant?: Field;
    /** Optional 1 */
    optional1?: Field;
    /** Optional 2 */
    optional2?: Field;
    /** Document type code */
    documentTypeCode?: Field;
    /** PIN code */
    pinCode?: Field;
    /** Language code */
    languageCode?: Field;
    /** Version number */
    versionNumber?: Field;
    /** Check digit document number */
    checkDigitDocumentNumber?: Field;
    /** Check digit birth date */
    checkDigitBirthDate?: Field;
    /** Check digit expiry date */
    checkDigitExpiryDate?: Field;
    /** Check digit personal number */
    checkDigitPersonalNumber?: Field;
    /** Check digit general */
    checkDigitGeneral?: Field;
}

DeIdCardResult contains the following properties:

/** German ID card, front side  */
export interface DeIdCardFrontDocument extends GenericDocumentWrapper {
    /** Document ID number (in the top-right corner) */
    id: Field;
    /** Surname */
    surname: Field;
    /** Maiden name */
    maidenName?: Field;
    /** Given names */
    givenNames: Field;
    /** Birth date */
    birthDate: Field;
    /** Nationality */
    nationality: Field;
    /** Birthplace */
    birthplace: Field;
    /** Expiry date */
    expiryDate: Field;
    /** PIN */
    pin: Field;
    /** Signature image */
    signature: Field;
}

/** German ID card, back side  */
export interface DeIdCardBackDocument extends GenericDocumentWrapper {
    /** Eye color */
    eyeColor: Field;
    /** Height */
    height: Field;
    /** Issue date */
    issueDate: Field;
    /** Issuing authority */
    issuingAuthority: Field;
    /** Address */
    address: Field;
    /** Pseudonym */
    pseudonym: Field;
    /** Raw MRZ text value */
    rawMRZ: Field;
    /**  Contains the MRZ sub-document. */
    mrz: MRZDocument;
}

Field contains the following properties:

export interface Field {
    /** Optional value of the field */
    value?: FieldValue;

    /** Field validation status. Applicable only to fields that support some kind of validation. */
    validationStatus?: ValidationStatus;
}

Customization

The UI and the behavior of the Generic Document Scanner can be customized by passing the configs value via GenericDocumentRecognizerConfiguration. All configuration options are optional.

export interface GenericDocumentRecognizerConfiguration {
    /** Controls whether the flash should be initially enabled. The default value is FALSE. */
    flashEnabled?: boolean;

    /** UI Interface orientation lock mode */
    orientationLockMode?: OrientationLockMode;

    /** The preferred camera module (default - BACK) */
    cameraModule?: CameraModule;

    /** The background color of the top toolbar. */
    topBarBackgroundColor?: string;

    /** The color of all active toggle buttons in the toolbar. */
    topBarButtonsActiveColor?: string;

    /** The color of all inactive toggle buttons in the toolbar. */
    topBarButtonsInactiveColor?: string;

    /** Background color outside of the finder window. */
    cameraOverlayColor?: string;

    /** Foreground color of the detection overlay. */
    finderLineColor?: string;

    /** Width of finder frame border. Default is 2. */
    finderLineWidth?: number;

    /** Text color of the fields count label. */
    fieldsCountTextColor?: string;

    /** Color of confidence value label background in details screen, when the field confidence level is high. */
    fieldConfidenceHighColor?: string;

    /** Color of confidence value label background in details screen, when the field confidence level is moderate. */
    fieldConfidenceModerateColor?: string;

    /** Color of confidence value label background in details screen, when the field confidence level is low. */
    fieldConfidenceLowColor?: string;

    /** Color of confidence value label text in details. */
    fieldConfidenceTextColor?: string;

    /** Color of tip text on scanning screen. */
    tipTextColor?: string;

    /** Color of tip background on scanning screen. */
    tipBackgroundColor?: string;

    /** The color of bottom sheet */
    detailsBackgroundColor?: string;

    /** The color of text elements in bottom sheet */
    detailsPrimaryColor?: string;

    /** The color of Submit button */
    detailsActionColor?: string;

    /** Text color for section headers on the details screen. iOS only. */
    detailsSectionHeaderTextColor?: string;

    /** Background color for section headers on the details screen. iOS only. */
    detailsSectionHeaderBackgroundColor?: string;

    /** Title of the cancel button. */
    cancelButtonTitle?: string;

    /** Whether the cancel button is hidden or not. iOS only. */
    cancelButtonHidden?: boolean;

    /** String used for displaying amount of detected fields. Use %d for number formatting symbol. */
    clearButtonTitle?: string;

    /** Text of the button which finishes the flow */
    submitButtonTitle?: string;

    /** String used for displaying amount of detected fields. Use %d for number formatting symbol. */
    fieldsCountText?: string;

    /** String that shows average confidence value of scanned document. Use %d as number formatting symbol. */
    confidenceValue?: string;

    /** String that asks user to scan back side of a document. */
    scanBackSideTitle?: string;

    /** String that asks user to scan front side of a document. */
    scanFrontSideTitle?: string;

    /** String that asks user to start scanning a document. */
    startScanningTitle?: string;

    /** String that notifies that both sides of document are scanned. */
    scannedEverythingTitle?: string;

    /** String being displayed for empty values. iOS only. */
    emptyValueTitle?: string;

    /** Title of the button that opens the screen where the user can allow the usage of the camera by the app. */
    enableCameraButtonTitle?: string;

    /** Text that will be displayed when the app is not allowed to use the camera, prompting the user to enable the usage of the camera. */
    enableCameraExplanationText?: string;

    /** A title to show image content. Android only. */
    imageTitle?: string;

    /** String that notifies that nothing was scanned yet. */
    noDataTitle?: string;

    /** Accepted document types. All other document types will be ignored. By default - All types */
    acceptedDocumentTypes?: GenericDocumentType[];

    /** Accepted minimal sharpness score. Images with a score less than that will be rejected with RecognitionStatus::ErrorTooBlurry. Default is 80. 0 - any image will be accepted. 80 - a good compromise; the recommended setting. 100 - only very sharp images will be accepted. */
    sharpnessAcceptanceFactor?: number;

    /** Allows to configure the display configuration for fields. */
    fieldsDisplayConfiguration?: FieldsDisplayConfiguration[];

    /** Allows to configure the display configuration for documents. */
    documentsDisplayConfiguration?: DocumentsDisplayConfiguration[];

    /** List of secure fields which should be excluded from scanning process. All other fields will be scanned as usual. Field should be set ONLY as normalized field name. Example - [DePassport.BirthDate] or [DePassport.Birthplace] */
    excludedFieldTypes?: string[];

    /** Controls whether the flash toggle button is hidden or not. */
    flashButtonHidden?: boolean;

    /** Title of the flash toggle button. */
    flashButtonTitle?: string;

    /** Controls whether buttons should use all capitals style, as defined by the Android Material Design. Defaults to TRUE. Android only. */
    useButtonsAllCaps?: boolean;

    /** If `true`, replaces the cancel button in the top bar with a back arrow icon. The default value is FALSE. Android only. */
    replaceCancelButtonWithIcon?: boolean;

    /** Preview mode of the camera. FILL_IN or FIT_IN. Default is FILL_IN. Android only */
    cameraPreviewMode?: CameraPreviewMode;

    /** Whether touch-to-focus is enabled on camera preview. Enabled by default. Android only. */
    touchToFocusEnabled?: boolean;
}

Want to scan longer than one minute?

Generate a free trial license to test the Scanbot SDK thoroughly.

Get your free Trial License

What do you think of this documentation?

What can we do to improve it? Please be as detailed as you like.

---