@capacitor-mlkit/barcode-scanning v7.2.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

Guides

• How to build an Ionic Barcode Scanner with Capacitor

Installation

npm install @capacitor-mlkit/barcode-scanning
npx cap sync

Android

Permissions

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"/>
<!-- To use multiple models: android:value="face,model2,model3" -->

Data Binding

Enable the databinding library by setting the dataBinding and enabled build options to true in your module-level (app-level) Gradle file (usually android/app/build.gradle):

android {
    ...
+    buildFeatures {
+        dataBinding true
+    }
+    dataBinding {
+        enabled = true
+    }
}

Variables

This plugin will use the following project variables (defined in your app’s variables.gradle file):

• $androidxCameraCamera2Version version of com.google.mlkit:barcode-scanning (default: 1.1.0)
• $androidxCameraCoreVersion version of com.google.mlkit:barcode-scanning (default: 1.1.0)
• $androidxCameraLifecycleVersion version of com.google.mlkit:barcode-scanning (default: 1.1.0)
• $androidxCameraViewVersion version of com.google.mlkit:barcode-scanning (default: 1.1.0)
• $mlkitBarcodeScanningVersion version of com.google.mlkit:barcode-scanning (default: 17.1.0)
• $playServicesCodeScannerVersion version of com.google.mlkit:barcode-scanning (default: 16.0.0)

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>

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],
  });
  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 setZoomRatio = async () => {
  await BarcodeScanner.setZoomRatio({ zoomRatio: 0.5 });
};

const getZoomRatio = async () => {
  const { zoomRatio } = await BarcodeScanner.getZoomRatio();
  return zoomRatio;
};

const getMinZoomRatio = async () => {
  const { zoomRatio } = await BarcodeScanner.getMinZoomRatio();
  return zoomRatio;
};

const getMaxZoomRatio = async () => {
  const { zoomRatio } = await BarcodeScanner.getMaxZoomRatio();
  return zoomRatio;
};

const openSettings = async () => {
  await BarcodeScanner.openSettings();
};

const isGoogleBarcodeScannerModuleAvailable = async () => {
  const { available } =
    await BarcodeScanner.isGoogleBarcodeScannerModuleAvailable();
  return available;
};

const installGoogleBarcodeScannerModule = async () => {
  await BarcodeScanner.installGoogleBarcodeScannerModule();
};

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 Framework 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 Framework 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()
• setZoomRatio(...)
• getZoomRatio()
• getMinZoomRatio()
• getMaxZoomRatio()
• openSettings()
• isGoogleBarcodeScannerModuleAvailable()
• installGoogleBarcodeScannerModule()
• checkPermissions()
• requestPermissions()
• addListener('barcodeScanned', ...)
• addListener('scanError', ...)
• addListener('googleBarcodeScannerModuleInstallProgress', ...)
• removeAllListeners()
• Interfaces
• Type Aliases
• Enums

startScan(...)

startScan(options?: StartScanOptions | undefined) => Promise<void>

Start scanning for barcodes.

Only available on Android and iOS.

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.

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, this method is only available on devices with Google Play Services installed. Therefore, no camera permission is required.

Attention: Before using this method on Android, first check if the Google Barcode Scanner module is available by using isGoogleBarcodeScannerModuleAvailable().

Only available on Android and iOS.

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

setZoomRatio(...)

setZoomRatio(options: SetZoomRatioOptions) => Promise<void>

Set the zoom ratio of the camera.

Only available on Android and iOS.

Since: 5.4.0

getZoomRatio()

getZoomRatio() => Promise<GetZoomRatioResult>

Get the zoom ratio of the camera.

Only available on Android and iOS.

Returns: Promise<GetZoomRatioResult>

Since: 5.4.0

getMinZoomRatio()

getMinZoomRatio() => Promise<GetMinZoomRatioResult>

Get the minimum zoom ratio of the camera.

Only available on Android and iOS.

Returns: Promise<GetMinZoomRatioResult>

Since: 5.4.0

getMaxZoomRatio()

getMaxZoomRatio() => Promise<GetMaxZoomRatioResult>

Get the maximum zoom ratio of the camera.

Only available on Android and iOS.

Returns: Promise<GetMaxZoomRatioResult>

Since: 5.4.0

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

isGoogleBarcodeScannerModuleAvailable()

isGoogleBarcodeScannerModuleAvailable() => Promise<IsGoogleBarcodeScannerModuleAvailableResult>

Check if the Google Barcode Scanner module is available.

If the Google Barcode Scanner module is not available, you can install it by using installGoogleBarcodeScannerModule().

Only available on Android.

Returns: Promise<IsGoogleBarcodeScannerModuleAvailableResult>

Since: 5.1.0

installGoogleBarcodeScannerModule()

installGoogleBarcodeScannerModule() => Promise<void>

Install the Google Barcode Scanner module.

Attention: This only starts the installation. The googleBarcodeScannerModuleInstallProgress event listener will notify you when the installation is complete.

Only available on Android.

Since: 5.1.0

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>

Called when a barcode is scanned.

Available on Android and iOS.

Returns: Promise<PluginListenerHandle>

Since: 0.0.1

addListener('scanError', ...)

addListener(eventName: 'scanError', listenerFunc: (event: ScanErrorEvent) => void) => Promise<PluginListenerHandle>

Called when an error occurs during the scan.

Available on Android and iOS.

Returns: Promise<PluginListenerHandle>

Since: 0.0.1

addListener('googleBarcodeScannerModuleInstallProgress', ...)

addListener(eventName: 'googleBarcodeScannerModuleInstallProgress', listenerFunc: (event: GoogleBarcodeScannerModuleInstallProgressEvent) => void) => Promise<PluginListenerHandle>

Called when the Google Barcode Scanner module is installed.

Available on Android.

Returns: Promise<PluginListenerHandle>

Since: 5.1.0

removeAllListeners()

removeAllListeners() => Promise<void>

Remove all listeners for this plugin.

Since: 0.0.1

Interfaces

StartScanOptions

ReadBarcodesFromImageResult

Barcode

ReadBarcodesFromImageOptions

ScanResult

ScanOptions

IsSupportedResult

IsTorchEnabledResult

IsTorchAvailableResult

SetZoomRatioOptions

GetZoomRatioResult

GetMinZoomRatioResult

GetMaxZoomRatioResult

IsGoogleBarcodeScannerModuleAvailableResult

PermissionStatus

PluginListenerHandle

BarcodeScannedEvent

ScanErrorEvent

GoogleBarcodeScannerModuleInstallProgressEvent

Type Aliases

CameraPermissionState

PermissionState | 'limited'

PermissionState

'prompt' | 'prompt-with-rationale' | 'granted' | 'denied'

Enums

BarcodeFormat

LensFacing

BarcodeValueType

GoogleBarcodeScannerModuleInstallState

Common Issues

NullPointerException during startScan(...)

The following error may occur when calling the startScan(...) method: Attempt to invoke virtual method 'void androidx.camera.view.PreviewView.setScaleType(androidx.camera.view.PreviewView$ScaleType)' on a null object reference. In this case, make sure that the databinding library is enabled (see Data Binding).

Terms & Privacy

This plugin uses the Google ML Kit:

• Terms & Privacy
• Android Data Disclosure
• iOS Data Disclosure

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.