Installation

1. Install the plugin in your OutSystems application by searching for "Scan Document Plugin" in the Forge and clicking Install.
2. In Service Studio, add the plugin as a dependency to your mobile application by opening the Manage Dependencies window and selecting the Scan Document Plugin.
3. For Android, no additional configuration is required. Google Play Services and ML Kit are bundled automatically.
4. For iOS, ensure your app's Info.plist includes the NSCameraUsageDescription key with a user-facing message explaining why the app needs camera access. This is required by Apple for any app that uses the camera.

Basic Usage

1. In your mobile application, create a button or action that will trigger the document scan.
2. Call the ScanDocument client action exposed by the plugin. With no parameters, it will use the default configuration: up to 24 pages, full scanner mode, image file paths as output, and maximum image quality.
3. Check the Status field in the response. A value of success means the scan completed. A value of cancel means the user dismissed the scanner without saving.
4. Access the scanned images through the ScannedImages list in the response. Each entry is either a file path or a base64 string, depending on your chosen response type.

Configuration Options

The ScanDocument action accepts an optional configuration object with the following parameters:

ResponseType — Controls the output format. Set to imageFilePath to receive file paths on disk (default) or base64 to receive base64-encoded strings. Use base64 when you need to upload images directly to a server or display them inline.

MaxNumDocuments — Sets the maximum number of pages the user can scan in a single session. Defaults to 24 on Android. Set to 1 for single-document mode where the scanner closes automatically after one capture.

CroppedImageQuality — Android only. Controls the JPEG quality of cropped images, from 0 (lowest) to 100 (highest). Defaults to 100. Lower values reduce file size at the cost of image clarity.

LetUserAdjustCrop — Android only. When set to true (default), the user can manually adjust the detected crop area before saving. Setting this to false forces automatic cropping and limits capture to a single document.

Brightness — Adjusts brightness of the scanned output. Accepts values from -255 to 255, where 0 is no change, positive values brighten the image, and negative values darken it. Useful for compensating low-light scans.

Contrast — Adjusts contrast of the scanned output. Accepts values from 0.0 to 10.0, where 1.0 is no change. Values above 1.0 increase contrast, which can improve text legibility in poorly lit scans.

ScannerMode — Android only. Controls which ML Kit features are available during scanning. Three options are available: base provides basic crop and rotate only; base_with_filter adds grayscale and auto-enhancement filters; full (default) enables all features including ML-based image cleaning that automatically removes stains, fingers, and other artifacts.

Example Flow

1. User taps a "Scan Receipt" button in your app.
2. Your action calls ScanDocument with MaxNumDocuments set to 1, ResponseType set to base64, and CroppedImageQuality set to 80.
3. The native scanner opens, the user captures one page, adjusts the crop if needed, and confirms.
4. Your action receives the response, checks that Status equals success, and reads the base64 string from ScannedImages to upload it to your backend or display it in an image widget.

Troubleshooting

If scanning fails on Android, verify that the device is not an emulator. The ML Kit Document Scanner does not support emulated environments due to Google Play Services limitations. Always test on a physical device.

If the camera does not open on iOS, confirm that the NSCameraUsageDescription key is present in your Info.plist and that the user has granted camera permissions.