Реализация подключения 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-значный код плюс metadata. Формат строго стандартизирован в 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 framework + 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 недели. Стоимость рассчитывается индивидуально.