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

Додавання IoT-пристроїв за серійним номером у мобільному додатку

Додавання за серійним номером — резервний спосіб для випадків, коли наклейка QR пошкоджена або відсутня. Користувач вводить або сканує серійний номер вручну, система знаходить пристрій та прив'язує його до облікового запису. Завдання просте за суттю, але потребує акуратної валідації та гарного UX для форми вводу.

Формати серійних номерів

Серійний номер — не довільна строка. У кожного виробника свій формат:

• SN-XXXXXXXX — 8 шістнадцятирічних символів після префіксу
• AAAA-BBBB-CCCC-DDDD — групи по 4 символи (аналог ключа активації)
• MAC-адреса як серійний номер — AA:BB:CC:DD:EE:FF
• Числовий код — 12345678901

Формат має бути відомий заздалегідь — він визначає маску вводу та валідатор. Якщо серійний номер завжди 12 символів, користувач не повинен вгадувати — поле має показати маску та приймати лише потрібний формат.

UI форми вводу

Ключові вимоги до поля серійного номера:

Вимкніть автозаголовне та автокорекцію. inputType="textNoSuggestions|textCapCharacters" на Android. На iOS: autocorrectionType = .no, autocapitalizationType = .allCharacters. Автокорекція перетворює ABC123 на Abc123 — пристрій не буде знайдено.

Маска вводу. Для формату XXXX-XXXX-XXXX — вставляйте дефіси автоматично під час вводу. На Android: TextWatcher з обробкою позиції курсора:

editText.addTextChangedListener(object : TextWatcher {
    private var isFormatting = false

    override fun afterTextChanged(s: Editable) {
        if (isFormatting) return
        isFormatting = true
        val digits = s.toString().filter { it.isLetterOrDigit() }.uppercase()
        val formatted = digits.chunked(4).joinToString("-").take(14)
        s.replace(0, s.length, formatted)
        isFormatting = false
    }
    override fun beforeTextChanged(s: CharSequence?, start: Int, count: Int, after: Int) {}
    override fun onTextChanged(s: CharSequence?, start: Int, before: Int, count: Int) {}
})

Сканування камерою як альтернатива вводу. Серійний номер часто надрукований штрихкодом на задній панелі пристрою. Кнопка «Сканувати» поруч із полем. ML Kit або ZXing для Code 128 / Code 39.

Валідація перед API-запитом

Локальна валідація перед відправкою запиту:

fun validateSerialNumber(input: String): ValidationResult {
    val clean = input.filter { it.isLetterOrDigit() }.uppercase()
    return when {
        clean.length < 8 -> ValidationResult.TooShort
        clean.length > 16 -> ValidationResult.TooLong
        !clean.matches(Regex("[A-Z0-9]+")) -> ValidationResult.InvalidChars
        else -> ValidationResult.Valid(clean)
    }
}

Показуйте помилку валідації inline — під полем, не у alert. Користувач бачить проблему одразу й виправляє її без втрати введених даних.

API: Пошук та прив'язка пристрою

Двохетапний процес:

Крок 1 — пошук пристрою:

GET /api/devices/lookup?serial=ABC12345678

Відповідь: тип пристрою, модель, статус (доступно / вже прив'язано до іншого облікового запису / не існує). Показати користувачу що саме знайдено — «Датчик температури модель T200» — перед підтвердженням прив'язки.

Крок 2 — прив'язка:

POST /api/devices/claim
{ "serial": "ABC12345678", "name": "Датчик на балконі" }

Серійний номер не дорівнює claim-токену — це різні речі. Серійний номер публічний, по ньому знаходять пристрій. Прив'язка потребує аутентифікації користувача (JWT у заголовку), інакше будь-хто міг би вкрасти пристрій.

Обробка помилок

Для 409 — запропонуйте «Це ваш пристрій?» з кнопкою звернення до підтримки. Інакше користувачі з куплених б/в пристроїв опиняться в глухому куті.

Реалізація додавання за серійним номером з валідацією та двохетапною прив'язкою: 1 тиждень. Стоимость рассчитывается индивидуально.