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 scan configuration supports the following options:

• source: camera, library or image (defaults to camera)
• sourceImageUrl: absolute image URL, required if source is image
• multiPage: whether to scan several pages in sequence
• multiPageFormat: none, pdf or tiff
• defaultFilter
• availableFilters
• pdfPageSize: fit, a4 or letter
• pdfMaxScanDimension
• pdfFontFileUrl
• jpegQuality
• postProcessingActions
• flashButtonHidden
• defaultFlashMode: auto, on or off
• backgroundColor
• foregroundColor
• highlightColor
• menuColor
• ocrConfiguration
• structuredData
• structuredDataBarcodeTypes

The returned result contains:

• multiPageDocumentUrl: generated PDF or TIFF when requested
• scans: scanned pages
  • originalUrl
  • enhancedUrl
  • ocrResult
  • structuredData

You are responsible for moving or deleting the generated files after use.

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 want to reorder pages or build a document yourself, you can generate a PDF from page images:

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

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.