[Readme in english 🇬🇧] [Описание на русском 🇷🇺]
- Описание
- Использование
- Поддерживаемые типы сообщений
- Примеры кода
- Демо
- Поддержка
- Обратная связь
- Лицензия
Простая и компактная библиотека для Android, позволяющая эмулировать NDEF-форматированные сообщения через NFC антенну на Android устройстве используя host card emulation API
Полностью написана на Kotlin без использования других зависимостей.
Эта библиотека эмулирует метку "NFC Forum Type 4 Tag" содержащую NDEF-форматированное сообщение. Этот тип меток соответсвует всем техническим требованиям и подходит под все ограничения для того, чтобы его возможно было эмулировать на Android HCE интерфейсе. Эти тэги нативно поддерживаются в большинстве ПО которое умеет читать NDEF-форматированные метки по NFC. Также их чтение нативно поддерживают обе мобильные операционные системы, и Android, и iOS.
Этот репозиторий содержит саму библиотеку (ndefemulation) и демо приложение с ней (demo).
Для того чтобы использовать библиотеку в вашем проекте, добавьте её в список зависимостей в скрипте сборки build.gradle:
implementation 'com.luigivampa92:ndefemulation-android:1.0.0'
Все действия с библиотекой производятся через класс NdefEmulation.
Этот класс содержит свойство currentEmulatedNdefData (или геттер и сеттер getCurrentEmulatedNdefData()/setCurrentEmulatedNdefData() если вы используете Java) которое используется для управления данными, которые необходимо эмулировать.
Для того чтобы назначить эмулируемые данные или отключить эмуляцию вам потребуется объект Context.
Класс содержит конструктор который принимает объект Context.
Вы можете создать и использовать объект NdefEmulation в любом андроид компоненте (Activity, Service, etc) или предоставив экземпляр Context через DI.
Библиотека спроектирована с максимально простым интерфейсом, и вся работа с ней производится буквально в одну строчку кода.
Чтобы включить эмуляцию создайте нужное вам NDEF сообщение и назначьте его в свойство currentEmulatedNdefData объекта NdefEmulation:
NdefEmulation(context).currentEmulatedNdefData = UriNdefData("https://www.youtube.com/watch?v=dQw4w9WgXcQ")
Чтобы отключить эмуляцию просто назначьте null в свойство currentEmulatedNdefData объекта NdefEmulation:
NdefEmulation(context).currentEmulatedNdefData = null
| Тип | Класс | Android | iOS | Коментарий |
|---|---|---|---|---|
| Обычный URI | UriNdefData | ✅ | ✅ | Стандартный URI. Самая полезная штука, и то, что, вероятно, будет использоваться вами в 95% случаев. Здесь может быть использован любой обычный URI или URL. Переданное сообщение может быть использовано для того чтобы вызвать срабатывание IPC, открыть какое-то приложение, выполнить действие, и т.д. Полностью нативно работает и в Android, и в iOS |
| GEO-URI геолокации | LocationNdefData | ✅ | 🤷 | Точка геолокации. Нативно работает на Android, однако чтобы принять этот тип сообщения на iOS у вас должно быть установлено приложение поддерживающее схему URI geo:// (например "MapsMe") |
| Сырой текст | TextNdefData | ❌ | ❌ | Просто сырой текст. Несмотря на то что это самый простой тип сообщения, он не может быть интерпретирован из коробки ни на Android, ни на iOS без дополнительного ПО которое будет ожидать какое-то специфическое содержимое в нём. Мобильные ОС прочитают это сообщение, но не будут его парсить и не будут предпринимать никакие дополнительные действия |
| Подключение к WiFi | WifiNetworkNdefData | ✅ | ❌ | Информация о подключении к точке доступа Wifi — имя и пароль. Поддерживаются только типы аутентификации OPEN (без пароля) и WPA/WPA2-PSK (обычный пароль). EAP подключения с пользовательскими сертификатами не поддерживаются. Нативно работает только на Android, iOS на этот тип сообщения не реагирует |
| Визитка контакта | ContactNdefData | ✅ | ❌ | Запись о контакте в телефонной книге устройства, или же "визитка", в формате VCard. Нативно работает только на Android, iOS на этот тип сообщения не реагирует |
| Другой сырой NDEF | NdefRecordData | 🤷 | 🤷 | Любой объект типа NdefRecord из фреймворка Android может быть заэмулирован. Например, вы можете получить NDEF сообщение через intent в вашем приложении, а затем сразу же отправить её на эмуляцию, даже не доставая никакие данные из него. Очень полезно, однако сможет ли получающая сторона принять и интерпретировать сообщение полностью зависит от его содержимого |
- ✅ - Обозначает что упомянутая ОС будет нативно читать и парсить этот тип сообщения. Вам не потребуется никакое дополнительное ПО на устройстве что будет читать эмулируемый тэг. После того как сообщение будет доставлено на читающее устройство, вы получите на нём уведомление, или же устройство сразу исполнит какое-то действие
- ❌ - Обозначает что упомянутая ОС будет нативно читать этот тип сообщения, но не будет его парсить и не будет предпринимать никаких других действий. Некоторые сторонние приложения могут содержать реализации которые смогут обработать такое сообщение, но не сама ОС
- 🤷 - Обозначает "зависит от ситуации". Сообщение будет прочитано, но его дальнейшая обработка зависит от внешних обстоятельств
Некоторые примеры кода эмуляции сообщений различных типов
Отправить ссылку на Youtube видео в виде обычного HTTP URL:
NdefEmulation(this).currentEmulatedNdefData = UriNdefData("https://www.youtube.com/watch?v=dQw4w9WgXcQ")
Отправить ссылку на Youtube видео в виде deeplink URI:
NdefEmulation(this).currentEmulatedNdefData = UriNdefData("vnd.youtube://www.youtube.com/watch?v=dQw4w9WgXcQ")
Открыть диалог в приложении WhatsApp по номеру телефона:
NdefEmulation(this).currentEmulatedNdefData = UriNdefData("https://wa.me/79123456789")
Открыть диалог в приложении Telegram по номеру телефона:
NdefEmulation(this).currentEmulatedNdefData = UriNdefData("tg://msg?to=+79123456789")
Просто отправить сырой текст:
NdefEmulation(this).currentEmulatedNdefData = TextNdefData("Whiskey Tango Foxtrot")
Отправить точку геолокации:
NdefEmulation(this).currentEmulatedNdefData = LocationNdefData(12.345678, 78.654321)
Отправить имя и пароль точки доступа WiFi:
NdefEmulation(this).currentEmulatedNdefData = WifiNetworkNdefData("YourWifiName", WifiNetworkNdefDataProtectionType.PASSWORD, "YourWifiPassword")
Отправить запись о контакте в телефонную книгу:
NdefEmulation(this).currentEmulatedNdefData = ContactNdefData("John", "Doe", "+12345678900")
Демо приложения могут быть найдены в Releases.
Вы можете скачать демо приложения с новейшей версией библиотеки здесь.
Есть версия демо приложения под смартфоны и под часы
Вы также можете собрать демо приложения самостоятельно из исходного кода:
./gradlew clean assemblePhoneRelease
./gradlew clean assembleWatchRelease
- Поставьте звёдочку этому репозиторию на GitHub ⭐
Вы можете предоставить обратную связь, предложить идеи для новых фич или просто задать вопросы по теме тут:
Текст лицензии располагается в файле LICENSE.