# Rokid Glass3 QRCode Scanner SDK Integration Guide

`scanner` is the Rokid Glass3 QR code and barcode scanning SDK. It supports two usage modes:

- Open the SDK built-in scanner page and scan QR codes through the camera in real time.
- Pass in a `Bitmap` and recognize QR codes directly from the image.

## 1. Add the dependency

Add the dependency in the App module `build.gradle` file:

```groovy
dependencies {
    implementation 'com.rokid.security.glass3.qrcode:scanner:1.0.3'
}
```

If your project uses Kotlin DSL:

```kotlin
dependencies {
    implementation("com.rokid.security.glass3.qrcode:scanner:1.0.3")
}
```

## 2. Open the scanner page

Use this mode when your app needs to start the camera and scan in real time.

```kotlin
import com.google.mlkit.vision.barcode.common.Barcode
import com.rokid.security.glass3.qrcode.api.GlassScanCallback
import com.rokid.security.glass3.qrcode.api.GlassScanner

GlassScanner.launch(
    activity = this,
    scanCallback = object : GlassScanCallback {
        override fun onScanSuccess(content: String?, barcode: Barcode) {
            log("Scan succeeded: $content")
        }

        override fun onScanFailure(error: String) {
            log("Scan failed: $error")
        }

        override fun onScanCancelled() {
            log("Scan cancelled by user")
        }
    }
)
```

By default, after a code is recognized, the SDK closes the scanner page automatically and returns the result through `onScanSuccess`.

## 3. Scan a Bitmap image

Use this mode to recognize QR codes from album images, screenshots, network images, or an existing business-side `Bitmap`. This mode does not open the scanner page.

```kotlin
import com.google.mlkit.vision.barcode.common.Barcode
import com.rokid.security.glass3.qrcode.api.GlassScanCallback
import com.rokid.security.glass3.qrcode.api.GlassScanner

val bitmap = FileUtils.loadBitmapFromAssets(this, "qrcode.jpg") ?: run {
    log("Failed to load QR code image")
    return
}

GlassScanner.scanFromBitmap(
    context = this,
    bitmap = bitmap,
    callback = object : GlassScanCallback {
        override fun onScanSuccess(content: String?, barcode: Barcode) {
            log("Scan succeeded. content=$content, barcode=${barcode.rawValue}")
        }

        override fun onScanFailure(error: String) {
            log("Scan failed: $error")
        }
    }
)
```

## 4. Customize scan configuration

`GlassScanner.launch(...)` supports passing in `GlassScanConfig`.

```kotlin
import com.rokid.security.glass3.qrcode.model.GlassScanConfig
import com.rokid.security.glass3.qrcode.model.ScanType

val config = GlassScanConfig(
    scanType = ScanType.QR_CODE_ONLY,
    enableAutoClose = true,
    customTitle = "Scan QR code"
)

GlassScanner.launch(
    activity = this,
    config = config,
    scanCallback = object : GlassScanCallback {
        override fun onScanSuccess(content: String?, barcode: Barcode) {
            log("Scan succeeded: $content")
        }

        override fun onScanFailure(error: String) {
            log("Scan failed: $error")
        }
    }
)
```

Configuration options:

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `scanType` | `ScanType` | `ScanType.QR_CODE_ONLY` | Scan type. Available values: `QR_CODE_ONLY` or `ALL_FORMATS`. |
| `enableAutoClose` | `Boolean` | `true` | Whether to close the scanner page automatically after a successful scan. |
| `customTitle` | `String?` | `null` | Scanner page title. If empty, the SDK default title is used. |

`ScanType` values:

| Enum | Description |
| --- | --- |
| `QR_CODE_ONLY` | Recognizes QR codes only. |
| `ALL_FORMATS` | Recognizes all supported barcode formats, including QR codes and one-dimensional barcodes. |

## 5. Callback reference

Implement `GlassScanCallback` to receive scan results.

```kotlin
interface GlassScanCallback {
    fun onScanSuccess(content: String?, barcode: Barcode)

    fun onScanFailure(error: String)

    fun onScanCancelled() {}
}
```

| Callback | Trigger |
| --- | --- |
| `onScanSuccess(content, barcode)` | Scan succeeded. `content` is the recognized content, and `barcode` is the original ML Kit `Barcode` object. |
| `onScanFailure(error)` | Scan failed, initialization failed, or no QR code was recognized in the image. |
| `onScanCancelled()` | The user exits the scanner page with the Back key. Implement this callback when needed. |

## 6. Complete example

```kotlin
class MainActivity : AppCompatActivity() {

    private fun startQRCodeScan() {
        GlassScanner.launch(
            activity = this,
            config = GlassScanConfig(
                scanType = ScanType.QR_CODE_ONLY,
                enableAutoClose = true,
                customTitle = "Scan QR code"
            ),
            scanCallback = object : GlassScanCallback {
                override fun onScanSuccess(content: String?, barcode: Barcode) {
                    log("Scan succeeded: $content")
                }

                override fun onScanFailure(error: String) {
                    log("Scan failed: $error")
                }

                override fun onScanCancelled() {
                    log("Scan cancelled by user")
                }
            }
        )
    }

    private fun scanImage(bitmap: Bitmap) {
        GlassScanner.scanFromBitmap(
            context = this,
            bitmap = bitmap,
            scanType = ScanType.QR_CODE_ONLY,
            callback = object : GlassScanCallback {
                override fun onScanSuccess(content: String?, barcode: Barcode) {
                    log("Image scan succeeded: $content")
                }

                override fun onScanFailure(error: String) {
                    log("Image scan failed: $error")
                }
            }
        )
    }
}
```
