How WebNFC on Android Chromium Reads and Writes NDEF Tags

This article explains the technical process of how the WebNFC API on the Android version of the Chromium web browser interacts with physical smart tags. It covers the complete lifecycle of reading and writing NFC Data Exchange Format (NDEF) messages, detailing the communication bridge between JavaScript in the browser, the Android operating system, the device's NFC hardware controller, and the physical tag when a user taps their phone against it.

The Communication Bridge: Browser to Hardware

The WebNFC API does not communicate directly with a phone's NFC antenna. Instead, it acts as a bridge. When a web application uses the WebNFC API, the Chromium browser translates JavaScript commands into native Android API calls.

Before any NFC operation can occur, Chromium enforces strict security rules. The website must be served over HTTPS, the web page must be visible in the foreground, and the user must explicitly trigger the NFC action through a physical gesture, such as tapping a button on the screen. Once granted permission, Chromium communicates with Android's native NfcAdapter system service to manage the hardware.

The Physical Connection

When an Android phone with an active NFC controller is brought within a few centimeters of a physical smart tag, the hardware initiates a connection:

  1. Inductive Coupling: The phone's NFC antenna emits a small radio frequency (RF) electromagnetic field.
  2. Powering the Tag: The physical smart tag, which usually has no battery of its own, absorbs energy from this RF field to power its tiny microchip.
  3. Handshake: The tag modulates the RF field to send its unique identifier (UID) and formatting data back to the phone.
  4. Format Verification: The Android OS checks if the tag is formatted for NDEF, which is the lightweight binary message format standardized for NFC communication. WebNFC only interacts with NDEF-compatible tags.

How WebNFC Reads an NDEF Tag

Reading a tag involves passing data from the physical tag up through the operating system to the web application.

  1. Initiating the Scan: The web developer instantiates an NDEFReader object in JavaScript and calls the scan() method.
  2. OS Registration: Chromium requests the Android OS to enable "Reader Mode" or foreground dispatch. This tells Android to route any detected NDEF tags directly to the browser rather than triggering a default system app.
  3. Tag Detection: The user touches the phone to the smart tag. The phone's NFC controller reads the raw binary data from the tag's memory.
  4. OS to Browser Translation: Android packages the raw binary into a native NDEF message and passes it to Chromium. Chromium parses this native object and converts it into a WebNFC NDEFReadingEvent.
  5. JavaScript Execution: The reading event fires in the browser. The web application accesses the data through an array of NDEFRecord objects, which contain the record type (such as plain text, a URL, or a MIME type) and the actual data payload, which JavaScript decodes for the user.

How WebNFC Writes to an NDEF Tag

Writing data reverses the flow, taking input from the web page and encoding it onto the physical microchip.

  1. Preparing the Data: The web application calls the write() method on the NDEFReader object, passing in the data to be written (such as a simple text string, a URL, or a complex array of records).
  2. Formatting to NDEF: Chromium takes the JavaScript input and serializes it into a standardized binary NDEF message. It then waits for the Android OS to detect a tag.
  3. Tag Connection: The user touches the phone to the physical tag. The Android OS establishes the RF connection and verifies that the tag is not locked (read-only) and has enough memory bytes to store the new payload.
  4. Data Transmission: Chromium passes the binary NDEF payload to the Android NfcAdapter. The phone's NFC controller modulates the RF field to transmit the bytes to the tag, overwriting the existing NDEF memory blocks on the tag's microchip.
  5. Confirmation: The tag sends a success signal back to the NFC controller. Android informs Chromium that the write operation is complete, and Chromium resolves the JavaScript Promise associated with the write() method, allowing the web page to notify the user that the tag has been updated.