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 record s, 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 record s are records that store opaque data with associated MIME type .

2.4.4 Absolute-URL records (TNF 3)

In absolute-URL record s 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 record s are for client specified data and must have a type name following the NFC Record Type Definition (RTD) Technical Specification standard.

2.4.7 2.4.6 Unknown type records (TNF 5)

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

2.4.8 2.4.7 Unchanged type records (TNF 6)

The unchanged record s 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.9.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. If the message parameter is not of type defined by the NDEFMessageSource union, reject p with a TypeError , and abort these steps.
    5. If the message parameter is of NDEFMessageInit type, and message 's records is empty , reject p with a TypeError and abort these steps.
    6. If timeout value is NaN or negative, reject p with a TypeError and abort these steps.
    7. If timeout value is not supported by the UA, reject p with a " NotSupportedError " DOMException and abort these steps.
    8. 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.
    9. 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 .
    10. Attempt to abort a pending push operation .
    11. Associate output with slot .
    12. If timeout value is not equal to Infinity , start a timer timer with the timeout value set to timeout .
    13. 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 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 idHost be the message 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. 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 adapter s. 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 adapter s.

           5. When the transfer has completed, clear output associated with target , resolve p .

    14. Let transformedPromise be the result of transforming React to p :
        1. If p with a fulfillment and rejection handler that: was settled (fulfilled or rejected), then:
           1. Clears the pending push tuple .
           2. Removes async write handlers .
    15. Set pending push tuple to ( this , transformedPromise p ).
    16. Return transformedPromise p .
    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.10.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.10.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:

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

9.10.3 URL pattern match algorithm

1. Let raw id be a message record identifier passed to this algorithm.
2. Let raw pattern be a URL pattern passed to this algorithm.
3. If raw id and raw pattern are empty string s, return true .
4. Let id be the result of running the basic URL parser on raw id .
5. If id 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 id 's host does not end with subdomain pattern and author id 's host is not equal to pattern 's host , return false .
10. If pattern 's path is equal to " /* ", return true .
11. If author id 's path begins with pattern 's path , return true .
12. Otherwise, return false .

9.10.4 The scan() method

The section §  9.11 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 id ", set reader . [[Url]] [[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 .
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 message s on all NFC adapter s.
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 adapter s to listen to NDEF message s.
   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]] [[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 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.11.1 Parsing records from bytes

1. Let records be the empty list.
2. 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 .
      Note
      As chunked records are not allowed as sub records, we ignore bit 5 ( CF field ).
      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.
3. Return records .

9.11.2 Parsing NDEF records

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

1. Set record 's id to ndef 's id .
2. If ndef 's typeNameField is 0 ( empty record ), then set record 's recordType to " empty " and set record 's mediaType to "" .
3. 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

4. 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.
5. If 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 .
6. If ndef 's typeNameField 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 . 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.
7. 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.

9.11.3 Parsing NDEF well-known T records

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

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

9.11.4 Parsing NDEF well-known U records

To parse an 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. If ndefRecord 's PAYLOAD field is not present, set record . [[PayloadData]] to undefined and return record .
4. Let buffer be the byte sequence of ndefRecords 's PAYLOAD field .
5. Let prefixByte be the value of the first byte of buffer .
6. 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 .
7. Otherwise, if there is no match for prefixByte , set record . [[PayloadData]] to buffer .
8. return record .

9.11.5 Parsing NDEF well-known Sp records

To parse an 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. If ndefRecord 's PAYLOAD field is not present, set record . [[PayloadData]] to undefined and return record .
4. Let buffer be the byte sequence of ndefRecords 's PAYLOAD field .
5. Set record . [[PayloadData]] to buffer .
6. return record .

9.11.6 Parsing NDEF MIME type records

To parse an 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. 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.
4. Let buffer be the byte sequence of ndefRecords 's PAYLOAD field if that exists, or otherwise undefined .
5. Set record . [[PayloadData]] to buffer .
6. return record .

9.11.7 Parsing NDEF absolute-URL records

To parse an 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. Let buffer be the byte sequence of ndefRecords 's TYPE field .
4. return record .

9.11.8 Parsing NDEF external type records

To parse an 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. Let buffer be the byte sequence of ndefRecords 's PAYLOAD field if that exists, or otherwise undefined .
4. Set record . [[PayloadData]] to buffer .
5. return record .

9.11.9 Parsing NDEF unknown type records

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

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

9.11.10 The NFC reading algorithm

1. If NFC is suspended , abort these steps.
2. Let message be a new NDEFMessage object, with message 's url set to null and message 's records set to the empty list .
3. Let serialNumber be the device identifier as a series of numbers, or null if unavailable.
4. 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.
5. Let input be the notation for the NDEF message which has been received.
6. 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.
7. If NFC is not suspended and message 's records is not empty , run the dispatch NFC content steps with given serialNumber and message .

9.11.11 Dispatching NFC content

To dispatch NFC content given a serialNumber of type serialNumber , message of type NDEFMessage , 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 If reader . [[Url]] [[Id]] as the URL pattern is present and message doesn't match any record 's url as the message identifier . If match id where record is false , an element of message , continue .
   2. If reader . [[RecordType]] is present and it is not equal to any record .[[RecordType]] '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 .