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..
  shouldSavePhotoImageInStorage: true,
  // 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 contains the following fields:

• documentType: GenericDocumentType may be one of the following document types 'DeDriverLicense', 'DePassport', 'DeIdCard'
• status: 'OK' if data was extracted, 'CANCELED' if the user canceled the operation (tapped on the "cancel" button).
• fields: GenericDocumentFields An object with extracted data fields.

The fields property will be of type GenericDocumentFields. According to documentType, fields will be one of the interfaces below:

type GenericDocumentFields =
    DeDriverLicenseResult
    | DePassportResult
    | DeIdCardResult
    ;

DeDriverLicenseResult contains the following properties:

interface DeDriverLicenseResult {
    birthDate?: GenericDocumentField;
    birthplace?: GenericDocumentField;
    expiryDate?: GenericDocumentField;
    givenNames?: GenericDocumentField;
    id?: GenericDocumentField;
    issueDate?: GenericDocumentField;
    issuingAuthority?: GenericDocumentField;
    licenseCategories?: GenericDocumentField;
    photoImageUri?: string;
    signatureImageUri?: string;
    surname?: GenericDocumentField;
    restrictions?: GenericDocumentField;
    categories?: DriverLicenseCategories;
}

interface DriverLicenseCategories {
    a?: DriverLicenseCategory;
    a1?: DriverLicenseCategory;
    a2?: DriverLicenseCategory;
    b?: DriverLicenseCategory;
    b1?: DriverLicenseCategory;
    be?: DriverLicenseCategory;
    c?: DriverLicenseCategory;
    c1?: DriverLicenseCategory;
    c1e?: DriverLicenseCategory;
    ce?: DriverLicenseCategory;
    d?: DriverLicenseCategory;
    d1?: DriverLicenseCategory;
    d1e?: DriverLicenseCategory;
    de?: DriverLicenseCategory;
    l?: DriverLicenseCategory;
    m?: DriverLicenseCategory;
    t?: DriverLicenseCategory;
}

interface DriverLicenseCategory {
    restrictions?: GenericDocumentField;
    validFrom?: GenericDocumentField;
    validUntil?: GenericDocumentField;
}

DePassportResult contains the following properties:

interface DePassportResult {
    birthDate?: GenericDocumentField;
    birthplace?: GenericDocumentField;
    countryCode?: GenericDocumentField;
    expiryDate?: GenericDocumentField;
    gender?: GenericDocumentField;
    givenNames?: GenericDocumentField;
    id?: GenericDocumentField;
    issueDate?: GenericDocumentField;
    issuingAuthority?: GenericDocumentField;
    maidenName?: GenericDocumentField;
    nationality?: GenericDocumentField;
    passportType?: GenericDocumentField;
    photoImageUri?: string;
    rawMrz?: GenericDocumentField;
    signatureImageUri?: string;
    surname?: GenericDocumentField;
    mrz?: MrzDocumentResult;
}

interface MrzDocumentResult {
    birthDate?: GenericDocumentField;
    checkDigits?: GenericDocumentField[];
    documentNumber?: GenericDocumentField;
    expiryDate?: GenericDocumentField;
    gender?: GenericDocumentField;
    givenNames?: GenericDocumentField;
    issuingAuthority?: GenericDocumentField;
    nationality?: GenericDocumentField;
    optional1?: GenericDocumentField;
    optional2?: GenericDocumentField;
    surname?: GenericDocumentField;
    travelDocType?: GenericDocumentField;
    travelDocTypeVariant?: GenericDocumentField;
}

DeIdCardResult contains the following properties:

interface DeIdCardResult {
    birthDate?: GenericDocumentField;
    birthplace?: GenericDocumentField;
    expiryDate?: GenericDocumentField;
    givenNames?: GenericDocumentField;
    id?: GenericDocumentField;
    maidenName?: GenericDocumentField;
    nationality?: GenericDocumentField;
    pin?: GenericDocumentField;
    photoImageUri?: string;
    signatureImageUri?: string;
    surname?: GenericDocumentField;
    address?: GenericDocumentField;
    eyeColor?: GenericDocumentField;
    height?: GenericDocumentField;
    issueDate?: GenericDocumentField;
    issuingAuthority?: GenericDocumentField;
    pseudonym?: GenericDocumentField;
    rawMrz?: GenericDocumentField;
}

GenericDocumentField contains the following properties:

interface GenericDocumentField {
    text?: string;
    confidence?: number;
}

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.

interface GenericDocumentRecognizerConfiguration {
    /**
     * Accepted document types. All other document types will be ignored.
     * All by default - DeIdFront, DeIdBack, DePassport, DeDriverLicenseFront and DeDriverLicenseBack
     */
    acceptedDocumentTypes?: RootDocumentType[]
    /**
    * Background color of the detection overlay.
    */
    cameraOverlayColor?: string;
    /**
     * Whether the cancel button is hidden or not. (iOS only)
     */
    cancelButtonHidden?: boolean;
    /**
     * Title of the cancel button.
     */
    cancelButtonTitle?: string;
    /**
     * Title of the clear button.
     */
    clearButtonTitle?: string;
    /**
     * String that shows average confidence value of scanned card. Use %d as number formatting symbol.
     */
    confidenceValue?: string;
    /**
     * Foreground color of the top bar buttons on the details screen.
     */
    detailsActionColor?: string;
    /**
     * Background color of the details screen.
     */
    detailsBackgroundColor?: string;
    /**
     * Text color in the details list. Also affects image background and separator.
     */
    detailsPrimaryColor?: string;
    /**
     * Foreground color of the detection overlay.
     */
    finderLineColor?: string;
    /**
     * Width of finder frame border. Default is 2.
     */
    finderLineWidth?: number;
    /**
     * Whether the flashlight is toggled on or off.
     */
    flashEnabled?: boolean;
    /**
     * A title to show image content.
     */
    imageTitle?: string;
    /**
     * String that notifies that nothing was scanned yet.
     */
    noDataTitle?: string;
    /**
     * String that asks user to scan back side of a card.
     */
    scanBackSideTitle?: string;
    /**
     * String that asks user to scan front side of a card.
     */
    scanFrontSideTitle?: string;
    /**
     * String that notifies that both sides of card are scanned.
     */
    scannedEverythingTitle?: string;
    /**
     * Defines if photo image should be stored in internal storage on disk.
     */
    shouldSavePhotoImageInStorage?: boolean;
    /**
     * Defines if signature image should be stored in internal storage on disk.
     */
    shouldSaveSignatureImageInStorage?: boolean;
    /**
     * String that asks user to start scanning a card.
     */
    startScanningTitle?: string;
    /**
     * Title of the submit button.
     */
    viewResultsButtonTitle?: string;
    /**
     * Color of tip background on scanning screen.
     */
    tipBackgroundColor?: string;
    /**
     * Color of tip text on scanning screen.
     */
    tipTextColor?: string;
    /**
     * Background color of the top bar.
     */
    topBarBackgroundColor?: string;
    /**
     * Foreground color of the top bar buttons on the scanning screen.
     */
    topBarButtonsColor?: string;
    /**
     * Foreground color of the flash button when flash is off.
     */
    topBarButtonsInactiveColor?: string;
    /**
     * Controls whether buttons should use all capitals style, as defined by Android Material Design. Defaults to TRUE.
     * Android only.
     */
    useButtonsAllCaps?: boolean;
    /**
     * The accepted minimal sharpness score. Images with a score less than this will
     * be rejected with a blurry status.
     *
     * 0 - any image will be accepted.
     * 80 - a good compromise; the recommended setting.
     * 100 - only very sharp images will be accepted.
     *
     * The default value is 80.
     */
    sharpnessAcceptanceFactor?: number;
    /**
     * Orientation lock mode of the UI, the camera preview, and the output images.
     * By default the orientation is not locked.
     */
    interfaceOrientation?: UIInterfaceOrientationMask;
    /**
     * 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;
    /**
     * Title of the button that opens the screen where the user can allow
     * the usage of the camera by the app.
     */
    enableCameraButtonTitle?: string;
    /**
     * Text color of the fields count label.
     */
    fieldsCountTextColor?: string;
    /**
     * String used for displaying amount of detected fields. Use %d for number formatting symbol.
     */
    fieldsCountText?: 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;
    /**
     * Configuration of document fields shown in details screen
     */
    detailsFieldConfiguration?: GenericDocumentFieldConfiguration;
    /**
     * 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[];
}

export interface GenericDocumentFieldConfiguration {
    /**
     * A title for IdCardBack in details screen.
     */
    deIdCardBackDocumentTitle?: string;
    /**
     * A title for IdCardFront in details screen.
     */
    deIdCardFrontDocumentTitle?: string;
    /**
     * A title for Passport in details screen.
     */
    dePassportDocumentTitle?: string;
    /**
     * A title for DriverLicenseBack in details screen.
     */
    deDriverLicenseBackDocumentTitle?: string;
    /**
     * A title for DriverLicenseFront in details screen.
     */
    deDriverLicenseFrontDocumentTitle?: string;
    /**
     * A title for address field in details screen.
     */
    fieldAddressTitle?: string;
    /**
     * A title for birth date field in details screen.
     */
    fieldBirthDateTitle?: string;
    /**
     * A title for birthplace field in details screen.
     */
    fieldBirthPlaceTitle?: string;
    /**
     * A title for country code field in details screen.
     */
    fieldCountryCodeTitle?: string;
    /**
     * A title for expiry date field in details screen.
     */
    fieldExpiryDateTitle?: string;
    /**
     * A title for eye color field in details screen.
     */
    fieldEyeColorTitle?: string;
    /**
     * A title for gender field in details screen.
     */
    fieldGenderTitle?: string;
    /**
     * A title for given names field in details screen.
     */
    fieldGivenNamesTitle?: string;
    /**
     * A title for height field in details screen.
     */
    fieldHeightTitle?: string;
    /**
     * A title for id field in details screen.
     */
    fieldIdTitle?: string;
    /**
     * A title for issuing date field in details screen.
     */
    fieldIssueDateTitle?: string;
    /**
     * A title for issuing authority field in details screen.
     */
    fieldIssuingAuthorityTitle?: string;
    /**
     * A title for maiden name field in details screen.
     */
    fieldMaidenNameTitle?: string;
    /**
     * A title for machine readable zone field in details screen.
     */
    fieldRawMrzTitle?: string;
    /**
     * A title for nationality field in details screen.
     */
    fieldNationalityTitle?: string;
    /**
     * A title for passport type field in details screen.
     */
    fieldPassportTypeTitle?: string;
    /**
     * A title for photo field in details screen.
     */
    fieldPhotoTitle?: string;
    /**
     * A title for PIN field in details screen.
     */
    fieldPinTitle?: string;
    /**
     * A title for pseudonym field in details screen.
     */
    fieldPseudonymTitle?: string;
    /**
     * A title for signature field in details screen.
     */
    fieldSignatureTitle?: string;
    /**
     * A title for surname field in details screen.
     */
    fieldSurnameTitle?: string;
    /**
     * A title for restrictions for the driver's license in details screen.
     */
    fieldRestrictionsTitle?: string;
    /**
     * A title for driver's license categories in details screen.
     */
    fieldLicenseCategoriesTitle?: string;
}

Want to scan longer than one minute?

Generate your free "no-strings-attached" Trial License and properly test the Scanbot SDK.

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.

---