Web NFC API

2.4.1 Empty NDEF records (TNF 0)

2.4.2 Well-known records (TNF 1)

The NFC Forum has standardized a small set of useful RTD (Record Type Definition) types for use in the NFC Forum well-known type records, for instance text, URL, and binary data such as media. 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. Most of these are defined in NFC Record Type Definition (RTD) Technical Specification.

For well-known records, the RTD type is stored in the TYPE field and is "T" (0x54) for text, "U" (0x55) for url and "Sp" (0x53, 0x70) for smart poster.

Other known RTD types supported by the platform and not Web NFC are "ac" (0x61, 0x63) for alternative carrier, "Hc" (0x48, 0x63) for handover carrier, "Hr" (0x48, 0x72) for handover request, and "Hs" (0x48, 0x73) for handover select.

An NFC handover defines RTD 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.

Smart poster embeds additional records inside its payload. Below you see an example embedding a text and a url record.

2.4.3 MIME type records (TNF 2)

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

2.4.4 Absolute-URL records (TNF 3)

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

2.4.5 External type records (TNF 4)

The NFC Forum external type records are for client specified data and must have a type name following the NFC Record Type Definition (RTD) Technical Specification standard.

2.4.6 Web NFC author records (TNF 4)

When writing data with Web NFC, a special author type record is written in addition to the other records. This record is specificed by this specification and is specific to Web NFC. The record indicates that the containing NDEF message is targeted for browsing contexts using this API and contains information useful for handling the NDEF message with the algorithms defined in this specification. The format is as follows:

• A short, non-chunked record with IL field set to 0 and thus no ID LENGTH field and ID field.
• Uses NFC Forum external type record with the TYPE field set to "w3.org:A".
• The payload contains the message author of the Web NFC message.

The message author host is a serialized host.

The message author is a message author host, optionally followed by a path-absolute-URL string. This enables matching Web NFC content with URL patterns specified by NFCReaders. For NDEF messages that are not Web NFC messages, the message author is null.

The term Web NFC content denotes all Web NFC messages contained within an NDEF message, identified by the message author. This version of the specification supports one author type record per NDEF message.

2.4.7 Unknown type records (TNF 5)

The unknown records are records that store opaque data without associated MIME type.

2.4.8 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.

First record:
Intermediate record:
Last record:

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

9.10.1 The push() method

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

1. Let p be a new Promise object.
2. Let message be the first argument.
3. Let options be the second argument.
4. Let signal be the options’ dictionary member of the same name if present, or null otherwise.
5. If there is no underlying NFC Adapter, or if a connection cannot be established, then reject p with a "NotSupportedError" DOMException and return p.
6. 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.
7. If pushing data is not supported by the underlying NFC Adapter, then reject p with a "NotSupportedError" DOMException and return p.
8. If signal’s aborted flag is set, then reject p with an "AbortError" DOMException and return p.
9. If signal is not null, then add the following abort steps to signal:
   1. If the instance has already initiated NFC data transfer, and it can't be aborted, ignore the abort signal and return.
   2. Stop the instance's timer if it is active.
   3. Reject p with an "AbortError" DOMException and abort these steps.
10. Run the following steps in parallel:
    1. An implementation MAY reject p with a "NotSupportedError" DOMException and abort these steps.
       Note

       The UA might terminate message push at this point. The reasons for terminations 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 operation requested.
    2. Let target be options's target.
    3. Let timeout be options's timeout.
    4. Let compatibility be options's compatibility.
    5. If the message parameter is not of type defined by the NDEFMessageSource union, reject p with a TypeError, and abort these steps.
    6. If the message parameter is of NDEFMessageInit type, and message's records is empty, reject p with a TypeError and abort these steps.
    7. If timeout value is NaN or negative, reject p with a TypeError and abort these steps.
    8. If timeout value is not supported by the UA, reject p with a "NotSupportedError" DOMException and abort these steps.
    9. Let output be the notation for the NDEF message to be created by UA, as the result of passing message to create Web NFC message. If this throws an exception, reject p with that exception and abort these steps.
    10. If target is "any", run the following steps twice, once with slot set to the value "tag", and once set to the value "peer"; otherwise run the following step once, with slot set to the value of target.
    11. Attempt to abort a pending push operation.
    12. Associate output with slot.
    13. If timeout value is not equal to Infinity, start a timer timer with the timeout value set to timeout.
    14. Add the following async write handlers:

        The timer expires

        1. Reject p with "TimeoutError" DOMException.

        An NFC device device comes within communication range

        1. Verify the following conditions:
           • if device is not officially supported by the NFC Forum, compatibility is "vendor" or "any".
           • 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 sub-steps:
           1. Stop timer if active.
           2. If device is an NFC tag,
              • Read the tag.
              • If options's ignoreRead is not equal to true, run the receiving steps.
              • Let authorHost be the message author host of the tag.
              • If authorHost 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. Initiate data transfer to device using output as buffer, using the NFC adapter in communication range with (connected to) device.
           4. If the transfer fails, reject p with "NetworkError" DOMException and abort these steps.
              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. When the transfer has completed, clear output associated with target, resolve p.

    15. Let transformedPromise be the result of transforming p with a fulfillment and rejection handler that:
        1. Clears the pending push tuple.
        2. Removes async write handlers.
    16. Set pending push tuple to (this, transformedPromise).
    17. Return transformedPromise.
    Note

    If NFC is suspended, continue waiting until timer expires (if set), or promise is aborted by the user, or until an NFC device comes within communication range.

9.11.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 "+" >

9.11.2 URL patterns

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

9.11.3 URL pattern match algorithm

1. Let raw author be a message author passed to this algorithm.
2. Let raw pattern be a URL pattern passed to this algorithm.
3. If raw author and raw pattern are empty strings, return true.
4. Let author be the result of running the basic URL parser on raw author.
5. If author is failure, return false.
6. Let pattern be the result of running the basic URL parser on raw pattern.
7. If pattern is failure, return false.
8. Let subdomain pattern be the result of prepending "." to pattern's host.
9. If author's host does not end with subdomain pattern and author's host is not equal to pattern's host, return false.
10. If pattern's path is equal to "/*", return true.
11. If author's path begins with pattern's path, return true.
12. Otherwise, return false.

9.11.4 The scan() method

The section § 9.12 Receiving and parsing content uses NFCReader instances to match incoming NFC content.

Multiple consecutive calls to the scan() method from the same origin create filters which are in OR relationship.

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

1. Let reader be the NFCReader instance.
2. Let options be first argument.
3. For each key → value of options:
   1. If key equals "signal", set reader.[[Signal]] to value.
   2. Otherwise, if key equals "url", set reader.[[Url]] 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.
   5. Otherwise, if key equals "compatibility", set reader.[[Compatibility]] to value.
4. 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.
5. 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.
6. If reader.[[Signal]]’s aborted flag is set, then return.
7. 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.
8. 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.[[Url]] 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 and focused (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 and focused again.

To obtain reading permission, run these steps:

1. If there is a prearranged trust relationship, return true.
2. Otherwise, if the user has earlier denied permission for the calling origin for all future calls of scan() as well, then return false.
3. 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.

4. Return true.

9.12.1 Parsing NDEF well-known T records

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

1. Let header be the first byte of ndefRecord's PAYLOAD field.
2. Let languageLength be the value given by bit 5 to bit 0 of the header.
3. Let language be the result of running ASCII decode on second byte to the languageLength + 1 byte, inclusive.
4. Let mimeType be a MIME type with type "text", subtype "plain" and parameters equal to an empty ordered map.
5. Set mimeType's parameters["lang"] to language.
6. Set record's recordType to "text".
7. Set record's mediaType to the result of serialize a MIME type with mimeType as the input.
8. Set record.[[PayloadData]] to the byte sequence of ndefRecord's PAYLOAD field.
9. return record.

9.12.2 Parsing NDEF well-known U records

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

1. Set record's recordType to "url".
2. Set record's mediaType to "text/plain".
3. Let prefixByte be the value of the first byte of ndefRecord's PAYLOAD field.
4. If prefixByte is not 0, then match the prefixByte against the prefix codes in NFC Forum Technical Specifications, URI Record Type Definition specification, Section 3.2.2.
5. Let prefixString be the matched prefix or else the empty string.
6. Let buffer be the byte sequence of ndefRecords's PAYLOAD field from the second byte to the end.
7. Set record.[[PayloadData]] to buffer.
8. return record.

9.12.3 Parsing NDEF well-known Sp records

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

1. Set record's recordType to "smart-poster".
2. Set record's mediaType to "".
3. Set record.[[PayloadData]] to the byte sequence of ndefRecord's PAYLOAD field.
4. return record.

9.12.4 Parsing NDEF MIME type records

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

1. Let mimeType be the MIME type returned by running parse a MIME type on ndefRecord's TYPE field.
2. 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.
   3. Set record.[[PayloadData]] to the byte sequence of ndefRecord's PAYLOAD field.
3. Otherwise,
   1. Set record's recordType to "opaque".
   2. Set record's mediaType to the result of serialize a MIME type with mimeType as the input.
   3. Set record.[[PayloadData]] to the byte sequence of ndefRecord's PAYLOAD field.
4. return record.

9.12.5 Parsing NDEF absolute-URL records

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

1. Set record's recordType to "url".
2. Set record's mediaType to "text/plain".
3. Set record.[[PayloadData]] to the value of ndefRecord's TYPE field.
4. return record.

9.12.6 Parsing NDEF external type records

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

1. Set record's recordType to the value of ndefRecord's TYPE field.
2. Set record's mediaType to "application/octet-stream".
3. Set record.[[PayloadData]] to the byte sequence of ndefRecord's PAYLOAD field.
4. return record.

9.12.7 Parsing NDEF unknown type records

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

1. Set record's recordType to "opaque".
2. Set record.[[PayloadData]] to the byte sequence of ndefRecord's PAYLOAD field.
3. return record.

9.12.8 The NFC reading algorithm

1. If NFC is suspended, abort these steps.
2. Let compatibility be "vendor" if the read NDEF compatible device is not officially supported by the NFC Forum, or else "nfc-forum".
3. Let message be a new NDEFMessage object, with message's url set to null and message's records set to the empty list.
4. Let serialNumber be the device identifier as a series of numbers, or null if unavailable.
5. 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.
6. Let input be the notation for the NDEF message which has been received.
7. 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.
   2. Let record be a new NDEFRecord object.
   3. If ndef's TNF field is 0 (empty record), then set record's recordType to "empty" and set record's mediaType to "".
   4. If ndef's TNF field is 1 (well-known type record):
      1. Set record to the result of the algorithm below switching on ndef's TYPE field:

         "T" (0x54)

         • running parse a NDEF text record on ndef.

         "U" (0x55)

         • running parse a NDEF URL record on ndef

         "Sp" (0x53 0x70)

         • running parse a NDEF smart-poster record on ndef

   5. If ndef's TNF field is 2 (MIME type record), then set record to the result of running parse a NDEF MIME type record on ndef, or make sure that the underlying platform provides equivalent values to the record object's properties.
   6. If ndef's TNF field is 3 (absolute-URL record), then set record to the result of running parse a NDEF absolute-URL record on ndef.
   7. If ndef's TNF field is 4 and ndef's lowercased TYPE field is "w3.org:a" (author type record), then set message's url to the ndef's PAYLOAD field.
   8. Otherwise, if ndef's TNF field is 4 (external type record), then set record to the result of running parse a NDEF external type record on ndef, or make sure that the underlying platform provides equivalent values to the record object's properties.
   9. Otherwise, if ndef's TNF field is 5 (unknown record) then set record to the result of running parse a NDEF unknown record on ndef, or make sure that the underlying platform provides equivalent values to the record object's properties.
   10. Otherwise, skip to the next NDEF record in input.
   11. Append record to message's records.
8. If NFC is not suspended and message's records is not empty, run the dispatch NFC content steps with given serialNumber, message and compatibility.

9.12.9 Dispatching NFC content

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

1. For each NFCReader instance reader in the activated reader objects, run the following sub-steps:
   1. Let match be the result of running URL pattern match, with reader.[[Url]] as the URL pattern and message's url as the message author.
   2. If match is false, continue.
   3. If reader.[[RecordType]] is present and it is not equal to any record.[[RecordType]] where record is an element of message, continue.
   4. If reader.[[MediaType]] is not "" and it is not equal to any record's mediaType where record is an element of message, continue.
   5. If reader.[[Compatibility]] is not "any", and not equal to compatibility, continue.
   6. Fire an event named "reading" at reader using NFCReadingEvent with its serialNumber attribute initialized to serialNumber and message attribute initialized to message.