Genius Scan SDK for Capacitor

Description

The Genius Scan SDK for Capacitor lets you integrate the document scanning experience that powers the Genius Scan app into your Capacitor application.

It exposes the Genius Scan SDK scan flow with features including:

• Automatic document detection
• Perspective correction
• Image enhancement with multiple filters
• Multi-page scanning
• OCR for raw text extraction and searchable PDFs
• Barcode scanning

License

You can try the plugin without a license key, but it will stop working after 60 seconds.

You need to set a license key for unlimited demo time and for production use.

To buy a license:

1. Sign up to the developer console
2. Submit a quote request for each application

You can learn more about licensing on our website and contact [email protected] for further questions.

Demo application

You can find a demo application in the geniusscan-sdk-demo repository.

Requirements

• Capacitor 8
• iOS 15.0+
• Android minSdk 23
• Java 21 for Android builds

Installation

From your Capacitor application:

npm install @thegrizzlylabs/capacitor-plugin-genius-scan
npx cap sync

iOS

Add the camera usage description to your app's Info.plist:

<key>NSCameraUsageDescription</key>
<string>We use the camera to scan documents.</string>

Android

Android builds require Java 21.

Usage

import GeniusScan from '@thegrizzlylabs/capacitor-plugin-genius-scan';

Set the license key

Initialize the SDK with a valid license key:

await GeniusScan.setLicenseKey(licenseKey, true);

setLicenseKey does not return a value. Other plugin methods will fail if the license key is invalid or expired.

Start the scan flow

const result = await GeniusScan.scanWithConfiguration({
  source: 'camera',
  multiPage: true,
});

The method scanWithConfiguration takes a configuration parameter which can take the following options:

• source: camera, image or library (defaults to camera)
• sourceImageUrl: an absolute image url, required if source is image. Example: file:///path/to/image.png
• multiPage: boolean (defaults to true). If true, after a page is scanned, a prompt to scan another page will be displayed. If false, a single page will be scanned.
• multiPageFormat: pdf, tiff, none (defaults to pdf)
• defaultFilter: the filter that will be applied by default to enhance scans, or none if no enhancement should be performed by default. Possible values are listed in the Available filters section. Default value is automatic.
• availableFilters: an array of filters that the user can select when they tap on the edit filter button. Defaults to [none, automatic, automaticMonochrome, automaticBlackAndWhite, automaticColor, photo].
• pdfPageSize: fit, a4, letter, defaults to fit.
• pdfPassword: Optional password used to protect generated PDF documents. Empty passwords are treated as no password. This only applies when multiPageFormat is pdf.
• pdfMaxScanDimension: max dimension in pixels when images are scaled before PDF generation, for example 2000 to fit both height and width within 2000px. Defaults to 0, which means no scaling is performed.
• pdfFontFileUrl: Custom font file used during the PDF generation to embed an invisible text layer. If null, a default font is used, which only supports Latin languages.
• jpegQuality: JPEG quality used to compress captured images. Between 0 and 100, 100 being the best quality. Default is 60.
• skipPostProcessingScreen: Whether to skip showing the post-processing screen. We only recommend enabling this option when scanning structured data. Generally, you want the user to visually confirm the quality of each scan.
• postProcessingActions: an array with the desired actions to display during the post processing screen (defaults to all actions). Possible actions are rotate, editFilter and correctDistortion.
• defaultCurvatureCorrection: enabled or disabled whether a curvature correction should be applied by default. Disabled by default.
• showCropValidation: never, always, or { whenConfidenceBelowOrEqual: 'highest' | 'high' | 'medium' | 'low' | 'lowest' } to automatically show crop validation after capture.
• defaultScanOrientation: automatic to rotate scan automatically after capture or original to keep original scan orientation (defaults to automatic).
• photoLibraryButtonHidden: boolean specifying whether the button allowing the user to pick an image on the Camera screen should be hidden (default to false).
• flashButtonHidden: boolean (default to false)
• defaultFlashMode: auto, on, off (default to off)
• foregroundColor: string representing a color, must start with a #. The color of the icons, text (defaults to '#ffffff').
• backgroundColor: string representing a color, must start with a #. The color of the toolbar, screen background (defaults to black)
• highlightColor: string representing a color, must start with a #. The color of the image overlays (default to blue)
• menuColor: string representing a color, must start with a #. The color of the menus (iOS only, defaults to system defaults).
• ocrConfiguration: text recognition options. Text recognition will run on a background thread for every captured image. No text recognition will be applied if this parameter is not present.
  • languages: list of the BCP 47 language codes (eg ["en-US"]) for which to run text recognition. Note that text recognition will take longer if multiple languages are specified.
  • outputFormats: an array with the formats in which the OCR result is made available in the ScanFlow result (defaults to all formats). Possible formats are rawText, hOCR and textLayerInPDF.
• structuredData: an array of the structured data you want to extract. E.g.: ['receipt', 'businessCard']. Possible values are receipt, barcode, bankDetails (iOS only), businessCard (iOS only).
• structuredDataBarcodeTypes: an array of the barcode types to extract, e.g. ['qr', 'code39']. Possible values are aztec, code39, code93, code128, dataMatrix, ean8, ean13, itf, pdf417, qr, upca (Android only), upce, codabar (iOS 15+ only), gs1DataBar (iOS 15+ only), microPDF417 (iOS 15+ only), microQR (iOS 15+ only), msiPlessey (iOS 17+ only).
• requiredReadabilityLevel: the required readability level below which a warning will be displayed to the user. Possible values are lowest, low, medium, high, highest (default to lowest, which means the warning will never be displayed).
• showFinalReview: boolean specifying whether the final review screen should be displayed before submission (default to false).

It returns a promise with result object containing:

• multiPageDocumentUrl: a document containing all the scanned pages (example: "file:///path/to/file.pdf")
• scans: an array of scan objects. Each scan object has:
  • originalUrl: the original file as scanned from the camera. "file:///path/to/file.jpeg"
  • enhancedUrl: the cropped and enhanced file, as processed by the SDK. "file:///path/to/file.{jpeg|png}"
  • ocrResult: the result of text recognition for this scan
    • text: the raw text that was recognized
    • hocrTextLayout: the recognized text in hOCR format (with position, style…)
  • structuredData: the result of the structured data extraction. A subdictionary will be present for each type of structured data detected by the scan flow.

An implicit API contract is that you have to take ownership of the resulting files referenced by the result object. You are responsible for moving them to the appropriate place and deleting them if you don’t need them anymore.

Available filters

The ScanFlow offers a variety of filters to enhance the appearance of different kinds of documents. Some filters are dynamic (or automatic), meaning they will apply the best enhancement possible, possibly with some constraints. For example, the automaticBlackAndWhite filter will apply the best enhancement, assuming that the scan is a text document and making sure the output will have a grayscale color palette. Here is a list of all possible dynamic filters: automatic, automaticColor, automaticBlackAndWhite, automaticMonochrome.

Other filters are static filters, which means they always perform the same enhancement operation, without any logic on the document characteristics. The different static filters are: photo, softBlackAndWhite, softColor, strongMonochrome, strongBlackAndWhite, strongColor, darkBackground.

Scan barcodes

const result = await GeniusScan.scanBarcodesWithConfiguration({
  isBatchModeEnabled: true,
  supportedCodeTypes: ['qr', 'ean13'],
});

The returned value contains a barcodes array with value and type.

Generate a PDF document

If you'd like to rearrange the pages returned by the ScanFlow or add some more pages, you can do so and generate a PDF document from these pages:

await GeniusScan.generateDocument(
  {
    pages: [
      { imageUrl: 'file:///path/to/page1.jpeg' },
      { imageUrl: 'file:///path/to/page2.jpeg' },
    ],
  },
  {
    outputFileUrl: 'file:///path/to/output.pdf',
  }
);

The document parameter is a map containing the following values:

• pages: an array of page objects. Each page object has:
  • imageUrl: the URL of the PNG or JPEG image file for this page, e.g. file:///path/to/file.{jpeg|png}
  • hocrTextLayout: the text layout in hOCR format

The configuration parameter provides the following options:

• outputFileUrl: the URL where the document should be generated, e.g. file:///path/to/file.pdf
• pdfFontFileUrl: Custom font file used during the PDF generation to embed an invisible text layer. If null, a default font is used, which only supports Latin languages.

Error handling

Plugin methods reject with a structured error object:

• code: standardized error code
• message: developer-facing diagnostic message
• recovery_message: developer-facing recovery suggestion when available
• underlying_error: stringified underlying native error when available

The code field is one of:

| Code | Description | Suggested handling | | --- | --- | --- | | cancellation_error | The user canceled the document or barcode scan flow. | Treat as a normal exit; do not show an error. | | configuration_error | The configuration or input parameters are invalid. | Fix the configuration before retrying. | | licensing_error | The license key is invalid, expired, or not initialized. | Verify the license key and contact support if needed. | | capture_error | The camera or capture session failed. | Let the user retry; restart the device if the problem persists. | | storage_space_error | There is not enough storage space to write generated files. | Ask the user to free up storage space and retry. | | internal_error | An unexpected SDK error occurred. | Show a generic error and collect underlying_error for diagnostics. |

message and recovery_message are English diagnostics for developers. They are not intended to be displayed directly to end users; use code to choose your own localized user-facing message.

Example:

try {
  await GeniusScan.scanWithConfiguration({ source: 'camera' });
} catch (error) {
  console.log(error.code);
  console.log(error.message);
  console.log(error.recovery_message);
  console.log(error.underlying_error);
}

Troubleshooting

Refer to the native SDK troubleshooting guides for common configuration and build issues:

• iOS
• Android

Changelog

See the changelog.