Web NFC API

Abstract

Near Field Communication (NFC) enables wireless communication between two devices at close proximity, usually less than a few centimeters. NFC is an international standard (ISO/IEC 18092) defining an interface and protocol for simple wireless interconnection of closely coupled devices operating at 13.56 MHz. The hardware standard is defined in NFC Forum Technical Specifications.

This document defines an API to enable selected use-cases based on NFC technology. The current scope of the specification is NDEF. Other NFC technologies may be supported in the future.

4. The NFC Standard

This section is non-normative.

NFC is standardized in the NFC Forum and described in [NFC-STANDARDS].

4.1 NDEF compatible tag types

This section is non-normative.

The NFC Forum has mandated the support of five different tag types to be operable with NFC devices. The same is required on operating systems, such as Android.

In addition to that, the MIFARE Standard specifies a way for NDEF to work on top of the older MIFARE Standard, which may be optionally supported by implementors.

A note about the NDEF mapping can be found here: MIFARE Classic as NFC Type MIFARE Classic Tag

NFC Forum Type 1: This tag is based on the ISO/IEC 14443-3A (NFC-A). The tags are rewritable and can be configured to become read-only. Memory size can be between 96 bytes and 2 Kbytes. Communication speed is 106 kbit/sec. In contract to all other types, these tags have no anti-collision protection for dealing with multiple tags within the NFC field.
NFC Forum Type 2: This tag is based on the ISO/IEC 14443-3A (NFC-A). The tags are rewritable and can be configured to become read-only. Memory size can be between 48 bytes and 2 Kbytes. Communication speed is 106 kbit/sec.
NFC Forum Type 3: This tag is based on the Japanese Industrial Standard (JIS) X 6319-4 (ISO/IEC 18092), commonly known as FeliCa. The tags are preconfigured to be either rewritable or read-only. Memory is 2 kbytes. Communication speed is 212 kbit/sec or 424 kbit/s.
NFC Forum Type 4: This tag is based on the ISO/IEC 14443-4 A/B (NFC A, NFC B) and thus supports either NFC-A or NFC-B for communication. On top of that the tag may optionally support ISO-DEP (Data Exchange Protocol defined in ISO/IEC 14443 (ISO/IEC 14443-4:2008 Part 4: Transmission protocol). The tags are preconfigured to be either rewritable or read-only. Variable memory, up to 32 kbytes. Supports three different communication speeds 106 or 212 or 424 kbit/s.
NFC Forum Type 5: This tag is based on ISO/IEC 15693 (NFC-V) and allows reading and writing an NDEF message on a ISO/IEC 15693 RF tag that is accessible by long range RFID readers as well. The NFC communication is limited to short distance and may use the Active Communication Mode of ISO/IEC 18092 where the sending peer generates the field which balances power consumption and improves link stability. Variable memory, up to 64 kbytes. Communiction speed 26.48 kbit/s
MIFARE Standard: This tag, often sold under the brand names MIFARE Classic or MIFARE Mini, is based on the ISO/IEC 14443-3A (also known as NFC-A, as defined in ISO/IEC 14443-3:2011, Part 3: Initialization and anticollision). The tags are rewritable and can be configured to become read-only. Memory size can be between 320 and 4 kbytes. Communication speed is 106 kbit/sec.
Note
MIFARE Standard is a not an NFC Forum type and can only be read by devices using NXP hardware. Support for reading and writing to tags based on the MIFARE Standard is thus non-nominative, but the type is included due to the popularity and use in legacy systems.

In addition to data types standardized for NDEF records by the NFC Forum, many commercial products such as bus cards, door openers may be based on the MIFARE Standard which require specific NFC chips (same vendor of card and reader) in order to function.

Card emulation mode capabilities also depend on the NFC chip in the device. For payments, a Secure Element is often needed.

4.2 The NDEF record and fields

An NDEF record is a part of an NDEF message. Each record is a binary structure that contains a data payload, as well as associated type information. In addition to this, it includes information about how the data is structured, like payload size, whether the data is chunked over multiple records etc.

A generic record looks like the following:

Only the first three bytes (lines in figure) are mandatory. First the header byte, followed by the TYPE LENGTH field and PAYLOAD LENGTH field, which may both be zero.

The TNF field (bit 0-2, type name format) indicates the format of the type name and is often exposed by native NFC software stacks. The field can take binary values denoting the following NDEF record payload types:

TNF value	Description
0	Empty record
1	NFC Forum well-known type record
2	MIME type record
3	Absolute-URL record
4	NFC Forum external type record
5	Unknown record
6	Unchanged record
7	Reserved for future use

The IL field (bit 3, id length) indicates whether an ID LENGTH field is present. If the IL field is 0, then the ID field is not present either.

The SR field (bit 4, short record) indicates a short record, one with a payload length <= 255 bytes. Normal records can have payload lengths exceeding 255 bytes up to a maximum of 4 GB. Short records only use one byte to indicate length, whether as normal records use 4 bytes (2³²-1 bytes).

The CF field (bit 5, chunk flag) indicates whether the payload is chunked across multiple records.

Note

Web NFC turns all received chunked records into logical records and transparently chunks sent payload when that is needed.

The ME field (bit 6, message end) indicates whether this record is the last in the NDEF message.

The MB field (bit 7, message begin) indicates whether this record is the first of the NDEF message.

The TYPE LENGTH field is an unsigned 8-bit integer that denotes the byte size of the TYPE field.

The TYPE field is a globally unique and maintained identifier that describes the type of the PAYLOAD field in a structure, encoding and format dictated by value of the TNF field.

Note

The NFC Record Type Definition (RTD) Technical Specification requires that the TYPE field names MUST be compared in case-insensitive manner.

The ID LENGTH field is an unsigned 8-bit integer that denotes the byte size of the ID field.

The ID field is an identifier in the form of a URI reference ([RFC3986]) that is unique, and can be absolute of relative (in the latter case the application must provide a base URI). Middle and terminating chunk records MUST NOT have an ID field, other records MAY have it.

The PAYLOAD LENGTH field denotes the byte size of the PAYLOAD field. If the SR field is 1, its size is one byte, otherwise 4 bytes, representing an 8-bit or 32-bit unsigned integer, respectively.

The PAYLOAD field carries the application bytes. Any internal structure of the data is opaque to NDEF. Note that in certain cases discussed later, this field MAY contain an NDEF message as data.

4.3 NDEF Record types

4.3.1 Empty NDEF record (TNF 0)

An empty record's' TYPE LENGTH field, ID LENGTH field and PAYLOAD LENGTH field MUST be 0, thus the TYPE field, ID field and PAYLOAD field MUST NOT be present.

4.3.2 Well-known type records (TNF 1)

The NFC Forum has standardized a small set of useful record types in [NFC-RTD] (Resource Type Definition specifications) called well-known type records, for instance text, URL, media and opaque binary data. In addition, there are record types designed for more complex interactions, such as smart poster (containing optional embedded records for url, text, signature and actions), and handover records.

The type information stored in the TYPE field can be of two kinds:

NFC Forum global type that are defined and managed by the NFC Forum and usually start with uppercase letter. Examples: "T" for text, "U" for URL, "Sp" for smart poster, "Sig" for signature, "Hc" for handover carrier, "Hr" for handover request, "Hs" for handover select, etc.
NFC Forum local type that are defined by the NFC Forum or by an application, within the scope of the local context of another record or application and always start with lowercase letter or a number. See Smart poster for an example on how local types are used.

4.3.2.1 Text record

The Text record is a well-known type that is defined in the [NDEF-TEXT] specification. The TNF field is 1 and the TYPE field is "T" (0x54). The first byte of the PAYLOAD field is a status byte, followed by the ISO/IANA language code in US-ASCII encoding. The rest of the payload is the actual text, encoded either in UTF-8 or UTF-16, as indicated by the status byte as follows:

Bits 0 to 5 define the length of the IANA language code.
Bit 6 is 0.
If bit 7 if set, means the payload is encoded in UTF-8, otherwise in UTF-16.

4.3.2.2 URI record

URI record is defined in [NDEF-URI]. The TNF field is 1 and the TYPE field is "U" (0x55). The first byte of the PAYLOAD field is a URI identifier code, in fact an index in an abbreviation table where the values are prepended to the rest of the URI. For instance the value 0 denotes no prepending, 1 denotes "http://www.", 0x04 denotes "https://"" and so on. The rest of the payload contains the rest of the URI as a UTF-8 string (and if the first byte is 0, then it denotes the whole URI).

The URI is defined in [RFC3987] and in fact is a UTF-8 encoded IRI that can be a URN or a URL.

4.3.2.3 Smart poster record

Smart poster is defined in [NDEF-SMARTPOSTER] as an NDEF record that contains an NDEF message as payload, which may contain several records: a mandatory URI record that refers to a content, and additional optional records related to the content: a title record (a Text record), one or more icon records, a type record, a size record and an action record.

Icon records are MIME type records. If multiple icon records are included, readers SHOULD select only one of them to display.

The type record has NFC Forum local type "t" specific to smart poster and the PAYLOAD field contains a UTF-8 encoded MIME type for the content referred to by the URI record.

The size record has NFC Forum local type "s" specific to smart poster and the PAYLOAD field contains a 4-byte 32 bit unsigned integer that denotes the size of the object referred to by the URL in the URI record.

The action record has NFC Forum local type "act" specific to smart poster and the PAYLOAD field contains a single byte, whose value has the following meaning:

Value	Description
0	Do the action
1	Save for later
2	Open for editing
3..0xFF	Reserved for future use

The action record is optional and there is no default action on the smart poster content if the action record is missing.

Note

At the time of NDEF standardization the value 0 ("do the action") was meant for use cases like send an SMS, make a call or launch browser. Similarly, the value 1, ("save the content for later processing") was meant for use cases like store the SMS in inbox, save the URL in bookmarks, or save the phone number to contacts. Also, the value 2 ("open for editing") was meant to open the smart poster content with a default application for editing.

Implementations don't need to implement any standardized behavior for the actions defined here. In this API it's up to the applications what actions they define (that may include the use cases above). However, Web NFC just provides the values.

The example below shows a smart poster record that embeds a text and a URL record.

4.3.2.4 Signature records

NDEF Signature is defined [NDEF-SIGNATURE]. Its TYPE field contains "Sig" (0x53, 0x69, 0x67) and its PAYLOAD field contains version, signature and a certificate chain. In this version of the API, Web NFC only provides the raw byte content of the payload (see this issue).

4.3.2.5 Handover records

NFC handover is defined [NFC-HANDOVER] and the corresponding message structure that allows negotiation and activation of an alternative communication carrier, such as Bluetooth or WiFi. The negotiated communication carrier would then be used (separately) to perform certain activities between the two devices, such as sending photos to the other device, printing to a Bluetooth printer or streaming video to a television set. Web NFC does not support this at the moment (see this issue.

4.3.3 MIME type records (TNF 2)

The MIME type records are records that store binary data with associated MIME type.

Note

Web NFC has special handling for working with JSON MIME type data.

4.3.4 Absolute-URL records (TNF 3)

In absolute-URL records the TYPE field contains the absolute-URL string, and not the payload.

Note

NOTE: Some platforms, like Windows Phone have stored additional data in the payload, but any payload data in these records are ignored by other platforms such as Android. On Android, reading such a record, will attempt to load the URL in Chrome and it is as such not intended for client applications.

4.3.5 External type records (TNF 4)

The NFC Forum external type records are for application specified data types and are defined in NFC Record Type Definition (RTD) Technical Specification.

The external type is a URN with the prefix "urn:nfc:ext:" followed by the name of the owner domain, adding a colon, then a non-zero type name, for instance "urn:nfc:ext:w3.org:atype", stored as "w3.org:atype" in the TYPE field.

4.3.6 Unknown type records (TNF 5)

The unknown records are records that store opaque data without associated MIME type, meaning that the application/octet-stream default MIME type MAY be assumed. The [NFC-NDEF] specification recommends that NDEF parsers store or forward the payload without processing it.

4.3.7 Unchanged type records (TNF 6)

The unchanged records are record chunks of a chunked data set, and is used for any, but the first record. A chunked payload is spread across multiple NDEF records that undergo the following rules:

The initial chunk record has the CF field set, its TYPE field set to the type of the whole chunked payload and its ID field MAY be set to an identifier used for the whole chunked payload. Its PAYLOAD LENGTH field denotes the size of the payload chunk in this record only.
The middle chunk records have the CF field set, have the same ID field as the first chunk, their TYPE LENGTH field and IL field MUST be 0 and their TNF field MUST be 6 (unchanged).
The terminating chunk record has this flag cleared, and in rest undergo the same rules as the middle chunk records.
A chunked payload MUST be contained in a single NDEF message, therefore the initial and middle chunk records cannot have the ME field set.

First record:
Intermediate record:
Last record:

Any implementation of Web NFC MUST transparently expose chunked records as single logical records.

9. Data Representation

9.1 The `NDEFMessage` interface

The content of any NDEF message is exposed by the NDEFMessage interface:

[Exposed=Window]
interface NDEFMessage {
  constructor(NDEFMessageInit messageInit);
  readonly attribute FrozenArray<NDEFRecord> records;
};

dictionary NDEFMessageInit {
  required sequence<NDEFRecordInit> records;
};

The records property represents a list of NDEF records defining the NDEF message.

The NDEFMessageInit dictionary is used to initialize a NDEF message.

9.2 The `NDEFRecord` interface

The content of any NDEF record is exposed by the NDEFRecord interface:

[Exposed=Window]
interface NDEFRecord {
  constructor(NDEFRecordInit recordInit);

  readonly attribute NDEFRecordType recordType;
  readonly attribute USVString mediaType;
  readonly attribute USVString id;

  USVString? text();
  [NewObject] ArrayBuffer? arrayBuffer();
  [NewObject] any json();
  sequence<NDEFRecord> toRecords();
};

dictionary NDEFRecordInit {
  required NDEFRecordType recordType;
  USVString mediaType;
  USVString id;

  any data;
};

A NDEFRecord object has the following internal slots:

Internal slot	Initial value	Description (non-normative)
[[PayloadData]]	Empty byte sequence.	A byte sequence representing the whole or a subset of the PAYLOAD field data.

The mediaType property represents the MIME type of the NDEF record payload.

The recordType property represents the NDEF record types.

The id property represents the record identifier, which is an absolute or relative URL. The required uniqueness of the identifier is guaranteed by the generator, as such only absolute URLs based on the origin of the browsing content can be written using this specification.

The record identifier host is a serialized host.
The record identifier is a record identifier host, optionally followed by a path-absolute-URL string.

Note

The NFC NDEF specifications uses the terms "message identifier" and "payload identifier" instead of record identifier, but the identifier is tied to each record and not the message (collection of records), and it may be present when no payload is.

The text() method, when invoked, MUST return the result of running convert NDEFRecord.[[PayloadData]] bytes with an NDEFRecord object and text target.

The arrayBuffer() method, when invoked, MUST return the result of running convert NDEFRecord.[[PayloadData]] bytes with an NDEFRecord object and arrayBuffer target.

The json() method, when invoked, MUST return the result of running convert NDEFRecord.[[PayloadData]] bytes with an NDEFRecord object and a JSON target.

The toRecords() method, when invoked, MUST return the result of running convert NDEFRecord.[[PayloadData]] bytes with an NDEFRecord object and records target.

The NDEFRecordInit dictionary is used to initialize an NDEF record with its type, optional MIME type, record identifier and payload data via the members of recordType, mediaType, id, and data, respectively. The mapping from data types of an NDEFRecordInit to NDEF record types is presented in the algorithmic steps which handle the data and described in the § 10.13 Parsing content and § 10.10 Writing or pushing content sections.

To convert NDEFRecord.[[PayloadData]] bytes, pass a record and a target, run these steps:

Let bytes be record.[[PayloadData]].
Let recordType be the value of record's recordType attribute.
Switch on target:
text
1. If the recordType value is equal to "empty", return null.
2. If the recordType value is equal to "text", then run the following sub-steps:
  1. Let header be the first byte of bytes.
  2. Let charset be "utf-8" if bit 7 (MB field) of header is equal to the value 0, or else "utf-16be".
  3. Let offset be the value given by bit 5 to bit 0 of the header.
  4. Let buffer be the bytes, from position offset + 1 to the end.
  5. If charset is equal to "utf-8", return the result of running UTF-8 decode on buffer.
  6. Otherwise, return the result of running decode on buffer with encoding set to "utf-16be".
3. Otherwise, return the result of running UTF-8 decode on bytes.
arrayBuffer
1. Return an ArrayBuffer whose contents are the bytes. Re-throw any exceptions.
JSON
1. If the recordType value is equal to "json" or "media", then return the result of running parse JSON from bytes on bytes. Re-throw any exceptions.
2. Otherwise, return null.
records
1. If the recordType value is "smart-poster", or "media", or an external type, then return the result of running parse records from bytes on bytes. Re-throw any exceptions.
2. Otherwise, return null.

9.3 The `NDEFRecordType` string

This string defines the allowed types for a NDEFRecord. The § 9.4 Data mapping section describes how NDEFRecordType is mapped to NDEF record types.

typedef DOMString NDEFRecordType;

A set of known standardized values exists, but it is also possible for organizations to create their own custom external types.

The "empty" string

The value representing empty NDEFRecord.

The "text" string

The value representing a Text record.

The "url" string

The value representing a URI record.

The "smart-poster" string

The value representing a Smart poster record.

The "absolute-url" string

The value representing a absolute-URL record.

The "media" string

The value representing a MIME type record.

The "json" string

The value representing a MIME type record that has a JSON MIME type.

The "unknown" string

The value representing an unknown record.

An external type

A DOMString representing a custom type for the external type record. The type must follow the external type ABNF.

ext-type             = reg-name ":" custom-type
custom-type          = 1*(ALPHA / DIGIT / other)

DIGIT                = %x30-39
ALPHA                = %x41-5A / %x61-7A   ; A-Z / a-z
other                = "(" / ")" / "+" / "," / "-" / ":" / "=" /
                       "@" / ";" / "$" / "_" / "!" / "*" / "'" / "."

The reg-name value is a registrable domain owned by the issuing organization, a ":" and a type, e.g. "w3.org:member". And additional ABNF exists for well-known type records:

wkt-type             = (ALPHA / DIGIT) *(ALPHA / DIGIT / other)

Note

The NFC Record Type Definition (RTD) Technical Specification defines every type in the well-known type records and external type records in terms of URNs, but only a subset of the URN is actually stored in the NDEF record's TYPE field, which corresponds to the above two ABNFs.

A local type

A DOMString that MUST start with lowercase letter or a number, representing a type for a NFC Forum local type, typically used in a record of an NDEFMessage that is the payload of a parent NDEFRecord, for instance in a smart poster. The context of the local type is the parent record whose payload is the NDEFMessage to which this record belongs. The value MUST NOT be equal to any other NDEFRecordType strings defined in this API.

Any implementation of Web NFC MUST transparently expose chunked records as single logical records, therefore unchanged records are not explicitly represented.

Two well-known types (including any NFC Forum local type and any NFC Forum global type) MUST be compared character by character in case-sensitive manner.

Two external types MUST be compared character by character, in case-insensitive manner.

The binary representation of any well-known type and external type MUST be written as a relative URI (RFC 3986), omitting the namespace identifier (NID) "nfc" and namespace specific string (NSS) "wkt" and "ext", respecively, i.e. omitting the "urn:nfc:wkt:" and "urn:nfc:ext:" prefixes. For instance, "urn:nfc:ext:company.com:a" is stored as "company.com:a`" and the well-known type of a Text record is "urn:nfc:wkt:T", but it is stored as "T".

9.4 Data mapping

The mapping from data types of an NDEFRecordInit to NDEF record types, as used in the § 10.10 Writing or pushing content section is as follows:

NDEFRecordInit recordType	NDEFRecordInit mediaType	NDEFRecordInit data	NDEF record type
"`empty`"	unused	unused	Empty record (TNF=0)
"`text`"	unused	`DOMString`	Well-known type (TNF=1) record with TYPE="`T`"
"`url`"	unused	`DOMString`	Well-known type (TNF=1) record with TYPE="`U`"
"`smart-poster`"	unused	`NDEFMessage`	Well-known type (TNF=1) record with TYPE="`Sp`"
"`json`"	JSON MIME type	JSON type	MIME type record (TNF=2) with TYPE= JSON type.
"`media`"	MIME type	`ArrayBuffer`	MIME type record (TNF=2) with TYPE= MIME type
"`absolute-url`"	unused	`DOMString` url	Absolute-URL record (TNF=3) with TYPE=url
external type	unused	`ArrayBuffer` or any typed array type or `NDEFMessage`	External type record (TNF=4) with TYPE= external type
local type	unused	`ArrayBuffer` or any typed array type	External type record (TNF=4) with TYPE= local type inside the `NDEFMessage` payload of another record
"`unknown`"	unused	`ArrayBuffer`	unknown record (TNF=5)

The mapping from NDEF record types to NDEFRecord, as used for incoming NDEF messages described in the § 10.13 Parsing content section, is as follows. The data getters column shows the ones that should work for the given payload type (the others may or will fail, depending on case).

NDEF record TNF field and TYPE field	NDEFRecord recordType	NDEFRecord mediaType	NDEFRecord data getters
Empty record (TNF=0)	"`empty`"	""	none (all getters fail)
Well-known type (TNF=1) record with TYPE="`T`"	"`text`"	"`text/plain`"	`text()` or `json()` or `arrayBuffer()`
Well-known type (TNF=1) record with TYPE="`U`"	"`url`"	"`text/plain`"	`text()` or `json()` or `arrayBuffer()`
Well-known type (TNF=1) record with TYPE="`Sp`"	"`smart-poster`"	""	`toRecords()` or `arrayBuffer()`
MIME type record (TNF=2) with TYPE=JSON MIME type	"`json`"	The JSON MIME type used in the NDEF record	`text()` or `json()` or `arrayBuffer()`
MIME type record (TNF=2) with TYPE=MIME type	"`media`"	The MIME type used in the NDEF record	`text()` or `json()` or `arrayBuffer()`
Absolute-URL record (TNF=3) with TYPE=url	"`url`"	""	`text()` returning url or `arrayBuffer()`
External type record (TNF=4) with TYPE=external type	external type	"`application/octet-stream`"	`text()` or `json()` or `arrayBuffer()` or `toRecords()`
Any embedded NDEF record with TYPE=local type	local type	"`application/octet-stream`"	`text()` or `json()` or `arrayBuffer()`
Unknown record (TNF=5)	"`unknown`"	"`application/octet-stream`"	`arrayBuffer()`

10. The NFCReader and NFCWriter objects

The objects provide a way for the browsing context to use NFC functionality. They allow for pushing NDEF messages to NFC tags or NFC peers within range, and to act on incoming NDEF messages either from an NFC tag or an NFC peer.

typedef (DOMString or ArrayBuffer or NDEFMessageInit) NDEFMessageSource;

[SecureContext, Exposed=Window]
interface NFCWriter {
  constructor();

  Promise<void> push(NDEFMessageSource message, optional NFCPushOptions options={});
};

[SecureContext, Exposed=Window]
interface NFCReader : EventTarget {
  constructor();

  attribute EventHandler onreading;
  attribute EventHandler onerror;

  void scan(optional NFCScanOptions options={});
};

[SecureContext, Exposed=Window]
interface NFCReadingEvent : Event {
  constructor(DOMString type, NFCReadingEventInit readingEventInitDict);

  readonly attribute DOMString serialNumber;
  [SameObject] readonly attribute NDEFMessage message;
};

dictionary NFCReadingEventInit : EventInit {
  DOMString? serialNumber = "";
  required NDEFMessageInit message;
};

[SecureContext, Exposed=Window]
interface NFCErrorEvent : Event {
  constructor(DOMString type, NFCErrorEventInit errorEventInitDict);

  readonly attribute DOMException error;
};

dictionary NFCErrorEventInit : EventInit {
  required DOMException error;
};

The NDEFMessageSource is a union type representing argument types accepted by the push() method.

The NFCReadingEvent is the event being dispatched on new NFC readings. The serialNumber property represents the serial number of the device used for anti-collision and identification, or empty string in case none is available. The message is an NDEFMessage object.

NFCReadingEventInit is used to initialize a new event with a serial number and the NDEFMessageInit data via the message member. If serialNumber is not present or is null, empty string will be used to init the event.

Note

Though most tags will have a stable unique identifier (UID), not all have one and some tags even create a random number on each read. The serial number usually consists of 4 or 7 numbers, separated by :.

The NFCErrorEvent is the event being dispatched on errors, with the DOMException object as the error attribute.

NFCErrorEventInit is used in order to initialize a new event with a DOMException data via the error member.

The NFCWriter is an object used for writing data to NFC devices such as tags.

An NFCWriter object has the following internal slots:

Internal Slot	Initial value	Description (non-normative)
[[PushOptions]]	`null`	The `NFCPushOptions` value for writer.
[[PushMessage]]	`null`	The `NDEFMessage` to be written. It is initially unset.
[[PushTimer]]	`null`	A timer associated with the writer.

The NFCReader is an object used for reading data when a device, such as a tag, is within the magnetic induction field.

An NFCReader object has the following internal slots:

Internal Slot	Initial value	Description (non-normative)
[[Id]]	An empty string.	The `NFCScanOptions`.`id` value.
[[RecordType]]	`undefined`	The `NFCScanOptions`.`recordType` value.
[[MediaType]]	An empty string.	The `NFCScanOptions`.`mediaType` value.
[[Signal]]	`undefined`	The `NFCScanOptions`.`signal` to abort the operation.

Note

Note that the internal slots of NFCReader come from the options passed to NFCReader.scan(). Therefore there is maximum one filter associated with any given NFCReader object and successive invocations of NFCReader.scan() with new options will replace existing filters.

The onreading is an EventHandler which is called to notify that new reading is available.

The onerror is an EventHandler which is called to notify that an error happened.

10.1 NFC state associated with the settings object

The relevant settings object of the active document of a browsing context which supports NFC has an associated NFC state record with the following internal slots:

Internal Slot	Initial value	Description (non-normative)
[[Suspended]]	`false`	A boolean flag indicating whether NFC functionality is suspended or not, initially `false`.
[[ActivatedReaderList]]	empty set	A set of `NFCReader` instances.
[[PendingPush]]	empty	A <`promise`, `writer`> tuple where `promise` holds a pending `Promise` and `writer` holds an `NFCWriter`.

The activated reader objects is the value of the [[ActivatedReaderList]] internal slot.

The pending push tuple is the value of the [[PendingPush]] internal slot.

NFC is suspended if the [[Suspended]] internal slot is true.

To suspend NFC, set the [[Suspended]] internal slot to true.

To resume NFC, set the [[Suspended]] internal slot to false.

Note

Internal slots are used only as a notation in this specification, and implementations do not necessarily have to map them to explicit internal properties.

10.2 Handling NFC adapters

Implementations MAY use multiple NFC adapters according to the algorithmic steps described in this specification.

10.3 Handling visibility change

When the user agent determines that the visibility state of the responsible document of the current settings object changes, it must run these steps:

Let document be the responsible document of the current settings object.
If document's visibility state is "visible", resume NFC and abort these steps.
Otherwise, suspend NFC and attempt to abort a pending push operation.

The term suspended refers to NFC operations being suspended, which means that no NFC content is pushed by NFCWriters, and no received NFC content is presented to any NFCReader while being suspended.

10.4 Clearing the pending push tuple

To clear the pending push tuple on an environment settings object, perform the following steps:

If there is no pending push tuple tuple, abort these steps.
Let writer be the pending push tuple's writer.
Stop writer.[[PushTimer]] if active.
Clear tuple.

10.5 Aborting pending push operation

To attempt to abort a pending push operation on an environment settings object, perform the following steps:

If there is no pending push tuple tuple, abort these steps.
If tuple's writer has already initiated an ongoing NFC data transfer, abort these steps.
Reject tuple's promise with an "AbortError" DOMException and abort these steps.
Note
Rejecting the promise will clear the pending push tuple.

10.6 Releasing NFC

To release NFC on an environment settings object, perform the following steps:

Suspend NFC.
Attempt to abort a pending push operation.
Stop the dispatch NFC content steps.
Clear the activated reader objects.
Release the NFC resources associated with nfc on the underlying platform.

The UA must release NFC given the document's relevant settings object as additional unloading document cleanup steps.

10.7 The `NFCPushOptions` dictionary

dictionary NFCPushOptions {
  NFCPushTarget target = "any";
  unrestricted double timeout = Infinity;
  boolean ignoreRead = true;
  boolean overwrite = true;
  AbortSignal? signal;
};

The target property denotes the intended target for the pending push() operation.

The timeout property denotes the timeout for the pending push() operation expressed in milliseconds. The default value is implementation-dependent. The value Infinity means there is no timeout, i.e. no timer is started. After the timeout expires, the message set for pushing is cleared, an error is returned, and a new NDEF message can be set for pushing.

When the value of the ignoreRead property is true, the push algorithm will skip invoking the NFC reading algorithm for an NFC tag.

When the value of the overwrite property is false, the push algorithm will read the NFC tag regardless of the ignoreRead value to determine if it has NDEF records on it, and if yes, it will not execute any pending push.

The signal property allows to abort the push() operation.

10.8 The `NFCPushTarget` enum

This enum defines the set of intended target values for the push() operation.

enum NFCPushTarget {
  "tag",
  "peer",
  "any"
};

tag: The enum value representing the intended target for the push() operation to be a NFC tag.
peer: The enum value representing the intended target for the push() operation to be a NFC peer.
any: The enum value representing the intended target for the push() operation to be a NFC tag or a NFC peer.

10.9 The `NFCScanOptions` dictionary

To describe which messages an application is interested in, the NFCScanOptions dictionary is used:

dictionary NFCScanOptions {
  USVString id = "";
  NDEFRecordType recordType;
  USVString mediaType = "";
  AbortSignal? signal;
};

The signal property allows to abort the scan() operation.

The id property denotes the URL pattern which is used for matching the record identifier of individual NDEF Records which are being read. The default value "" means that no matching is performed.

The recordType property denotes the enum value which is used for matching the recordType property of each NDEFRecord object in an NDEF message. If the dictionary member is not present, then it will be ignored by the NFC listen algorithm.

The mediaType property denotes the match pattern which is used for matching the mediaType property of each NDEFRecord object in an NDEF message. The default value "" means that no matching is performed.

Example 12: Filter accepting only JSON content from https://www.w3.org

const options = {
  id: "https://www.w3.org/*",  // any path from the domain is accepted
  recordType: "json",
  mediaType: "application/*+json"  // any JSON-based MIME type
}

Example 13: Filter which only accepts binary content from a given path for w3 domain and its subdomains

const options = {
  id: "https://w3.org/info/restaurant/daily-menu/",
  recordType: "media",
  mediaType: "application/octet-stream"
}

10.10 Writing or pushing content

This section describes how to write an NDEF message to an NFC tag or how to push it to an NFC peer device when it is next time in proximity range before a timer expires. At any time there is at maximum of two NDEF messages that can be set for pushing for an origin: one targeted to NFC tags and one to NFC peers, until the current message is sent, a timeout happens, or the push is aborted.

10.10.1 The push() method

The NFCWriter.push method, when invoked, MUST run the push a message algorithm:

Let p be a new Promise object.
Let message be the first argument.
Let options be the second argument.
If there is no underlying NFC Adapter, or if a connection cannot be established, then reject p with a "NotSupportedError" DOMException and return p.
If the UA is not allowed to access the underlying NFC Adapter (e.g. a user preference), then reject p with a "NotReadableError" DOMException and return p.
If pushing data is not supported by the underlying NFC Adapter, then reject p with a "NotSupportedError" DOMException and return p.
Let signal be the options’ dictionary member of the same name if present, or null otherwise.
If signal’s aborted flag is set, then reject p with an "AbortError" DOMException and return p.
If signal is not null, then add the following abort steps to signal:
1. Run the abort a pending push operation on the environment settings object.
React to p:
1. if p was settled (fulfilled or rejected), then run the clear the pending push tuple steps.
Return p and run the following steps in parallel:
1. An implementation MAY reject p with a "NotSupportedError" DOMException and abort these steps.
  Note
  The UA might abort message push at this point. The reasons for termination are implementation details. For example, the user could have has set a preference to allow a given origin only to read, write, or push data to peers. Also, the implementation might be unable to support the requested operation.
2. Let output be the notation for the NDEF message to be created by UA, as the result of passing message to create NDEF message. If this throws an exception, reject p with that exception and abort these steps.
3. Attempt to abort a pending push operation.
  Note
  A push replaces all previously configured push operations.
4. Set this.[[PushOptions]] to options.
5. Set this.[[PushMessage]] to output.
6. Set pending push tuple to (this, p).
7. Run the start the push timer steps.
8. Run the start the NFC push steps whenever an NFC device device comes within communication range.

To start the push timer, run these steps:

Let p be the pending push tuple's promise.

Let writer be the pending push tuple's writer.
Let timeout be writer.[[PushOptions]]'s timeout.
- If timeout value is NaN or negative, reject p with a TypeError and abort these steps.
- If timeout value is not supported by the UA, reject p with a "NotSupportedError" DOMException and abort these steps.
- If timeout value is equal to Infinity, abort these steps.
Start a timer timer with the timeout value set to timeout and set writer.[[PushTimer]] to timer.
When timer expires, reject p with "TimeoutError" DOMException.

To start the NFC push, run these steps:

Let p be the pending push tuple's promise.
Let writer be the pending push tuple's writer.
Let options be writer.[[PushOptions]].
Let target be options' target.
If the NFC device in proximity range does not expose NDEF technology for formatting or writing, then reject p with a "NotSupportedError" DOMException and return p.
Verify the following conditions:
- if device is an NFC tag, target is "tag" or "any".
- if device is an NFC peer, target is "peer" or "any".
- NFC is not suspended.
In case of success, run the following steps:
1. Stop writer.[[PushTimer]] if active.
2. If device is an NFC tag,
  - If options's ignoreRead is not equal to true, run the NFC reading algorithm.
  - Otherwise, if options's overwrite is false, read the tag to check whether there are NDEF records on the tag. If yes, then reject p with a "NotAllowedError" DOMException and return p.
  - Let idHost be the record identifier host of the tag.
  - If idHost is null, or different than the serialized host of the current settings object's origin, and the obtain push permission steps return false, then reject p with "NotAllowedError" DOMException and abort these steps.
3. Let output be writer.[[PushMessage]].
4. Initiate data transfer to device using output as buffer, using the NFC adapter in communication range with device.
  Note
  If the NFC device in proximity range is an unformatted NFC tag that is NDEF-formatable, format it and write output as buffer.
  
  Note
  Multiple adapters should be used sequentially by users. There is very small likelihood that a simultaneous tap will happen on two or multiple different and connected NFC adapters. If it happens, the user will likely need to repeat the taps until success, preferably one device at a time. The error here gives an indication that the operation needs to be repeated. Otherwise the user may think the operation succeeded on all connected NFC adapters.
5. If the transfer fails, reject p with "NetworkError" DOMException and abort these steps.
6. When the transfer has completed, resolve p.

10.10.2 Obtaining push permission

To obtain push permission, run these steps:

If there is a prearranged trust relationship, return true.
Run the query a permission steps for the Web NFC permission name until completion.
1. If it resolved with "granted" (i.e. an expressed permission has been granted to the origin and global object using the Permissions API), return true.
2. Otherwise, if it resolved with "prompt", then optionally request permission from the user for the Web NFC permission name. If that is granted, return true.
  Issue 1
  The request permission steps are not yet clearly defined. At this point the UA asks the user about the policy to be used with the Web NFC permission name for the given origin and global object, if the user grants permission, return true.
Return false.

10.11 Creating content

10.11.1 Creating NDEF message

To create NDEF message given a message run these steps:

If the message parameter is not of type defined by the NDEFMessageSource union, throw a TypeError and abort these steps.
If the message parameter is of NDEFMessageInit type, and message's records is empty, throw a TypeError and abort these steps.
Let output be the notation for the NDEF message to be created by the UA as a result of these steps.
For each record in the list message's records, run the following steps, or make sure that the underlying platform provides equivalent values to ndef:
1. If record's recordType is undefined:
  1. If record's data is undefined, reject promise a TypeError and abort these steps.
  2. Otherwise, if the type of record's data is DOMString, then set record's recordType to "text".
  3. Otherwise, if the type of record's data is an ArrayBuffer, then set record's recordType to "media".
  4. Otherwise, set record's recordType to "json".
2. Let ndef be the result of passing record to the algorithm below switching on record's recordType. If the algorithm throws an exception e, reject promise with e and abort these steps.
  "empty"
  - map empty record to NDEF.
  "text"
  - map text to NDEF.
  "url"
  - map a URL to NDEF.
  "json"
  - map JSON to NDEF.
  "media"
  - map binary data to NDEF.
  external type
  - If record's data is of type NDEFMessageInit, then return the result of running the create NDEF message given record's data.
  - Otherwise, map external data to NDEF given record.
  local type
  - If record's data is of type NDEFMessageInit, then return the result of running the create NDEF message given record's data.
  - Otherwise, map local type to NDEF given record.
  unmatched type
  - throw a TypeError
3. If message is of type NDEFMessageInit and its id is not null:
  - Set identifier to the result of invoking create a record identifier given id. If this throws an exception, re-throw it.
  - Set ndef's IL field to 1.
  - Set ndef's ID LENGTH field to the length of identifier.
  - Set ndef's ID field to identifier.
4. Add ndef to output.

10.11.2 Mapping empty record to NDEF

To map empty record to NDEF given a record, run these steps:

Let ndef be the notation for the NDEF record to be created by the UA.
Set the ndef's TNF field to 0 (empty record).
Set the ndef's IL field to 0.
Set ndef's TYPE LENGTH field, and PAYLOAD LENGTH field to 0, and omit TYPE field and PAYLOAD field.
Return ndef.

10.11.3 Mapping string to NDEF

To map text to NDEF given a record, run these steps:

Note

This is useful when clients specifically want to write text in a well-known type record. Other options would be to use the value "media" with an explicit MIME type text type, which allows for better differentiation, e.g. when using "text/xml", or "text/vcard".

If the type of a record's data is not a DOMString, throw a TypeError and abort these steps.
Let mimeTypeRecord be the MIME type returned by running parse a MIME type on record's mediaType.
1. If mimeTypeRecord is failure, let mimeTypeRecord be a new MIME type record whose type is "text", and subtype is "plain".
2. If mimeTypeRecord's type is not "text", then throw a "SyntaxError" DOMException and abort these steps.
Let language be mimeTypeRecord's parameters["lang"] if it exists, or "en".
Let charset be mimeTypeRecord's parameters["charset"] if it exists, or "utf-8".
If charset is not equal to "utf-8", throw a TypeError.
Let header be a byte constructed the following way:
1. Set bit 7 to the value 0 (meaning UTF-8 encoding).
2. Set bit 6 to the value 0 (reserved).
3. Let languageLength be the length of the language string.
4. If languageLength cannot be stored in 6 bit (languageLength > 63), throw a SyntaxError.
5. Set bit 5 to bit 0 to languageLength.
Let data be an empty byte sequence.
1. Set the first byte (position 0) of data to header.
2. Set position 1 (second byte) to position languageLength of data to language.
3. Let stream be the resulting byte stream of running UTF-8 encode on record's data.
4. Read bytes from stream into data (from position languageLength + 1) until read returns end-of-stream.
Set length to the length of data.
Let ndefRecord be the notation for the NDEF record to be created by the UA.
1. Set the ndefRecord's TNF field to 1 ( well-known type record).
2. Set the ndefRecord's TYPE field to "T" (0x54).
3. Set the ndefRecord's PAYLOAD LENGTH field to length.
4. If length > 0, set the ndefRecord's PAYLOAD field to data.
Return ndefRecord.

Note

The lang= parameter is a non-standard parameter to MIME types, but it is used in this specification in order to maintain compatibility with NFC Forum Technical Specifications.

10.11.4 Mapping URL to NDEF

To map a URL to NDEF given a record, run these steps:

If record's data is not a DOMString, throw a TypeError and abort these steps.
Let url be the result of parsing record's data.
If url is failure, throw a TypeError and abort these steps.
Let serializedURL be serialization of url.
Match the URI prefixes as defined in NFC Forum Technical Specifications, URI Record Type Definition specification, Section 3.2.2, against the serializedURL.
Let prefixString be the matched prefix or else the empty string.
Let prefixByte be the corresponding prefix number, or else 0.
Let shortenedURL be serializedURL with prefixString removed from the start of the string.
Let data be an empty byte sequence.
1. Set the first byte of data to prefixByte.
2. Let stream be the resulting byte stream of running UTF-8 encode on shortenedURL.
3. Read bytes from stream into data (from position 1) until read returns end-of-stream.
Set length to the length of data.
Let ndefRecord be the notation for the NDEF record to be created by the UA.
1. Set the ndefRecord's TNF field to 1 (well-known type record).
2. Set the ndefRecord's TYPE field to "U" (0x55).
3. Set the ndefRecord's PAYLOAD LENGTH field to length.
4. If length > 0, set the ndefRecord's PAYLOAD field to data.
Return ndefRecord.

10.11.5 Mapping JSON to NDEF

To map JSON to NDEF given a record, run these steps:

Let mimeTypeRecord be the MIME type returned by running parse a MIME type on record's mediaType.
1. If mimeTypeRecord is failure, let mimeTypeRecord be a new MIME type record whose type is "application", and subtype is "json".
2. If mimeTypeRecord is not a JSON MIME type, then throw a "SyntaxError" DOMException and abort these steps.
Let data be an empty byte sequence.
1. Let stream be the resulting byte stream of executing serialize JSON to bytes on record's data.
2. Read bytes from stream into data until read returns end-of-stream.
Set length to the length of data.
Let ndefRecord be the notation for the NDEF record to be created by the UA.
1. Set the ndefRecord's TNF field to 2 (MIME type).
2. Set the ndefRecord's TYPE field to the result of serialize a MIME type with mimeTypeRecord as the input.
3. Set the ndefRecord's PAYLOAD LENGTH field to length.
4. If length > 0, set the ndefRecord's PAYLOAD field to data.
Return ndefRecord.

Note

JavaScript Object Notation aka JSON can be any of the following ECMAScript Language Specification types: object, array, String, Boolean, Number or null, which covers a lot of the Web IDL types as listed here: JSON type.

Serializing JSON to bytes can result in 0 bytes in some cases, like serializing the following object, which specifies it own toJSON operation:

class ZeroByteJSON {
  toJSON() {
    return undefined;
  }
}

This means that the map JSON to NDEF algorithm might result in a NDEF record with no PAYLOAD field.

10.11.6 Mapping binary data to NDEF

To map binary data to NDEF given a record, run these steps:

If the type of a record's data is not an ArrayBuffer, throw a TypeError and abort these steps.
Let mimeTypeRecord be the MIME type returned by running parse a MIME type on record's mediaType.
1. If mimeTypeRecord is failure, let mimeTypeRecord be a new MIME type record whose type is "application", and subtype is "octet-stream".
Set arrayBuffer to record's data.
Set length to arrayBuffer.[[ArrayBufferByteLength]].
Set data to arrayBuffer.[[ArrayBufferData]].
Let ndefRecord be the notation for the NDEF record to be created by the UA.
1. Set the ndefRecord's TNF field to 2 (MIME type).
2. Set the ndefRecord's TYPE field to the result of serialize a MIME type with mimeTypeRecord as the input.
3. Set the ndefRecord's PAYLOAD LENGTH field to length.
4. If length > 0, set the ndefRecord's PAYLOAD field to data.
Return ndefRecord.

10.11.7 Mapping external data to NDEF

To map external data to NDEF given a record, run these steps:

If the type of a record's data is not an ArrayBuffer, throw a TypeError and abort these steps.
Set arrayBuffer to record's data.
Set length to arrayBuffer.[[ArrayBufferByteLength]].
Set data to arrayBuffer.[[ArrayBufferData]].
Let ndefRecord be the notation for the NDEF record to be created by the UA.
1. Set ndefRecord's TNF field to 4 (external type record).
2. Set the ndefRecord's TYPE field to record's recordType.
3. Set the ndefRecord's PAYLOAD LENGTH field to length.
4. If length > 0, set the ndefRecord's PAYLOAD field to data.
Return ndefRecord.

10.11.8 Mapping local type to NDEF

To map local type to NDEF given a record, run these steps:

If the type of a record's data is not an ArrayBuffer, throw a TypeError and abort these steps.
Set arrayBuffer to record's data.
Set length to arrayBuffer.[[ArrayBufferByteLength]].
Set data to arrayBuffer.[[ArrayBufferData]].
Let ndefRecord be the notation for the NDEF record to be created by the UA.
1. Set the ndefRecord's TYPE field to record's recordType.
2. If record's recordType is a standard local type to smart poster or a handover record, then set ndefRecord's TNF field to 1 (well-known type record), otherwise set ndefRecord's TNF field to 4 (external type record).
3. Set the ndefRecord's PAYLOAD LENGTH field to length.
4. If length > 0, set the ndefRecord's PAYLOAD field to data.
Return ndefRecord.

10.11.9 Creating a record identifier

To create a record identifier given URL string id, run these steps:

Let origin be the current settings object's origin.
Let host be origin's host, serialized.
Let urlRecord be the result of parsing id with "https://" + host as the base URL.
If any of the following cases matches, throw a TypeError and abort these steps:
- If urlRecord is failure.
- If urlRecord's protocol is not equal to "https:".
- If urlRecord's host doesn't end with host's registrable domain.
Let identifier be urlRecord, serialized.
Return identifier.

10.12 Listening for content

If there are any NFCReader instances in activated reader objects then the UA MUST listen to NDEF messages.

To listen for NFC content, the client MUST activate an NFCReader instance by calling NFCReader.scan(). When attaching an event listener for the "reading" event on it, NFC content is accessible to the client.

Each NFCReader can accept NDEF messages based on data type, and a record identifier (URL) filters.

Filtering by a record identifier URL pattern, means that it will be matched against the URLs found in the NDEF records' ID field, thus the presence of such is required.

10.12.1 Match patterns

A match pattern is defined by the following ABNF:

match-pattern  = top-level-type "/" [ tree "." ] subtype [ "+" suffix ] [ ";" parameters ]
top-level-type = "*" / < VCHAR except "/" and "*" >
subtype        = "*" / < VCHAR except "+" >

A match pattern is a glob used for matching MIME types, for instance the pattern "application/*+json" matches "application/calendar+json", but does not match "application/json". The pattern "*/*json", on the other hand, matches both.

10.12.2 URL patterns

A URL pattern is a URL record that can be used to match the optional record identifier of every NDEF record ID field. A valid URL pattern is a valid URL record whose scheme component is equal to "https".

A URL pattern's scheme, host and path components that are used by the URL pattern match algorithm have the following matching rules:

URL pattern component	Matching rule for record identifier
host	exact match or ends with (URL pattern's host prepended with "`.`").
path	If URL pattern's path is "`/*`", match any record identifier path. Otherwise, begins with URL pattern's path.

Note

For example, 'https://mydomain.com/*' will match 'https://service.mydomain.com/myapp/' and 'https://info.mydomain.com/general/', while 'https://app.mydomain.com/contacts' will match 'https://app.mydomain.com/contacts' and 'https://app.mydomain.com/contacts/all' The '*' is a valid character for the URL path component, therefore, 'https://www.mydomain.com/*' pattern will match both 'https://www.mydomain.com/*' and 'https://www.mydomain.com/service' URLs.

10.12.3 URL pattern match algorithm

To match record identifier with URL pattern for a given record identifier and URL pattern, run these steps:

Let raw id be a record identifier passed to this algorithm.
Let raw pattern be a URL pattern passed to this algorithm.
If raw id and raw pattern are empty strings, return true.
Let id be the result of running the basic URL parser on raw id.
If id is failure, return false.
Let pattern be the result of running the basic URL parser on raw pattern.
If pattern is failure, return false.
Let subdomain pattern be the result of prepending "." to pattern's host.
If id's host does not end with subdomain pattern and id's host is not equal to pattern's host, return false.
If pattern's path is equal to "/*", return true.
If id's path begins with pattern's path, return true.
Otherwise, return false.

10.12.4 The scan() method

Incoming NFC content is matched using NFCReader instances.

When the NFCReader.scan method is invoked, the UA MUST run the following NFC listen algorithm:

Let reader be the NFCReader instance.
Let options be first argument.
For each key → value of options:
1. If key equals "signal" and value is not undefined, set reader.[[Signal]] to value.
2. Otherwise, if key equals "id", set reader.[[Id]] to value, prepended with "https://".
3. Otherwise, if key equals "recordType", set reader.[[RecordType]] to value.
4. Otherwise, if key equals "mediaType", set reader.[[MediaType]] to value.
If there is no underlying NFC Adapter, or if a connection cannot be established, then
1. Let e be the result of create a "NotSupportedError" DOMException.
2. Fire an event named "error" at reader using NFCErrorEvent with its error attribute initialized to e.
3. Return.
If the UA is not allowed to access the underlying NFC Adapter (e.g. a user preference), then
1. Let e be the result of create a "NotReadableError" DOMException.
2. Fire an event named "error" at reader using NFCErrorEvent with its error attribute initialized to e.
3. Return.
If reader.[[Signal]]'s aborted flag is set, then return.
If reader.[[Signal]] is not null, then add the following abort steps to reader.[[Signal]]:
1. Remove the NFCReader instance from the activated reader objects.
2. If the activated reader objects is empty, then make a request to stop listening to NDEF messages on all NFC adapters.
Run the following steps in parallel:
1. If the obtain reading permission steps return false, then
  1. Let e be the result of create a "NotAllowedError" DOMException.
  2. Fire an event named "error" at reader using NFCErrorEvent with its error attribute initialized to e.
  3. Return.
2. If this is the first listener being set up, then make a request to all NFC adapters to listen to NDEF messages.
3. If the request fails, then the UA may run the following sub-steps:
  1. Let e be the result of create a "NotSupportedError" DOMException.
  2. Fire an event named "error" at reader using NFCErrorEvent with its error attribute initialized to e.
  3. Return.
4. If the reader.[[Id]] is not an empty string and it is not a valid URL pattern, then
  1. Let e be the result of create a "SyntaxError" DOMException.
  2. Fire an event named "error" at reader using NFCErrorEvent with its error attribute initialized to e.
  3. Return.
5. Add reader to the activated reader objects.
6. If the Document of the top-level browsing context is not visible (e.g. the user navigated to another page), then the registered activated reader objects still SHOULD continue to exist, but SHOULD become paused, i.e. the UA SHOULD NOT check and use them until the Document is visible again.
7. Whenever the UA detects NFC technology, run the NFC reading algorithm.

To obtain reading permission, run these steps:

If there is a prearranged trust relationship, return true.
Otherwise, if the user has earlier denied permission for the calling origin for all future calls of scan() as well, then return false.
Otherwise, UAs SHOULD ask for forgiveness with relevant information displayed to the user.
Note
The ask for forgiveness interaction might show choices like "block now" or "block forever", etc. If the user has chosen to "block forever" the given origin, it is the responsibility of the UA to remember these user choices for each origin, regardless of which NFC adapter is used, and consult them on later invocations.

Note
In this step UAs are advised to notify users about that reading NFC content may indirectly reveal the physical location of the user.
Return true.

10.12.5 The NFC reading algorithm

To receive NDEF content, run the NFC reading algorithm:

If NFC is suspended, abort these steps.
If the NFC device in proximity range does not expose NDEF technology for reading or formatting, abort these steps.
Note
This means there is no reading event generated when non-NDEF NFC technology comes in proximity range. This may change in future version of the specification.
Let serialNumber be the device identifier as a series of numbers, or null if unavailable.
If serialNumber is not null, set it to the string of U+003A (:) concatenating each number represented as ASCII hex digit, in the same order.
Let message be a new NDEFMessage object, with message's records set to the empty list.
If the NFC device in proximity range is an unformatted NFC tag that is NDEF-formattable, let input be null. Otherwise, let input be the notation for the NDEF message which has been received.
Note
The UA SHOULD represent an unformatted NFC tag as an NDEF message containing no NDEF records, i.e. an empy array for its records property.
For each NDEF record which is part of input, run the following sub-steps:
1. Let ndef be the notation for the current NDEF record with typeNameField corresponding to the TNF field and payload corresponding to the PAYLOAD field data.
2. Let record be the result of parse an NDEF record on ndef.
3. If record is not null, append record to message's records.
If NFC is not suspended, run the dispatch NFC content steps with given serialNumber and message.

10.12.6 Dispatching NFC content

To dispatch NFC content given a serialNumber of type serialNumber, message of type NDEFMessage, run these steps:

For each NFCReader instance reader in the activated reader objects, run the following sub-steps:
1. If reader.[[Id]] is present and doesn't match any record's id where record is an element of message, continue.
2. If reader.[[RecordType]] is present and it is not equal to any record's recordType where record is an element of message, continue.
3. If reader.[[MediaType]] is not "" and it is not equal to any record's mediaType where record is an element of message, continue.
4. Fire an event named "reading" at reader using NFCReadingEvent with its serialNumber attribute initialized to serialNumber and message attribute initialized to message.

10.13 Parsing content

10.13.1 Parsing records from bytes

To parse records from bytes given bytes, run these steps:

Let records be the empty list.
As long as there are unread bytes of bytes, run the following sub-steps:
1. If remaining length of bytes is less than 3, abort these sub-steps.
2. If any of the following steps requires reading bytes beyond the remaining length of bytes, return records.
3. Let ndef be the notation for the current NDEF record
4. Let header be the next byte of bytes.
  1. Let messageBegin (MB field) be the left most bit (bit 7) of header.
  2. If this is the first iteration of these sub-steps and messageBegin is false, return records.
  3. Let messageEnd (ME field) be bit 6 of header.
  4. Let shortRecord (SR field) be bit 4 of header.
  5. Let hasIdLength (IL field) be bit 3 of header.
  6. Let ndef's typeNameField (TNF field) be the integer value of bit 2-0 of header.
5. Let typeLength be the integer value of next byte (TYPE LENGTH field) of bytes.
6. If shortRecord is true, let payloadLength be the integer value of next byte (PAYLOAD LENGTH field) of bytes.
7. Otherwise, let payloadLength be the integer value of the next 4 bytes of bytes.
8. If hasIdLength is true, let idLength be the integer value of next byte (ID LENGTH field) of bytes, otherwise let it be 0.
9. If typeLength > 0, let ndef's type be result of running UTF-8 decode on the next typeLength (TYPE field) bytes, orelse let type be the empty string.
10. If idLength > 0, let ndef's id be result of running UTF-8 decode on the next idLength (ID field) bytes, orelse let ndef's id be the empty string.
11. Let ndef's payload be the byte sequence of the last payloadLength (PAYLOAD field) bytes, which may be 0 bytes.
12. Let record be the result of parse an NDEF record on ndef.
13. If record is not null, append record to records.
14. If messageEnd is true, abort these sub-steps.
Return records.

10.13.2 Parsing NDEF records

To parse an NDEF record given ndef into a record, run these steps:

Set record's id to ndef's id.
If ndef's typeNameField is 0 (empty record), then set record's recordType to "empty" and set record's mediaType to "".
If ndef's typeNameField is 1 (well-known type record):
1. Set record to the result of the algorithm below switching on ndef's type:
  "T" (0x54)
  - running parse an NDEF text record on ndef.
  "U" (0x55)
  - running parse an NDEF URL record on ndef
  "Sp" (0x53 0x70)
  - running parse an NDEF smart-poster record on ndef
If ndef's typeNameField is 2 (MIME type record), then set record to the result of running parse an NDEF MIME type record on ndef, or make sure that the underlying platform provides equivalent values to the record object's properties.
Otherwise, if ndef's typeNameField is 3 (absolute-URL record), then set record to the result of running parse an NDEF absolute-URL record on ndef.
Otherwise, if ndef's typeNameField is 4 (external type record), then set record to the result of running parse an NDEF external type record on ndef, or make sure that the underlying platform provides equivalent values to the record object's properties.
Otherwise, if ndef's typeNameField is 5 (unknown record) then set record to the result of running parse an NDEF unknown record on ndef, or make sure that the underlying platform provides equivalent values to the record object's properties.

10.13.3 Parsing NDEF well-known `T` records

To parse an NDEF text record given a ndefRecord into a record, run these steps:

Set record's recordType to "text".
Let mimeType be a MIME type with type "text", subtype "plain" and parameters equal to an empty ordered map.
If ndefRecord's PAYLOAD field is not present, set |record|s mediaType to mimeType, set record.[[PayloadData]] to undefined and return record.
Let header be the first byte of ndefRecord's PAYLOAD field.
Let languageLength be the value given by bit 5 to bit 0 of the header.
Let language be the result of running ASCII decode on second byte to the languageLength + 1 byte, inclusive.
Set mimeType's parameters["lang"] to language.
Set record's mediaType to the result of serialize a MIME type with mimeType as the input.
Let buffer be the byte sequence of ndefRecords's PAYLOAD field.
Set record.[[PayloadData]] to buffer.
return record.

Note

The Unicode standard defines multiple encodings like UTF-8, UTF-16 and UTF-32. UTF-8 is the preferred encoding on the web, and it has the advantage that it is endianness agnostic, as code points are represented in single bytes.

The NDEF text records allow the text to be encoded as either UTF-8 or UTF-16. Generally, it is preferred to use UTF-8 encoding on the web, but integration with existing systems may require UTF-16.

The data transmission order and thus the byte order of NDEF is defined as big endian (BE) in NFC Data Exchange Format (NDEF) Technical Specification, which means that everything is read back with big endian byte ordering.

For UTF-16, byte order matters as it might differ between reading and writing due to each code point spanning two bytes. For this reason UTF-16 encoded text usually contains a byte order mark (also known as BOM) which is written as 0xFEFF. This means that if the byte order differs between host machine and NDEF, then the value will be read back as 0xFFFE, indicating that the byte order should be swapped. The Encoding Standard differentiates UTF-16 as UTF-16BE (big endian) and UTF-16LE (little endian) depending on the byte order.

In the case that no byte order mark is present, UTF-16BE encoding should be assumed.

Using the decoder with encoding set to utf-16, it will automatically detect whether bytes should be swapped in case the byte order mark is present. utf-16be can be used to read as big endian in case there is no byte order mark.

Using the encoder, it is only possible to encode as UTF-8, so if UTF-16 is needed, it will have to be encoded manually or by using a library.

10.13.4 Parsing NDEF well-known `U` records

To parse an NDEF URL record given a ndefRecord into a record, run these steps:

Set record's recordType to "url".
Set record's mediaType to "text/plain".
If ndefRecord's PAYLOAD field is not present, set record.[[PayloadData]] to undefined and return record.
Let buffer be the byte sequence of ndefRecords's PAYLOAD field.
Let prefixByte be the value of the first byte of buffer.
If the value of prefixByte matches the URL expansion codes in the NFC Forum Technical Specifications URI Record Type Definition specification, Section 3.2.2, Table 3, then
1. Let prefixString be the byte sequence value corresponding to the value of prefixByte.
2. Set record.[[PayloadData]] to prefixString appended to buffer.
Otherwise, if there is no match for prefixByte, set record.[[PayloadData]] to buffer.
return record.

10.13.5 Parsing NDEF well-known `Sp` records

To parse an NDEF smart-poster record given a ndefRecord into a record, run these steps:

Set record's recordType to "smart-poster".
Set record's mediaType to "".
If ndefRecord's PAYLOAD field is not present, set record.[[PayloadData]] to undefined and return record.
Let buffer be the byte sequence of ndefRecords's PAYLOAD field.
Set record.[[PayloadData]] to buffer.
return record.

10.13.6 Parsing NDEF MIME type records

To parse an NDEF MIME type record given a ndefRecord into a record, run these steps:

Let mimeType be the MIME type returned by running parse a MIME type on ndefRecord's TYPE field.
If mimeType is a JSON MIME type, then
1. Set record's recordType to "json".
2. Set record's mediaType to the result of serialize a MIME type with mimeType as the input.
Otherwise,
1. Set record's recordType to "media".
2. Set record's mediaType to the result of serialize a MIME type with mimeType as the input.
Let buffer be the byte sequence of ndefRecords's PAYLOAD field if that exists, or otherwise undefined.
Set record.[[PayloadData]] to buffer.
return record.

10.13.7 Parsing NDEF absolute-URL records

To parse an NDEF absolute-URL record given a ndefRecord into a record, run these steps:

Set record's recordType to "url".
Set record's mediaType to "text/plain".
Let buffer be the byte sequence of ndefRecords's TYPE field.
return record.

10.13.8 Parsing NDEF external type records

To parse an NDEF external type record given a ndefRecord into a record, run these steps:

Set record's recordType to the value of ndefRecord's TYPE field.
Set record's mediaType to "application/octet-stream".
Let buffer be the byte sequence of ndefRecords's PAYLOAD field if that exists, or otherwise undefined.
Set record.[[PayloadData]] to buffer.
return record.

10.13.9 Parsing NDEF unknown type records

To parse an NDEF unknown record given a ndefRecord into a record, run these steps:

Set record's recordType to "media".
Set record's mediaType to "application/octet-stream".
Let buffer be the byte sequence of ndefRecords's PAYLOAD field if that exists, or otherwise undefined.
Set record.[[PayloadData]] to buffer.
return record.

10.14 IDL Index

[Exposed=Window]
interface NDEFMessage {
  constructor(NDEFMessageInit messageInit);
  readonly attribute FrozenArray<NDEFRecord> records;
};

dictionary NDEFMessageInit {
  required sequence<NDEFRecordInit> records;
};

[Exposed=Window]
interface NDEFRecord {
  constructor(NDEFRecordInit recordInit);

  readonly attribute NDEFRecordType recordType;
  readonly attribute USVString mediaType;
  readonly attribute USVString id;

  USVString? text();
  [NewObject] ArrayBuffer? arrayBuffer();
  [NewObject] any json();
  sequence<NDEFRecord> toRecords();
};

dictionary NDEFRecordInit {
  required NDEFRecordType recordType;
  USVString mediaType;
  USVString id;

  any data;
};

typedef DOMString NDEFRecordType;

typedef (DOMString or ArrayBuffer or NDEFMessageInit) NDEFMessageSource;

[SecureContext, Exposed=Window]
interface NFCWriter {
  constructor();

  Promise<void> push(NDEFMessageSource message, optional NFCPushOptions options={});
};

[SecureContext, Exposed=Window]
interface NFCReader : EventTarget {
  constructor();

  attribute EventHandler onreading;
  attribute EventHandler onerror;

  void scan(optional NFCScanOptions options={});
};

[SecureContext, Exposed=Window]
interface NFCReadingEvent : Event {
  constructor(DOMString type, NFCReadingEventInit readingEventInitDict);

  readonly attribute DOMString serialNumber;
  [SameObject] readonly attribute NDEFMessage message;
};

dictionary NFCReadingEventInit : EventInit {
  DOMString? serialNumber = "";
  required NDEFMessageInit message;
};

[SecureContext, Exposed=Window]
interface NFCErrorEvent : Event {
  constructor(DOMString type, NFCErrorEventInit errorEventInitDict);

  readonly attribute DOMException error;
};

dictionary NFCErrorEventInit : EventInit {
  required DOMException error;
};

dictionary NFCPushOptions {
  NFCPushTarget target = "any";
  unrestricted double timeout = Infinity;
  boolean ignoreRead = true;
  boolean overwrite = true;
  AbortSignal? signal;
};

enum NFCPushTarget {
  "tag",
  "peer",
  "any"
};

dictionary NFCScanOptions {
  USVString id = "";
  NDEFRecordType recordType;
  USVString mediaType = "";
  AbortSignal? signal;
};

10.15 Acknowledgments

The editors would like to thank Jeffrey Yasskin, Anne van Kesteren, Anssi Kostiainen, Domenic Denicola, Daniel Ehrenberg, Jonas Sicking, Don Coleman, Salvatore Iovene, Rijubrata Bhaumik, Wanming Lin, and François Beaufort for their contributions to this document.

Special thanks to Luc Yriarte and Samuel Ortiz for their initial work on exposing NFC to the web platform, and for their support for the current approach.

Web NFC API

Draft Community Group Report 16 October 2019

Abstract

Status of This Document

1. Conformance

2. Introduction

3. Terminology and conventions

3.1 Security related terms

3.2 NFC specific terms

4. The NFC Standard

4.1 NDEF compatible tag types

4.2 The NDEF record and fields

4.3 NDEF Record types

4.3.1 Empty NDEF record (TNF 0)

4.3.2 Well-known type records (TNF 1)

4.3.2.1 Text record

4.3.2.2 URI record

4.3.2.3 Smart poster record

4.3.2.4 Signature records

4.3.2.5 Handover records

4.3.3 MIME type records (TNF 2)

4.3.4 Absolute-URL records (TNF 3)

4.3.5 External type records (TNF 4)

4.3.6 Unknown type records (TNF 5)

4.3.7 Unchanged type records (TNF 6)

5. Use Cases

5.1 Reading an NFC tag

5.2 Writing to an NFC tag

5.3 Pushing data to an NFC peer device

5.4 Handover to another wireless connection type

5.5 Payment scenarios

5.6 Support for multiple NFC adapters

6. Features

7. Examples

7.1 Push a text string to either a tag or peer

7.2 Push a text string to a peer device

7.3 Push a URL to either a tag or peer

7.4 Read data from tag, and write to empty ones

7.5 Save and restore game progress with another device

7.6 Push and read JSON (serialized and deserialized)

7.7 Write data to tag and print out existing data

7.8 Stop listening to NDEF messages

7.9 Push a smart poster message

7.10 Read an external record with an NDEF message as payload

7.11 Push an external record with an NDEF message as payload

8. Security and Privacy

8.1 Chain of trust

8.2 Threats

8.3 Permissions and user prompts

8.4 Security policies

8.4.1 Secure Context

8.4.2 Visible document

8.4.3 Permissions controls

8.4.4 Store site URL as record identifier when writing data

8.4.5 Warn risk of physical location leak

8.4.6 Restrict automatic handling

9. Data Representation

9.1 The NDEFMessage interface

9.2 The NDEFRecord interface

9.3 The NDEFRecordType string

9.4 Data mapping

10. The NFCReader and NFCWriter objects

10.1 NFC state associated with the settings object

10.2 Handling NFC adapters

10.3 Handling visibility change

10.4 Clearing the pending push tuple

10.5 Aborting pending push operation

10.6 Releasing NFC

10.7 The NFCPushOptions dictionary

10.8 The NFCPushTarget enum

10.9 The NFCScanOptions dictionary

10.10 Writing or pushing content

10.10.1 The push() method

10.10.2 Obtaining push permission

10.11 Creating content

10.11.1 Creating NDEF message

10.11.2 Mapping empty record to NDEF

10.11.3 Mapping string to NDEF

10.11.4 Mapping URL to NDEF

10.11.5 Mapping JSON to NDEF

9.1 The `NDEFMessage` interface

9.2 The `NDEFRecord` interface

9.3 The `NDEFRecordType` string

10.7 The `NFCPushOptions` dictionary

10.8 The `NFCPushTarget` enum

10.9 The `NFCScanOptions` dictionary

10.13.3 Parsing NDEF well-known `T` records

10.13.4 Parsing NDEF well-known `U` records

10.13.5 Parsing NDEF well-known `Sp` records