Реалізація підключення IoT-пристрою через QR-код у мобільному додатку

Прив'язування IoT-пристрою через QR-код у мобільному додатку

QR-паринг — найшвидший спосіб додати IoT-пристрій: користувач сканує наклейку на пристрої, додаток витягує ідентифікатор та автоматично прив'язує його до облікового запису. Без введення серійних номерів, без Bluetooth-сканування. При правильній реалізації весь процес займає 10–15 секунд.

Що кодується в QR

QR-код на IoT-пристрої може містити:

• Серійний номер / Device ID (SN:ABC12345)
• MAC-адресу (MAC:AA:BB:CC:DD:EE:FF)
• Claim-токен для прив'язки до конкретного користувача
• Matter provisioning code (MT:Y.K90SO527JA0648G00)
• Користувацький URL з параметрами (https://app.example.com/pair?id=ABC&key=xyz)

Matter використовує числовий Setup Code, вбудований в QR під час виробництва — 11-значний код плюс метаданні. Формат строго стандартизований у специфікації Matter (MTR-006).

Для власних пристроїв — рекомендую URL-схему або Base64 JSON. URL-схема дозволяє відкрити додаток прямо з системної камери через Deep Link, без відкриття браузера.

Сканування: ML Kit Barcode

ML Kit Barcode Scanning — найкращий вибір для Android: підтримує QR, DataMatrix, PDF417, працює офлайн:

val options = BarcodeScannerOptions.Builder()
    .setBarcodeFormats(Barcode.FORMAT_QR_CODE)
    .build()

val scanner = BarcodeScanning.getClient(options)

// У CameraX ImageAnalysis
scanner.process(inputImage)
    .addOnSuccessListener { barcodes ->
        barcodes.firstOrNull()?.rawValue?.let { qrData ->
            viewModel.onQrScanned(qrData)
            // Зупинити камеру після першого успішного сканування
            cameraProvider.unbindAll()
        }
    }

Важливо зупинити камеру після першого сканування — інакше ML Kit буде викликано кілька разів на один QR. Дебаунс через AtomicBoolean isScanning або Flow.distinctUntilChanged().

На iOS — фреймворк Vision + AVCaptureSession або DataScannerViewController (iOS 16+):

// iOS 16+ — найпростіший шлях
let scanner = DataScannerViewController(
    recognizedDataTypes: [.barcode(symbologies: [.qr])],
    isHighlightingEnabled: true
)
scanner.delegate = self
try? scanner.startScanning()

// delegate
func dataScanner(_ dataScanner: DataScannerViewController,
                 didTapOn item: RecognizedItem) {
    if case .barcode(let barcode) = item {
        handleQrData(barcode.payloadStringValue ?? "")
    }
}

DataScannerViewController на iOS 16+ замінює користувацькі реалізації AVCaptureSession — простіше, з вбудованим UI підсвітки.

Парсинг та валідація даних QR

Дані з QR потребують захищеного парсингу — користувач може навести камеру на будь-який QR, не лише на пристрій:

data class DeviceQrPayload(
    val deviceId: String,
    val claimToken: String,
    val productType: String
)

fun parseQrCode(raw: String): DeviceQrPayload? {
    return try {
        // URL-формат: myapp://pair?id=ABC&token=XYZ&type=sensor
        val uri = Uri.parse(raw)
        if (uri.scheme != "myapp" || uri.host != "pair") return null
        DeviceQrPayload(
            deviceId = uri.getQueryParameter("id") ?: return null,
            claimToken = uri.getQueryParameter("token") ?: return null,
            productType = uri.getQueryParameter("type") ?: "unknown"
        )
    } catch (e: Exception) { null }
}

null при будь-якій помилці парсингу — не крах. Показати користувачу «Невпізнаний QR-код».

Прив'язка до облікового запису: API-виклик

Після парсингу QR — запит до сервера для прив'язки пристрою до облікового запису користувача:

POST /api/devices/claim
{
  "device_id": "ABC12345",
  "claim_token": "eyJhbGci...",
  "device_name": "Датчик температури кухні"
}

Claim-токен — одноразовий, генерується при виробництві, зберігається в базі. Після першої успішної прив'язки — інвалідується. Це захист від того, що чужий QR опиниться у постороннього користувача.

Matter QR обробляється інакше: Google Home SDK або Apple HomeKit Framework самі розшифровують setup payload та виконують commissioning. Додатку не потрібно робити backend-виклик — Matter платформа займається цим.

UX після сканування

Не показуйте пустий екран завантаження. Як тільки QR розпізнаний — покажіть дані пристрою (тип, серійний номер, коротке опис) та кнопку «Додати». Користувач підтверджує. Лише тоді — прив'язка до облікового запису.

Це захист від випадкового сканування: користувач бачить, що саме додається, та може скасувати.

Реалізація QR-парингу з прив'язкою до облікового запису: 1–2 тижні. Стоимість рассчитывается индивидуально.