Considerations and Limitations

Consider these guidelines and limitations when developing features that use the DocumentScanner API.

Device Limitations

To scan documents using a mobile device’s camera, DocumentScanner requires permission to use the camera. Your user must grant your app access to the camera. The exact user experience is governed by the platform. The request happens automatically on first use, and is managed by the device itself, but you should plan for it when designing the user experience of your app.
To scan documents stored in the device photo library, DocumentScanner requires permission to access the photo library. Your user must grant your app access to the photo library. Again, the user experience is managed by the platform (iOS or Android).
In Android 11 or later, if the user taps “Deny” for permission to access the Camera app or photo library more than once during the app’s lifetime of installation on a device, the user won’t see the system permissions dialog again. Tapping Deny multiple times implicitly chooses the “don’t ask again” option.

In previous versions of Android, users would see the system permissions dialog each time the app requested permission unless the user had previously selected “don’t ask again”. This change in Android 11 discourages repeated requests for permissions that users have chosen to deny.

If the user has denied permission to access the Camera app or photo library and needs to change their permissions to allow access, they can do so in their device’s settings.
DocumentScanner doesn’t implement scanning itself. Instead, it delegates document scanning and recognition to an underlying SDK implemented in native code (Android or iOS). While the features provided by DocumentScanner are the same across both platforms, they’re subject to some platform-specific quirks and minor differences.
- If the chosen input for the document to be scanned is the device camera, DocumentScanner automatically uses the “main” device camera. Built-in controls allow choosing other device cameras, if available.
- If you can’t get a clear picture of the document, it can’t be recognized. The quality of the device camera affects text recognition. A damaged or low-quality camera lens or focusing system, poor lighting, motion, and other factors can make it difficult or impossible to get a clear picture of a document.
- The quality of the document affects text recognition. Specifically, documents with damaged or obscured text are hard to recognize successfully.
- DocumentScanner recognizes printed text and handwritten form factors. However, DocumentScanner provides the most accurate results when scanning printed text compared handwritten text, which varies on the legibility of handwritten characters. While DocumentScanner is capable of performing text recognition on a variety of typefaces, highly stylized fonts can lower recognition accuracy.

Development Considerations

DocumentScanner requires access to camera hardware, or to the device photo library. To test scanning using a camera during development, use actual, physical devices.
- The Android emulator can simulate camera hardware by using a webcam on your development system. To do so, edit the camera configuration for your Android Virtual Device, in the advanced settings panel. However, the camera built into most laptops is much lower quality than what’s found on modern mobile phones. A low-quality camera limits the usefulness of testing text recognition.
- The iOS simulator doesn’t provide access to simulated camera hardware at all. You can certainly develop the user experience for your component on a desktop or laptop development system. But, be sure to test camera scanning functionality on the physical devices on which you plan to deploy your Lightning app.
As a work-around for limited camera access in virtual devices, you can load a few sample images into the virtual device’s photo library, and use those for scanning operations. However, if you expect your users to scan using a device camera, be sure to also test using real device cameras.

DocumentScanner Considerations

DocumentScanner is built on top of mobile operating system and device features. DocumentScanner’s capabilities therefore depend on Android or iOS features, which are subject to change beyond our control. When mobile operating system features change, the behavior of DocumentScanner can change without notice.