[Readme in english 🇬🇧] [Описание на русском 🇷🇺]
Tiny and effective library for Android that allows you to emulate NDEF formatted messages via Android device NFC antenna, using the Android host card emulation API.
The library is written in Kotlin and has no extra dependencies.
This library emulates the "NFC Forum Type 4" tag that contains an NDEF-formatted message. That type of tag meets all the technical requirements and fits all the restrictions to be emulated via the Android HCE interface. It is also natively supported in most of the software products that can read NDEF-formatted messages via NFC, and it is also natively supported on both mobile operating systems, Android and iOS.
This repository contains the library itself (ndefemulation) and the demo application (demo).
To use the library in your project, simply add it to your dependencies in the build.gradle build script:
implementation 'com.luigivampa92:ndefemulation-android:1.0.0'
All actions are performed through the NdefEmulation class.
This class contains property currentEmulatedNdefData (or getCurrentEmulatedNdefData()/setCurrentEmulatedNdefData() methods if you use Java) that is used to set the data that must be emulated.
You will need the Context object to set the current emulated NDEF message or to disable the emulation.
The class has the constructor that accepts the Context.
You can create and use the NdefEmulation object in any Android component (Activity, Service, etc) or by providing the Context object via the DI.
The library interface is very simple and basically fits in just a single line of code.
To enable the emulation, create the required NDEF message object and set it to the currentEmulatedNdefData property of NdefEmulation:
NdefEmulation(context).currentEmulatedNdefData = UriNdefData("https://www.youtube.com/watch?v=dQw4w9WgXcQ")
To disable the emulation of NDEF messages simply set null to the currentEmulatedNdefData property in NdefEmulation:
NdefEmulation(context).currentEmulatedNdefData = null
| Type | Class | Android | iOS | Comment |
|---|---|---|---|---|
| Normal URI | UriNdefData | ✅ | ✅ | The standard URI. The most useful thing and something that you will probably use in 95% of cases. Any normal URI and URL can be used here. The transferred message can be used to trigger IPC, open apps, perform actions, etc. Perfectly and natively works on both Android and iOS |
| Location GEO-URI | LocationNdefData | ✅ | 🤷 | Geolocation point. Works natively on Android; however, to properly receive this kind of message on iOS, you must have an application that supports the geo:// URI scheme installed (like "MapsMe" for instance) |
| Raw Text | TextNdefData | ❌ | ❌ | Simple raw text. While it is the simplest type of message, it cannot be interpreted out-of-the-box by neither Android nor iOS without the special software that will expect some specific content in it. The OS will read this message but will not parse it or do anything else |
| WiFi Connection | WifiNetworkNdefData | ✅ | ❌ | Wifi access point connection data — name and password. Only OPEN (no password) and WPA/WPA2-PSK (standard password) types of wifi are supported. The EAP connections with user certificates are not supported. Works natively only on Android; iOS does not react to this type of message |
| Phonebook Contact | ContactNdefData | ✅ | ❌ | Phonebook contact data in the VCard format. Works natively only on Android; iOS does not react to this type of message |
| Another Raw NDEF | NdefRecordData | 🤷 | 🤷 | Any object of the NdefRecord class from the Android framework can be emulated. For example, you can receive an NDEF record by intent in your application and then set it to be emulated without even parsing it. Very useful, but whether it will be received or not on the reader side depends on the message contents |
- ✅ - Means that the mentioned OS can natively read and parse that type of message. You do not need any specific third-party applications on the device that will read the emulated tag. After the message is transferred to the reading device, you will see some notification that some action will be performed right away
- ❌ - Means that the mentioned OS can natively read but will not parse that type of message and will not perform any actions after it. Some third-party applications may have the implementations that will handle this type of message but not the OS itself
- 🤷 - Means that "it depends" The message will be read, but its further handling depends on extra circumstances
Some code examples of emulating the messages of various types
Send the Youtube video by the HTTP URL:
NdefEmulation(this).currentEmulatedNdefData = UriNdefData("https://www.youtube.com/watch?v=dQw4w9WgXcQ")
Send the Youtube video by the deeplink URI:
NdefEmulation(this).currentEmulatedNdefData = UriNdefData("vnd.youtube://www.youtube.com/watch?v=dQw4w9WgXcQ")
Open the WhatsApp dialog by a phone number:
NdefEmulation(this).currentEmulatedNdefData = UriNdefData("https://wa.me/79123456789")
Open the Telegram dialog by a phone number:
NdefEmulation(this).currentEmulatedNdefData = UriNdefData("tg://msg?to=+79123456789")
Send some raw text:
NdefEmulation(this).currentEmulatedNdefData = TextNdefData("Whiskey Tango Foxtrot")
Send the geolocation point:
NdefEmulation(this).currentEmulatedNdefData = LocationNdefData(12.345678, 78.654321)
Send the WiFi access point name and password:
NdefEmulation(this).currentEmulatedNdefData = WifiNetworkNdefData("YourWifiName", WifiNetworkNdefDataProtectionType.PASSWORD, "YourWifiPassword")
Send the phonebook contact data:
NdefEmulation(this).currentEmulatedNdefData = ContactNdefData("John", "Doe", "+12345678900")
The demo applications can be found and downloaded in Releases.
You can download the demo apps for the latest library version here.
There are versions for the smartphones and for the watches
You can also build the demo applications yourself from the sources:
./gradlew clean assemblePhoneRelease
./gradlew clean assembleWatchRelease
- Star this GitHub repository ⭐
You can provide your feedback, suggest ideas for the new features or simply ask the questions here:
Please see the LICENSE for details.