Skip to main content

Generic Document Recognizer | React Native Generic Document Recognizer

Generic Document Recognizer

ScanbotSdk.UI.startGenericDocumentRecognizer(configuration: GenericDocumentRecognizerConfiguration): Promise

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 Recognizer.

alt

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

  • German ID Card
  • German Passport
  • German Driver's license

The Generic Document Recognizer is based on the OCR feature and thus requires the proper installation of the OCR language files deu.traineddata and eng.traineddata (aka. blob files). For more details on how to set up OCR language files please refer to the OCR section.

Use the API method ScanbotSdk.UI.startGenericDocumentRecognizer(configuration: GenericDocumentRecognizerConfiguration): Promise<GenericDocumentRecognizerResult> to start the Generic Document Recognizer Ready-To-Use UI.

Result:

The promise resolves to a result object with the following properties:

  • status - 'OK' if the recognition was successful. 'CANCELED' if the user canceled the operation (tapped on the "cancel" button).
  • documentType - the recognized document type
  • fields - the recognized document fields

Document Type:

The document type can be one of the following:

export type GenericDocumentType =
/** German ID card, front side */
| 'DeIdCardFront'
/** German ID card, back side */
| 'DeIdCardBack'
/** German travel passport (Reisepass) */
| 'DePassport'
/** German driver license (Führerschein), front side */
| 'DeDriverLicenseFront'
/** German driver license (Führerschein), back side */
| 'DeDriverLicenseBack';

Fields:

The type of 'fields' varies depending on the documentType. It can either be:

  • DeDriverLicenseResult
  • DePassportResult
  • DeIdCardResult

Depending on the expected result, you can cast the fields property to the needed type:

if (result.documentType == 'DeIdCardFront' || result.documentType == 'DeIdCardBack') {
let idCardFields = result.fields as DeIdCardResult;
console.log("Address: " + idCardFields.address?.text ?? "-");
// etc ...
}

Configuration

To only recognize a specific type of document, you can use the acceptedDocumentTypes property.

For example, if you only want to recognize German ID Cards, you can use the following configuration:

let config: GenericDocumentRecognizerConfiguration = {
// Enables recognition for german ID cards only (front and back)
acceptedDocumentTypes: ['DeIdCardFront', 'DeIdCardBack']
}

Here you can read all the properties available in 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;

/** Title of the clear button. */
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 this 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 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;
}

Normalized Names

When setting properties like fieldsDisplayConfiguration, documentsDisplayConfiguration or excludedFieldTypes you will need to specify the fields or documents you want to apply the configuration to.

In order to do this, you should use our normalized name convention which is the following:

const normalizedName = `${DOCUMENT_NAME}.${FIELD_NAME}`

In case of MRZ fields you would use the following name:

const normalizedName = `${DOCUMENT_NAME}.MRZ.${FIELD_NAME}`

Constants

If you only need to specify a few fields, you can refer to the available documents and fields section.

Otherwise, if you don't want to hard-code your normalized names, you can follow the approach described below.

The normalized names will be exposed as constants starting from version v4.15.3 of the SDK:

import {GenericDocumentNormalizedFields} from 'react-native-scanbot-sdk'

Allowing you to specify field names like this:

const normalizedName = GenericDocumentNormalizedFields.DeIdCardBack.MrzFields.DOCUMENT_NUMBER;

For lower versions, you can manually copy these utility objects in your project if needed:

export const GenericDocumentNormalizedFields = {
DeDriverLicenseBack: {
/** Normalized field type name of the "Restrictions" document field. */
RESTRICTIONS: 'DeDriverLicenseBack.Restrictions',
Category: {
/** Normalized field type name of the "Restrictions" document field. */
RESTRICTIONS: 'DeDriverLicenseBack.Category.Restrictions',
/** Normalized field type name of the "ValidFrom" document field. */
VALID_FROM: 'DeDriverLicenseBack.Category.ValidFrom',
/** Normalized field type name of the "ValidUntil" document field. */
VALID_UNTIL: 'DeDriverLicenseBack.Category.ValidUntil'
},
},
DeDriverLicenseFront: {
/** Normalized field type name of the "BirthDate" document field. */
BIRTH_DATE: 'DeDriverLicenseFront.BirthDate',
/** Normalized field type name of the "Birthplace" document field. */
BIRTHPLACE: 'DeDriverLicenseFront.Birthplace',
/** Normalized field type name of the "ExpiryDate" document field. */
EXPIRY_DATE: 'DeDriverLicenseFront.ExpiryDate',
/** Normalized field type name of the "GivenNames" document field. */
GIVEN_NAMES: 'DeDriverLicenseFront.GivenNames',
/** Normalized field type name of the "ID" document field. */
ID: 'DeDriverLicenseFront.ID',
/** Normalized field type name of the "IssueDate" document field. */
ISSUE_DATE: 'DeDriverLicenseFront.IssueDate',
/** Normalized field type name of the "IssuingAuthority" document field. */
ISSUING_AUTHORITY: 'DeDriverLicenseFront.IssuingAuthority',
/** Normalized field type name of the "LicenseCategories" document field. */
LICENSE_CATEGORIES: 'DeDriverLicenseFront.LicenseCategories',
/** Normalized field type name of the "Photo" document field. */
PHOTO: 'DeDriverLicenseFront.Photo',
/** Normalized field type name of the "Signature" document field. */
SIGNATURE: 'DeDriverLicenseFront.Signature',
/** Normalized field type name of the "Surname" document field. */
SURNAME: 'DeDriverLicenseFront.Surname',
},
DeIdCardBack: {
/** Normalized field type name of the "Address" document field. */
ADDRESS: 'DeIdCardBack.Address',
/** Normalized field type name of the "EyeColor" document field. */
EYE_COLOR: 'DeIdCardBack.EyeColor',
/** Normalized field type name of the "Height" document field. */
HEIGHT: 'DeIdCardBack.Height',
/** Normalized field type name of the "IssueDate" document field. */
ISSUE_DATE: 'DeIdCardBack.IssueDate',
/** Normalized field type name of the "IssuingAuthority" document field. */
ISSUING_AUTHORITY: 'DeIdCardBack.IssuingAuthority',
/** Normalized field type name of the "Pseudonym" document field. */
PSEUDONYM: 'DeIdCardBack.Pseudonym',
/** Normalized field type name of the "RawMRZ" document field. */
RAW_MRZ: 'DeIdCardBack.RawMRZ',
/** MRZ Fields */
MrzFields: new GenericDocumentNormalizedMRZFields('DeIdCardBack'),
},
DeIdCardFront: {
/** Normalized field type name of the "BirthDate" document field. */
BIRTH_DATE: 'DeIdCardFront.BirthDate',
/** Normalized field type name of the "Birthplace" document field. */
BIRTHPLACE: 'DeIdCardFront.Birthplace',
/** Normalized field type name of the "ExpiryDate" document field. */
EXPIRY_DATE: 'DeIdCardFront.ExpiryDate',
/** Normalized field type name of the "GivenNames" document field. */
GIVEN_NAMES: 'DeIdCardFront.GivenNames',
/** Normalized field type name of the "ID" document field. */
ID: 'DeIdCardFront.ID',
/** Normalized field type name of the "MaidenName" document field. */
MAIDEN_NAME: 'DeIdCardFront.MaidenName',
/** Normalized field type name of the "Nationality" document field. */
NATIONALITY: 'DeIdCardFront.Nationality',
/** Normalized field type name of the "PIN" document field. */
PIN: 'DeIdCardFront.PIN',
/** Normalized field type name of the "Photo" document field. */
PHOTO: 'DeIdCardFront.Photo',
/** Normalized field type name of the "Signature" document field. */
SIGNATURE: 'DeIdCardFront.Signature',
/** Normalized field type name of the "Surname" document field. */
SURNAME: 'DeIdCardFront.Surname',
},
DePassport: {
/** Normalized field type name of the "BirthDate" document field. */
BIRTH_DATE: 'DePassport.BirthDate',
/** Normalized field type name of the "Birthplace" document field. */
BIRTHPLACE: 'DePassport.Birthplace',
/** Normalized field type name of the "CountryCode" document field. */
COUNTRY_CODE: 'DePassport.CountryCode',
/** Normalized field type name of the "ExpiryDate" document field. */
EXPIRY_DATE: 'DePassport.ExpiryDate',
/** Normalized field type name of the "Gender" document field. */
GENDER: 'DePassport.Gender',
/** Normalized field type name of the "GivenNames" document field. */
GIVEN_NAMES: 'DePassport.GivenNames',
/** Normalized field type name of the "ID" document field. */
ID: 'DePassport.ID',
/** Normalized field type name of the "IssueDate" document field. */
ISSUE_DATE: 'DePassport.IssueDate',
/** Normalized field type name of the "IssuingAuthority" document field. */
ISSUING_AUTHORITY: 'DePassport.IssuingAuthority',
/** Normalized field type name of the "MaidenName" document field. */
MAIDEN_NAME: 'DePassport.MaidenName',
/** Normalized field type name of the "Nationality" document field. */
NATIONALITY: 'DePassport.Nationality',
/** Normalized field type name of the "PassportType" document field. */
PASSPORT_TYPE: 'DePassport.PassportType',
/** Normalized field type name of the "Photo" document field. */
PHOTO: 'DePassport.Photo',
/** Normalized field type name of the "RawMRZ" document field. */
RAW_MRZ: 'DePassport.RawMRZ',
/** Normalized field type name of the "Signature" document field. */
SIGNATURE: 'DePassport.Signature',
/** Normalized field type name of the "Surname" document field. */
SURNAME: 'DePassport.Surname',
/** MRZ Fields */
MrzFields: new GenericDocumentNormalizedMRZFields('DePassport'),
},
};

// Some documents contain MRZ fields, this utility class exposes the corrent normalized names
// by pre-pending the document type to the string
export class GenericDocumentNormalizedMRZFields {
constructor(private rootField: string) {}

/** Normalized field type name of the "BirthDate" document field. */
public get BIRTH_DATE() {
return `${this.rootField}.MRZ.BirthDate`;
}

/** Normalized field type name of the "CheckDigit" document field. */
public get CHECK_DIGIT() {
return `${this.rootField}.MRZ.CheckDigit`;
}

/** Normalized field type name of the "DocumentNumber" document field. */
public get DOCUMENT_NUMBER() {
return `${this.rootField}.MRZ.DocumentNumber`;
}

/** Normalized field type name of the "ExpiryDate" document field. */
public get EXPIRY_DATE() {
return `${this.rootField}.MRZ.ExpiryDate`;
}

/** Normalized field type name of the "Gender" document field. */
public get GENDER() {
return `${this.rootField}.MRZ.Gender`;
}

/** Normalized field type name of the "GivenNames" document field. */
public get GIVEN_NAMES() {
return `${this.rootField}.MRZ.GivenNames`;
}

/** Normalized field type name of the "IssuingAuthority" document field. */
public get ISSUING_AUTHORITY() {
return `${this.rootField}.MRZ.IssuingAuthority`;
}

/** Normalized field type name of the "Nationality" document field. */
public get NATIONALITY() {
return `${this.rootField}.MRZ.Nationality`;
}

/** Normalized field type name of the "Optional1" document field. */
public get OPTIONAL_1() {
return `${this.rootField}.MRZ.Optional1`;
}

/** Normalized field type name of the "Optional2" document field. */
public get OPTIONAL_2() {
return `${this.rootField}.MRZ.Optional2`;
}

/** Normalized field type name of the "Surname" document field. */
public get SURNAME() {
return `${this.rootField}.MRZ.Surname`;
}

/** Normalized field type name of the "TravelDocType" document field. */
public get TRAVEL_DOC_TYPE() {
return `${this.rootField}.MRZ.TravelDocType`;
}

/** Normalized field type name of the "TravelDocTypeVariant" document field. */
public get TRAVEL_DOC_TYPE_VARIANT() {
return `${this.rootField}.MRZ.TravelDocTypeVariant`;
}
}

Available documents and fields

DeDriverLicenseBack

  • DeDriverLicenseBack.Restrictions
  • DeDriverLicenseBack.Category.Restrictions
  • DeDriverLicenseBack.Category.ValidFrom
  • DeDriverLicenseBack.Category.ValidUntil

DeDriverLicenseFront

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

DeIdCardBack

  • DeIdCardBack.Address
  • DeIdCardBack.EyeColor
  • DeIdCardBack.Height
  • DeIdCardBack.IssueDate
  • DeIdCardBack.IssuingAuthority
  • DeIdCardBack.Pseudonym
  • DeIdCardBack.RawMRZ
  • DeIdCardBack.MRZ.${MRZ_FIELD_NAME} - (check MRZ field names below)

DeIdCardFront

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

DePassport

  • 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
  • DePassport.MRZ.${MRZ_FIELD_NAME} - (check MRZ field names below)

MRZ Field Names

  • ${DOCUMENT_NAME}.MRZ.BirthDate
  • ${DOCUMENT_NAME}.MRZ.CheckDigit
  • ${DOCUMENT_NAME}.MRZ.DocumentNumber
  • ${DOCUMENT_NAME}.MRZ.ExpiryDate
  • ${DOCUMENT_NAME}.MRZ.Gender
  • ${DOCUMENT_NAME}.MRZ.GivenNames
  • ${DOCUMENT_NAME}.MRZ.IssuingAuthority
  • ${DOCUMENT_NAME}.MRZ.Nationality
  • ${DOCUMENT_NAME}.MRZ.Optional1
  • ${DOCUMENT_NAME}.MRZ.Optional2
  • ${DOCUMENT_NAME}.MRZ.Surname
  • ${DOCUMENT_NAME}.MRZ.TravelDocType
  • ${DOCUMENT_NAME}.MRZ.TravelDocTypeVariant

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?