NFC в мини-приложении MAX: эмулировать метку, не прочитать

Единственная подсистема только для Android

Документация MAX Bridge описывает работу с NFC одной короткой фразой:

Сразу следом — предупреждение, которого нет ни у одной из четырнадцати других подсистем той же библиотеки (данные инициализации, экран, номер телефона, ссылки, файлы, шеринг, QR-коды, кнопка «Назад», два вида хранилища, биометрия, тактильные отклики):

Для мини-приложения, открытого на iPhone, объекта NfcManager в собственном смысле просто нет — вызывать его методы там не для чего, платформа не выполняет ни одного из них.

Три проверки вместо одной

Прежде чем звать любой другой метод, документация требует вызвать window.WebApp.NfcManager.init(). Он возвращает не простое «да» или «нет», а объект из трёх независимых полей, каждое из которых описано отдельно:

Первое поле проверяет железо, второе — системный тумблер NFC, который выключен на большинстве телефонов по умолчанию. А третье — это отдельное разрешение внутри самого MAX: пользователь может держать NFC включённым в системе и всё равно запретить конкретному мини-приложению им пользоваться, в настройках приватности мессенджера, а не телефона. В интерфейсе TypeScript поле accessRevoked помечено вопросительным знаком — необязательное, оно появляется в ответе не всегда.

Переход в настройки, который срабатывает не всегда

Если проверка показала, что NFC выключен, мини-приложение может одной командой отправить пользователя в системные настройки:

У метода есть условие, которое легко упустить при чтении по диагонали:

То есть кнопка «включить NFC» в интерфейсе бота не может звать этот метод вслепую при каждом нажатии — переход и закрытие мини-приложения произойдут только тогда, когда NFC действительно выключен. Если пользователь просто отозвал доступ для этого мини-приложения (поле accessRevoked), сам NFC на телефоне остаётся включённым — и метод молча ничего не откроет.

Эмулировать метку — не значит прочитать чужую

У объекта NfcManager всего четыре метода: init(), isInited, openSystemSettings() и один рабочий — emulateNfcTag(nfctag). Ни один из них не отвечает за сканирование чужой метки или банковской карты. Документация описывает единственное действие, доступное разработчику:

Название метода — не фигура речи: телефон в этом режиме не читает метку, а сам становится ей, транслируя переданную мини-приложением строку в сторону считывающего терминала. Остановить трансляцию можно тем же методом, не выключая NFC:

Тот же трюк уже работает без единой строчки кода

Ровно этот физический приём — телефон вместо карты — в MAX уже встроен в интерфейс, но как готовая функция, а не программный интерфейс для мини-приложений. Справка MAX описывает Цифровой ID:

Устройство пересказывает эту функцию в отдельном разборе — как приложить телефон к терминалу для Цифрового ID. Разница в адресате: там телефон транслирует один заранее выпущенный документ через встроенный экран настроек, здесь — любую строку, которую соберёт само мини-приложение через emulateNfcTag. Механизм передачи один и тот же, но для сторонних мини-приложений он не автоматический — им нужно пройти три проверки из предыдущего раздела и вызвать метод самим.

Ошибка без списка кодов

Про отказ методы объекта договариваются одной общей фразой:

Структура объекта ошибки — { error: { code: string } }. Само поле code — просто строка: страница не прикладывает таблицу значений, которые оно может принять, ни для NFC, ни для остальных методов Bridge. Различить «модуль выключен», «доступ отозван» и «телефон не поддерживает NFC» после отказа придётся заранее — тем самым методом init(), а не разбором кода ошибки.

Частые вопросы