👁 Image
GeniusScanSDK.ScanFlow 6.1.0

Genius Scan SDK for .NET MAUI

Description

The Genius Scan SDK for .NET MAUI enables you to integrate the document scanning experience that powers the Genius Scan app in your MAUI application.

GeniusScanSDK.ScanFlow exposes a thin, cross-platform ScanFlowService that wraps the native iOS and Android bindings so that your app only needs to interact with a single API surface. The service provides:

• The Document ScanFlow, an all-in-one configurable document scanner module
• The Barcode ScanFlow, for continuous barcode capture
• PDF generation

Installation

dotnet add package GeniusScanSDK.ScanFlow

The package multi-targets net9.0-android, net10.0-android, net9.0-ios, and net10.0-ios and depends on the platform binding packages automatically.

Android activity hook

Forward OnActivityResult to the service so promises complete correctly:

protected override void OnActivityResult(int requestCode, Result resultCode, Intent? data)
{
 if (!ScanFlowService.OnActivityResult(requestCode, resultCode, data))
 {
 base.OnActivityResult(requestCode, resultCode, data);
 }
}

License

You can try the SDK for free without a license key, with the only limitation being that the app stops working after 60 seconds.

For production use you must set a license key. To purchase one:

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

See the licensing FAQ for more details or contact us at sales@geniusscansdk.com.

Usage

using GeniusScanSDK.ScanFlow;

var scanFlowService = new ScanFlowService();

Every API is asynchronous (except SetLicenseKey and GenerateDocument) and returns dictionaries that mirror the JSON payloads from the native SDKs. The consumer owns the lifecycle of any files referenced in the results.

Set the license key

Initialize the SDK with a valid license key:

scanFlowService.SetLicenseKey(licenseKey);

This method doesn't return anything. However, other methods of the plugin will fail if the license key is invalid or expired. Note that, for testing purpose, you can also use the plugin without setting a license key, but it will only work for 60 seconds.

Start the document scanner module

The following line will start a scan flow with the corresponding configuration:

var result = await scanFlowService.ScanDocument(configuration);

The configuration dictionary accepts the following keys (all optional unless noted):

• source: camera, image, or library (default camera).
• sourceImageUrl: absolute URL used when source == "image", e.g. file:///var/.../image.jpg.
• multiPage: bool enabling additional page prompts (default true).
• multiPageFormat: pdf, tiff, or none (default pdf).
• defaultFilter: none, automatic, automaticColor, automaticBlackAndWhite, automaticMonochrome, photo, etc. (default automatic).
• availableFilters: array of filters users may pick (defaults to [none, automatic, automaticMonochrome, automaticBlackAndWhite, automaticColor, photo]).
• pdfPageSize: fit, a4, or letter (default fit).
• pdfMaxScanDimension: number limiting the maximal dimension of processed scans in pixels (default 0, meaning no scaling).
• 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 60).
• skipPostProcessingScreen: bool to bypass the review UI (default false).
• 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.
• 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 (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 15+ 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).

Result dictionary

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

Start the barcode scanner module

The following code starts a Barcode ScanFlow, dedicated to barcode/QR scanning:

var result = await scanFlowService.ScanBarcodes(configuration);

Configuration keys

• supportedCodeTypes: array of barcode identifiers (qr, code128, ...). Empty or missing means “all supported types”.
• isBatchModeEnabled: bool. When true, keeps the camera active and appends codes until you dismiss the flow manually.
• highlightColor: string representing a color, must start with a #. The color of the barcode overlay (defaults to green).
• menuColor: string representing a color, must start with a #. The color of the UI menus (defaults to the system default color).

Result dictionary

• barcodes: array where each entry contains:
  • value: decoded string.
  • type: barcode type (matches the identifiers listed above).

PDF generation

The following code generates a PDF document from scans you control (for example after re-ordering pages):

scanFlowService.GenerateDocument(document, configuration);

The document parameter is a dictinary 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.

Throws an exception when the native generator reports an error.

Error handling

Scan flow errors are thrown as ScanFlowException with the following fields:

• Code: standardized error code
• Message: developer-facing diagnostic message
• RecoveryMessage: developer-facing recovery suggestion (may be empty)
• UnderlyingError: stringified underlying error (may be empty)

The Code field is one of:

Message and RecoveryMessage 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

var scanFlowService = new ScanFlowService();

scanFlowService.SetLicenseKey("<your key>");

var result = await scanFlowService.ScanDocument(new Dictionary<string, object>
{
 ["source"] = "camera",
 ["ocrConfiguration"] = new Dictionary<string, object>
 {
 ["languages"] = new[] { "en-US" }
 }
});

var documentUrl = (string)result["multiPageDocumentUrl"];

FAQ

• How is the UI localized? The SDK automatically uses the device locale for screens, dialogs, and guidance.
• What if the license expires? Show an in-app message asking users to update, then refresh the key via our developer console.
• Where can I find troubleshooting help? Refer to the iOS and Android guides for native requirements.

Changelog

See the public changelog.