capacitor-mlkit-barcode-scanning-videoelement v7.0.0

@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, iOS and web

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:

<uses-permission android:name="android.permission.CAMERA" />

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" -->

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.3.0)
• $playServicesCodeScannerVersion version of com.google.android.gms:play-services-code-scanner (default: 16.1.0)

iOS

Minimum Deployment Target

Make sure to set the deployment target in your ios/App/Podfile to at least 15.5:

platform :ios, '15.5'

Usage Description

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>

Web

Polyfill

This plugin uses the Barcode Detection API to scan barcodes in the browser. This API is not yet supported in all browsers. You can check the compatibility here. For this reason, we recommend installing the barcode-detector package for a better compatibility:

npm install barcode-detector

This package provides a polyfill that uses ZXing-C++ WebAssembly under the hood.

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';
import { Torch } from '@capawesome/capacitor-torch';

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 Torch.enable();
};

const disableTorch = async () => {
  await Torch.disable();
};

const toggleTorch = async () => {
  await Torch.toggle();
};

const isTorchEnabled = async () => {
  const { enabled } = await Torch.isEnabled();
  return enabled;
};

const isTorchAvailable = async () => {
  const { available } = await Torch.isAvailable();
  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()
• setZoomRatio(...)
• getZoomRatio()
• getMinZoomRatio()
• getMaxZoomRatio()
• openSettings()
• isGoogleBarcodeScannerModuleAvailable()
• installGoogleBarcodeScannerModule()
• checkPermissions()
• requestPermissions()
• addListener('barcodesScanned', ...)
• addListener('scanError', ...)
• addListener('googleBarcodeScannerModuleInstallProgress', ...)
• removeAllListeners()
• Interfaces
• Type Aliases
• Enums

startScan(...)

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

Start scanning for barcodes.

Since: 0.0.1

stopScan()

stopScan() => Promise<void>

Stop scanning for barcodes.

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.

Returns: Promise<IsSupportedResult>

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.

Returns: Promise<PermissionStatus>

Since: 0.0.1

requestPermissions()

requestPermissions() => Promise<PermissionStatus>

Request camera permission.

Returns: Promise<PermissionStatus>

Since: 0.0.1

addListener('barcodesScanned', ...)

addListener(eventName: 'barcodesScanned', listenerFunc: (event: BarcodesScannedEvent) => void) => Promise<PluginListenerHandle>

Called when barcodes are scanned.

Returns: Promise<PluginListenerHandle>

Since: 6.2.0

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

BarcodeCalendarEvent

BarcodeContactInfo

Address

BarcodeEmail

PersonName

BarcodePhone

BarcodeDriverLicense

BarcodeGeoPoint

BarcodeSms

BarcodeUrlBookmark

BarcodeWifi

ReadBarcodesFromImageOptions

ScanResult

ScanOptions

IsSupportedResult

SetZoomRatioOptions

GetZoomRatioResult

GetMinZoomRatioResult

GetMaxZoomRatioResult

IsGoogleBarcodeScannerModuleAvailableResult

PermissionStatus

PluginListenerHandle

BarcodesScannedEvent

ScanErrorEvent

GoogleBarcodeScannerModuleInstallProgressEvent

Type Aliases

CameraPermissionState

PermissionState | 'limited'

PermissionState

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

Enums

BarcodeFormat

LensFacing

Resolution

AddressType

EmailFormatType

PhoneFormatType

BarcodeValueType

WifiEncryptionType

GoogleBarcodeScannerModuleInstallState

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.