# Barcode Scanner Plugin

Tested Version: 1.6.1

This plugin provides a scanning barcode feature. Detect barcode or [QR Code](#user-content-fn-1)[^1]\[^1] by device's camera and returns extracted strings.

{% hint style="info" %}

### Important Notice (2025 Compliance)

To comply with the new **“16 KB page size requirement”** enforced by Google Play from **November 2025**,\
this plugin must be used with **version 1.6.1 or later**.

If you are currently using an older version in your project, please update as follows:

1. Open your project in **Monaca Cloud IDE**
2. Navigate to **Settings → Cordova Plugin Management**
3. Locate the **Barcode Scanner** plugin
4. Change the version to **1.6.1**, save the settings
5. Rebuild your project

No additional code changes are required — updating the plugin version is sufficient.
{% endhint %}

## Plugin ID

```
@monaca/monaca-plugin-barcode-scanner
```

## Adding the Plugin in Monaca

In order to use this plugin, please [enable](https://en.docs.monaca.io/products_guide/monaca_ide/dependencies/cordova_plugin#importing-cordova-plugins) `Barcode Scanner` plugin in Monaca Cloud IDE.

## Supported Platforms

### Build Environments

* Cordova 11.0.0 or later
* Android Platform 10.1.2 or later
* iOS Platform 6.2.0 or later

### Operating Environments

* Android 5.1 or later (9 or later recommended)
* iOS 11 or later (13 or later recommended)

## Supported Barcode Types

* QR\_CODE
* EAN\_8
* EAN\_13
* ITF
* CODE\_128
* CODE\_39

and more...

{% hint style="info" %}

* As of ver.1.4.0, we have expanded supported barcode types.\
  This plugin now scans almost all formats supported by the iOS or Android MKKit.
* In additional to the types mentioned above, following types will be scanned.
  * CODE\_93, AZTEC, DATA\_MATRIX, UPC\_E, and others.
* Some formats are exclusively supported on iOS.
  {% endhint %}

See [here](#about-detecting-barcode) for the caution of detection.

{% hint style="info" %}
Some devices may fail to detect barcodes. See [here](#barcode-detection-problem) for details.
{% endhint %}

## Features

### Scanning mode

* `Normal` mode (since v1.0.0) \
  The detected code is displayed on screen and selected by tapping(clicking).
* `One Shot` mode (since v1.1.0) \
  The first detected code is selected and screen closed automatically.

### Detection timeout message (since v1.1.0)

A Specified message can be displayed if no code is detected for a certain period.

### Torch light

The torch light can be turned on.<br>

## API Reference

### monaca.BarcodeScanner.scan()

```
monaca.BarcodeScanner.scan(successCallback, failCallback[, options])
```

* Calling `scan ()` will transition to the scanner screen.
* When the barcode is detected, the extracted character string is displayed below the frame.(`Normal` mode)
* Tap the string to return to the original screen and the string and barcode type will be returned to `successCallback`.
* In the case of `One Shot` mode, the first detected code is returned and screen is closed automatically.
* When returned to the original screen without selecting the string, the detection will be cancelled.\
  In order to return to the original screen, click the "Close" (X on the screen) button for iOS and the "Back" button for Android.

#### successCallback

`successCallback(result)`

result: following data

```
{
  data: {
    "text": "xxxxxxxx"  // detected string
    "format": "QR_CODE"  // barcode type
  },
  cancelled: false // detection cancelled(true) or not(false)
}
```

#### failCallback

`failCallback(error)`

error: error message(string)

| message             | description                       |
| ------------------- | --------------------------------- |
| "permission denied" | camera permission is not granted. |

### options

```
{
  "oneShot" : true,
  "timeoutPrompt" : {
    "show" : true,
    "timeout" : 5,
    "prompt" : "Not detected"
  },
  "torch" : {
    "enable" : true,
    "defaultOn" : false
  },
  "debug" : {
    "preview" : 0
  }
}
```

<table><thead><tr><th>parameter</th><th width="98">type</th><th>default value</th><th>description</th></tr></thead><tbody><tr><td>oneShot</td><td>boolean</td><td>false</td><td>Enable or disable One Shot mode.</td></tr><tr><td>timeoutPrompt.show</td><td>boolean</td><td>false</td><td>Show or hide detection timeout message.</td></tr><tr><td>timeoutPrompt.timeout</td><td>int</td><td>-</td><td>Period(in seconds) from when the barcode not detected until the message is displayed.</td></tr><tr><td>timeoutPrompt.prompt</td><td>string</td><td>"Barcode not detected"</td><td>Timeout message.</td></tr><tr><td>torch.enable</td><td>boolean</td><td>false</td><td>Enable torch light feature.</td></tr><tr><td>torch.defaultOn</td><td>boolean</td><td>false</td><td>Turn on torch by default.</td></tr><tr><td>debug.preview<br>(android only)</td><td>int</td><td>0</td><td>Debug Preview Mode(Android only) <br>Displays camera preview bitmap(before sending to MLKit) on screen. <br>0: OFF(default) 1: Inside detection area 2: Whole camera image</td></tr></tbody></table>

## Example

```javascript
  monaca.BarcodeScanner.scan((result) => {
    if (result.cancelled) {
      // scan cancelled
    } else {
      // scan
      const detected_text = result.data.text;
      const detected_format = result.data.format;
    }
  }, (error) => {
    // permission error
    const error_message = error;
  }, {
    "oneShot" : true,
    "timeoutPrompt" : {
      "show" : true,
      "timeout" : 5,
      "prompt" : "Not detected"
    },
    "torch" : {
      "enable" : true,
      "defaultOn" : false
    }
});
```

## iOS Quirks

Since iOS 10, it's mandatory to provide a usage description in the `info.plist`. \
The description string is displayed in the permission dialog box.

This plugin requires the following usage descriptions:

* `NSCameraUsageDescription` specifies the reason for your app to access the device's camera.

To add these entries to the `info.plist`, you can use the `<edit-config>` tag in the `config.xml` file like this:

```
    <platform name="ios">
        <edit-config target="NSCameraUsageDescription" file="*-Info.plist" mode="merge">
            <string>need camera access to scan barcode</string>
        </edit-config>
    </platform>
```

## Android Quirks

### compileSDKVersion <a href="#id-1-9-1" id="id-1-9-1"></a>

The library `androidx.camera:camera-view` used internally requires `compileSDKVersion>=31`. \
So `Target SDK Version` of `Android Application setting` in Monaca Cloud IDE should be set 31 or above.

### Barcode detection problem due to device model dependency <a href="#barcode-detection-problem" id="barcode-detection-problem"></a>

This plugin detects barcodes by processing the image captured by the camera (ImageProxy) and passing it to the barcode detection library (MLKit). \
ImageProxy can store images in a variety of formats, and it depends on the device what format the camera captures. \
Some devices may fail to detect barcodes because they are captured in a format not supported by the plugin.

#### Supported format

| version          | supported format                                                                                                                                                 |
| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| before ver.1.2.1 | <p>- Support <code>JPEG</code> or <code>YUV\_420\_888</code><br>- Support only when plane buffer's <code>rowStride</code> is same as <code>ImageWidth</code></p> |
| ver.1.3.0        | - Support when plane buffer's `rowStride` is different from `ImageWidth`                                                                                         |

#### How to check for unsupported image formats

You can check the device compatibility by using the `debug preview` feature added in ver.1.3.0.

* Enable `debug preview` in options

```javascript
  monaca.BarcodeScanner.scan((result) => {
    if (result.cancelled) {
      // scan cancelled
    } else {
      // scan
    }
  }, (error) => {
    // permission error
    const error_message = error;
  }, {
    "debug" : {
      "preview" : 1
    }
  });
```

* Thumbnail of the image before barcode detection are displayed on the scan screen.

If this thumbnail image is displayed distorted, it will be a device that does not support.

![](https://3091308003-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MfWe1U2tFctp8FkP9W8%2Fuploads%2F0gVpj71hi8bgL9aD1I6d%2Funsupported_device.png?alt=media\&token=d78a456b-9fd2-41c4-9e8e-0de7fa2d73e6)

## About detecting barcode <a href="#about-detecting-barcode" id="about-detecting-barcode"></a>

### ITF code (since ver.1.2.0)

* ver. 1.2.0
  * For iOS, only ITF-14 (14 digits ITF) is supported.
  * For Android, various digits ITF is supported.
* ver. 1.4.0
  * Various digits ITF is supported on iOS.

### Other barcode

* Because some barcode standard is prone to cause miss-detection, requiring the barcode to be exactly positioned within the detection area.

***

\[^1]: QR Code is a registered trademark of DENSO WAVE INCORPORATED in Japan and in other countries.

[^1]: QR Code is a registered trademark of DENSO WAVE INCORPORATED in Japan and in other countries.