Considerations and Limitations

Device Limitations

• BarcodeScanner requires the use of the mobile device camera. The 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.

• In Android 11 or later, if the user taps “Deny” for permission to access the Contacts app 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 Contacts app and needs to change their permissions to allow access, they can do so in their device’s settings.

• BarcodeScanner doesn’t implement scanning itself. Instead, it makes available the scanning feature of the underlying platform (Android or iOS). While the features provided by BarcodeScanner are the same across both platforms, it is subject to some platform-specific quirks and minor differences.
  • If you can’t get a clear picture of the barcode, it can’t be recognized. The quality of the device camera affects barcode 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 barcode.
  • The quality of the barcode affects barcode recognition. Specifically, damaged or obscured barcodes are hard to recognize successfully.
• If you’re having trouble getting BarcodeScanner to recognize a barcode, try the following:
  • First, verify that the barcode type is one of the supported barcode symbologies. There are other barcode types that aren’t supported.
  • Second, verify that you’ve configured BarcodeScanner to recognize the expected symbology. See BarcodeScannerOptions in BarcodeScanner Data Types for configuration details.
  • Finally, check whether another app on the same device is able to recognize the barcode. If the standard camera app on the device can’t recognize the barcode, neither can BarcodeScanner.

Development Considerations

• BarcodeScanner requires access to camera hardware. To test scanning 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 barcode 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 scanning functionality on the physical devices on which you plan to deploy your Lightning app.

Usage Considerations

Keep in mind the following considerations to increase the chances of ‌performing a successful scan.

• Device camera quality significantly impacts barcode scanning success. High-end devices with better cameras scan barcodes more accurately and efficiently than low-end devices, which are more likely to make mistakes in finding them.
• For optimal scanner performance, ensure barcodes are printed on a flat surface, not a curved or deformed one.
• Scanning barcodes from digital screens can be challenging due to minor image artifacts introduced by the screen when viewed through a device’s camera lens. This is a common issue when aiming a camera at a digital display, making digital screen scanning inherently more difficult.
• Scanning becomes more challenging when barcodes are resized or scaled down to fit a smaller area (such as a digital screen), especially long variable-length barcodes.
• When scanning a small barcode, bring your phone as close as possible without blurring the image. Blurring will reduce the chances of a successful scan. You can also pinch-to-zoom on the scanner viewport to enlarge the image.
• Prioritize moving the phone closer to the barcode before using pinch-to-zoom. Many devices, especially older Android models, utilize digital zoom for pinch-to-zoom, particularly at higher zoom levels. This can significantly reduce image quality.
• On Apple Pro and Pro MAX series devices, the Nimbus BarcodeScanner uses the ultra-wide angle lens for macro-mode shooting when the phone is brought physically closer to a barcode. This automatic lens switch enables successful scans even at extremely close distances by preventing blurry images. This feature is currently not available for Android devices.

BarcodeScanner Considerations

Be aware of the following considerations when using BarcodeScanner in your Lightning app.

• BarcodeScanner is built on top of mobile operating system features. BarcodeScanner’s scanning 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 BarcodeScanner can change without notice.
• BarcodeScanner provides haptic feedback (a short vibration) after a successful scan on iOS devices. There’s no haptic feedback on Android devices.
• The Nimbus BarcodeScanner plugin may behave differently on iOS and Android, because of the differences in their operating systems and how their barcode scanning APIs work.
• Third-party barcode scanning applications often use their own scanning and detection tools and libraries to scan barcodes. These may differ from the built-in operating system (Android and iOS) APIs used by the Nimbus BarcodeScanner.
• BarcodeScanner performs better with 2D barcodes (such as QR codes) due to their lower error susceptibility during detection. In contrast, "linear" or 1D barcodes (such as Code128, UPC) are more prone to detection errors.

  Furthermore, some 1D barcodes have variable data lengths. This can lead to partial payload scans, as the scanner might mistakenly register a complete barcode even when only a portion is visible. Therefore, if you have the option, 2D barcodes are preferable.

  To improve handling of 1D barcodes, you can configure the scanner by setting manualConfirmation=true in the BarcodeScanner options. This setting requires the user to manually confirm the detected barcode by tapping a screen button, allowing time to bring the entire barcode into view.

• BarcodeScanner uses OS-level APIs for barcode processing, particularly 1D barcodes that may contain special characters. It does not filter or process these characters; instead, whatever is detected by the APIs is returned to the LWC as-is. This approach maintains the scanner's generic utility, catering to diverse customer needs where special characters in the payload are desired. Therefore, any subsequent filtering or processing of special characters is the developer's responsibility.