@ivakm/capacitor-mlkit v1.0.1
@capacitor-mlkit/barcode-scanning
Unofficial Capacitor plugin for ML Kit Barcode scanning.^1
Features
- 𧩠Optional ready-to-use interface without webview customizations
- ποΈ Extremely fast
- π· Scan multiple barcodes at once
- βΊοΈ Define detection area
- ποΈ Reading barcodes from images
- π¦ Torch and Autofocus support
- π Supports Android and iOS
For a complete list of supported barcodes, see BarcodeFormat.
Demo
A working example can be found here: https://github.com/robingenz/capacitor-mlkit-plugin-demo
Android |
---|
Installation
npm install @capacitor-mlkit/barcode-scanning
npx cap sync
Android
This API requires the following permissions be added to your AndroidManifest.xml
before the application
tag:
<!-- To get access to the camera. -->
<uses-permission android:name="android.permission.CAMERA" />
<!-- To get access to the flashlight. -->
<uses-permission android:name="android.permission.FLASHLIGHT"/>
You also need to add the following meta data in the application
tag in your AndroidManifest.xml
:
<meta-data android:name="com.google.mlkit.vision.DEPENDENCIES" android:value="barcode_ui"/>
Variables
This plugin will use the following project variables (defined in your appβs variables.gradle
file):
$androidxCameraCamera2Version
version ofcom.google.mlkit:barcode-scanning
(default:1.1.0
)$androidxCameraCoreVersion
version ofcom.google.mlkit:barcode-scanning
(default:1.1.0
)$androidxCameraLifecycleVersion
version ofcom.google.mlkit:barcode-scanning
(default:1.1.0
)$androidxCameraViewVersion
version ofcom.google.mlkit:barcode-scanning
(default:1.1.0
)$mlkitBarcodeScanningVersion
version ofcom.google.mlkit:barcode-scanning
(default:17.0.3
)$playServicesCodeScannerVersion
version ofcom.google.mlkit:barcode-scanning
(default:16.0.0-beta3
)
iOS
Add the NSCameraUsageDescription
key to the ios/App/App/Info.plist
file, which tells the user why the app needs to use the camera:
+ <key>NSCameraUsageDescription</key>
+ <string>The app enables the scanning of various barcodes.</string>
If you also use a @capacitor-firebase/*
dependency in your project, then implement this workaround to avoid conflict with the Cocoapods dependencies.
Configuration
No configuration required for this plugin.
Demo
A working example can be found here: robingenz/capacitor-mlkit-plugin-demo
Usage
import {
BarcodeScanner,
BarcodeFormat,
LensFacing,
} from '@capacitor-mlkit/barcode-scanning';
const startScan = async () => {
// The camera is visible behind the WebView, so that you can customize the UI in the WebView.
// However, this means that you have to hide all elements that should not be visible.
// You can find an example in our demo repository.
// In this case we set a class `barcode-scanner-active`, which then contains certain CSS rules for our app.
document.querySelector('body')?.classList.add('barcode-scanner-active');
// Add the `barcodeScanned` listener
const listener = await BarcodeScanner.addListener(
'barcodeScanned',
async result => {
console.log(result.barcode);
},
);
// Start the barcode scanner
await BarcodeScanner.startScan();
};
const stopScan = async () => {
// Make all elements in the WebView visible again
document.querySelector('body')?.classList.remove('barcode-scanner-active');
// Remove all listeners
await BarcodeScanner.removeAllListeners();
// Stop the barcode scanner
await BarcodeScanner.stopScan();
};
const scanSingleBarcode = async () => {
return new Promise(async resolve => {
document.querySelector('body')?.classList.add('barcode-scanner-active');
const listener = await BarcodeScanner.addListener(
'barcodeScanned',
async result => {
await listener.remove();
document
.querySelector('body')
?.classList.remove('barcode-scanner-active');
await BarcodeScanner.stopScan();
resolve(result.barcode);
},
);
await BarcodeScanner.startScan();
});
};
const scan = async () => {
const { barcodes } = await BarcodeScanner.scan({
formats: [BarcodeFormat.QrCode],
lensFacing: LensFacing.Back,
});
return barcodes;
};
const isSupported = async () => {
const { supported } = await BarcodeScanner.isSupported();
return supported;
};
const enableTorch = async () => {
await BarcodeScanner.enableTorch();
};
const disableTorch = async () => {
await BarcodeScanner.disableTorch();
};
const toggleTorch = async () => {
await BarcodeScanner.toggleTorch();
};
const isTorchEnabled = async () => {
const { enabled } = await BarcodeScanner.isTorchEnabled();
return enabled;
};
const isTorchAvailable = async () => {
const { available } = await BarcodeScanner.isTorchAvailable();
return available;
};
const openSettings = async () => {
await BarcodeScanner.openSettings();
};
const checkPermissions = async () => {
const { camera } = await BarcodeScanner.checkPermissions();
return camera;
};
const requestPermissions = async () => {
const { camera } = await BarcodeScanner.requestPermissions();
return camera;
};
An example of the CSS class barcode-scanner-active
with Ionic could be:
// Hide all elements
body.barcode-scanner-active {
visibility: hidden;
--background: transparent;
--ion-background-color: transparent;
}
// Show only the barcode scanner modal
.barcode-scanner-modal {
visibility: visible;
}
@media (prefers-color-scheme: dark) {
.barcode-scanner-modal {
--background: transparent;
--ion-background-color: transparent;
}
}
An example of the CSS class barcode-scanner-active
without Ionic could be:
// Hide all elements
body.barcode-scanner-active {
visibility: hidden;
}
// Show only the barcode scanner modal
.barcode-scanner-modal {
visibility: visible;
}
If you can't see the camera view, make sure all elements in the DOM are not visible or have a transparent background to debug the issue.
API
startScan(...)
stopScan()
readBarcodesFromImage(...)
scan(...)
isSupported()
enableTorch()
disableTorch()
toggleTorch()
isTorchEnabled()
isTorchAvailable()
openSettings()
checkPermissions()
requestPermissions()
addListener('barcodeScanned', ...)
addListener('scanError', ...)
removeAllListeners()
- Interfaces
- Type Aliases
- Enums
startScan(...)
startScan(options?: StartScanOptions | undefined) => Promise<void>
Start scanning for barcodes.
Only available on Android and iOS.
Param | Type |
---|---|
options | StartScanOptions |
Since: 0.0.1
stopScan()
stopScan() => Promise<void>
Stop scanning for barcodes.
Only available on Android and iOS.
Since: 0.0.1
readBarcodesFromImage(...)
readBarcodesFromImage(options: ReadBarcodesFromImageOptions) => Promise<ReadBarcodesFromImageResult>
Read barcodes from an image.
Only available on Android and iOS.
Param | Type |
---|---|
options | ReadBarcodesFromImageOptions |
Returns: Promise<ReadBarcodesFromImageResult>
Since: 0.0.1
scan(...)
scan(options?: ScanOptions | undefined) => Promise<ScanResult>
Scan a barcode with a ready-to-use interface without WebView customization.
On Android, no camera permission is required.
Only available on Android and iOS.
Param | Type |
---|---|
options | ScanOptions |
Returns: Promise<ScanResult>
Since: 0.0.1
isSupported()
isSupported() => Promise<IsSupportedResult>
Returns whether or not the barcode scanner is supported.
Available on Android and iOS.
Returns: Promise<IsSupportedResult>
Since: 0.0.1
enableTorch()
enableTorch() => Promise<void>
Enable camera's torch (flash) during a scan session.
Only available on Android and iOS.
Since: 0.0.1
disableTorch()
disableTorch() => Promise<void>
Disable camera's torch (flash) during a scan session.
Only available on Android and iOS.
Since: 0.0.1
toggleTorch()
toggleTorch() => Promise<void>
Toggle camera's torch (flash) during a scan session.
Only available on Android and iOS.
Since: 0.0.1
isTorchEnabled()
isTorchEnabled() => Promise<IsTorchEnabledResult>
Returns whether or not the camera's torch (flash) is enabled.
Only available on Android and iOS.
Returns: Promise<IsTorchEnabledResult>
Since: 0.0.1
isTorchAvailable()
isTorchAvailable() => Promise<IsTorchAvailableResult>
Returns whether or not the camera's torch (flash) is available.
Only available on Android and iOS.
Returns: Promise<IsTorchAvailableResult>
Since: 0.0.1
openSettings()
openSettings() => Promise<void>
Open the settings of the app so that the user can grant the camera permission.
Only available on Android and iOS.
Since: 0.0.1
checkPermissions()
checkPermissions() => Promise<PermissionStatus>
Check camera permission.
Only available on Android and iOS.
Returns: Promise<PermissionStatus>
Since: 0.0.1
requestPermissions()
requestPermissions() => Promise<PermissionStatus>
Request camera permission.
Only available on Android and iOS.
Returns: Promise<PermissionStatus>
Since: 0.0.1
addListener('barcodeScanned', ...)
addListener(eventName: 'barcodeScanned', listenerFunc: (event: BarcodeScannedEvent) => void) => Promise<PluginListenerHandle> & PluginListenerHandle
Called when a barcode is scanned.
Available on Android and iOS.
Param | Type |
---|---|
eventName | 'barcodeScanned' |
listenerFunc | (event: BarcodeScannedEvent) => void |
Returns: Promise<PluginListenerHandle> & PluginListenerHandle
Since: 0.0.1
addListener('scanError', ...)
addListener(eventName: 'scanError', listenerFunc: (event: ScanErrorEvent) => void) => Promise<PluginListenerHandle> & PluginListenerHandle
Called when an error occurs during the scan.
Available on Android and iOS.
Param | Type |
---|---|
eventName | 'scanError' |
listenerFunc | (event: ScanErrorEvent) => void |
Returns: Promise<PluginListenerHandle> & PluginListenerHandle
Since: 0.0.1
removeAllListeners()
removeAllListeners() => Promise<void>
Remove all listeners for this plugin.
Since: 0.0.1
Interfaces
StartScanOptions
Prop | Type | Description | Since |
---|---|---|---|
formats | BarcodeFormat[] | Improve the speed of the barcode scanner by configuring the barcode formats to scan for. | 0.0.1 |
lensFacing | LensFacing | Configure the camera (front or back) to use. | 0.0.1 |
ReadBarcodesFromImageResult
Prop | Type | Description | Since |
---|---|---|---|
barcodes | Barcode[] | The detected barcodes. | 0.0.1 |
Barcode
Prop | Type | Description | Since |
---|---|---|---|
bytes | number[] | Raw bytes as it was encoded in the barcode. | 0.0.1 |
cornerPoints | [number, number, number, number, number, number, number, number] | The four corner points of the barcode in clockwise order starting with top-left. | 0.0.1 |
displayValue | string | The barcode value in a human readable format. | 0.0.1 |
format | BarcodeFormat | The barcode format. | 0.0.1 |
rawValue | string | The barcode value in a machine readable format. | 0.0.1 |
valueType | BarcodeValueType | The barcode value type. | 0.0.1 |
ReadBarcodesFromImageOptions
Prop | Type | Description | Since |
---|---|---|---|
formats | BarcodeFormat[] | Improve the speed of the barcode scanner by configuring the barcode formats to scan for. | 0.0.1 |
path | string | The local path to the image file. | 0.0.1 |
ScanResult
Prop | Type | Description | Since |
---|---|---|---|
barcodes | Barcode[] | The detected barcodes. | 0.0.1 |
ScanOptions
Prop | Type | Description | Since |
---|---|---|---|
formats | BarcodeFormat[] | Improve the speed of the barcode scanner by configuring the barcode formats to scan for. | 0.0.1 |
IsSupportedResult
Prop | Type | Description | Since |
---|---|---|---|
supported | boolean | Whether or not the barcode scanner is supported. | 0.0.1 |
IsTorchEnabledResult
Prop | Type | Description | Since |
---|---|---|---|
enabled | boolean | Whether or not the torch is enabled. | 0.0.1 |
IsTorchAvailableResult
Prop | Type | Description | Since |
---|---|---|---|
available | boolean | Whether or not the torch is available. | 0.0.1 |
PermissionStatus
Prop | Type | Since |
---|---|---|
camera | CameraPermissionState | 0.0.1 |
PluginListenerHandle
Prop | Type |
---|---|
remove | () => Promise<void> |
BarcodeScannedEvent
Prop | Type | Description | Since |
---|---|---|---|
barcode | Barcode | A detected barcode. | 0.0.1 |
ScanErrorEvent
Prop | Type | Description | Since |
---|---|---|---|
message | string | The error message. | 0.0.1 |
Type Aliases
CameraPermissionState
PermissionState | 'limited'
PermissionState
'prompt' | 'prompt-with-rationale' | 'granted' | 'denied'
Enums
BarcodeFormat
Members | Value | Description | Since |
---|---|---|---|
Aztec | 'AZTEC' | Only available on Android and iOS. | 0.0.1 |
Codabar | 'CODABAR' | Only available on Android and iOS. | 0.0.1 |
Code39 | 'CODE_39' | Only available on Android and iOS. | 0.0.1 |
Code93 | 'CODE_93' | Only available on Android and iOS. | 0.0.1 |
Code128 | 'CODE_128' | Only available on Android and iOS. | 0.0.1 |
DataMatrix | 'DATA_MATRIX' | Only available on Android and iOS. | 0.0.1 |
Ean8 | 'EAN_8' | Only available on Android and iOS. | 0.0.1 |
Ean13 | 'EAN_13' | Only available on Android and iOS. | 0.0.1 |
Itf | 'ITF' | Only available on Android and iOS. | 0.0.1 |
Pdf417 | 'PDF_417' | Only available on Android and iOS. | 0.0.1 |
QrCode | 'QR_CODE' | Only available on Android and iOS. | 0.0.1 |
UpcA | 'UPC_A' | Only available on Android and iOS. | 0.0.1 |
UpcE | 'UPC_E' | Only available on Android and iOS. | 0.0.1 |
LensFacing
Members | Value | Since |
---|---|---|
Front | 'FRONT' | 0.0.1 |
Back | 'BACK' | 0.0.1 |
BarcodeValueType
Members | Value | Since |
---|---|---|
CalendarEvent | 'CALENDAR_EVENT' | 0.0.1 |
ContactInfo | 'CONTACT_INFO' | 0.0.1 |
DriversLicense | 'DRIVERS_LICENSE' | 0.0.1 |
Email | 'EMAIL' | 0.0.1 |
Geo | 'GEO' | 0.0.1 |
Isbn | 'ISBN' | 0.0.1 |
Phone | 'PHONE' | 0.0.1 |
Product | 'PRODUCT' | 0.0.1 |
Sms | 'SMS' | 0.0.1 |
Text | 'TEXT' | 0.0.1 |
Url | 'URL' | 0.0.1 |
Wifi | 'WIFI' | 0.0.1 |
Unknown | 'UNKNOWN' | 0.0.1 |
Terms & Privacy
This plugin uses the Google ML Kit:
Changelog
See CHANGELOG.md.
License
See LICENSE.
^1: This project is not affiliated with, endorsed by, sponsored by, or approved by Google LLC or any of their affiliates or subsidiaries.
^2: QR Code
is a registered trademark of DENSO WAVE INCORPORATED.