Web NFC API

1. Conformance

As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.

The key words MAY, MUST, MUST NOT, SHOULD, and SHOULD NOT are to be interpreted as described in [RFC2119].

This document defines conformance criteria that apply to a single product: the UA (user agent) that implements the interfaces it contains.

Implementations that use ECMAScript to implement the APIs defined in this document MUST implement them in a manner consistent with the ECMAScript Bindings defined in the Web IDL specification [WEBIDL], as this document uses that specification and terminology.

2. Terminology and conventions

The terms URL and URL path are defined in [URL].

The following terms are defined in [HTML5]: browsing context, top-level browsing context, global object, incumbent settings object, script execution environment, Document, document base URL, Window, WindowProxy, origin, ASCII serialized origin, executing algorithms in parallel, queue a task, task source, iframe, valid MIME type.

A browsing context refers to the environment in which Document objects are presented to the user. A given browsing context has a single WindowProxy object, but it can have many Document objects, with their associated Window objects. The script execution environment associated with the browsing context identifies the entity which invokes this API, which can be a web app, a web page, or an iframe.

The term secure context is defined in [WEBAPPSEC].

Inspired by the Streams specification, we use the notation x@[[y]] to refer to internal slots of an object, instead of saying "the [[y]] internal slot of x".

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.

The Augmented Backus-Naur Form (ABNF) notation used is specified in [RFC5234].

DOMString, ArrayBuffer, BufferSource and any are defined in [WEBIDL].

DOMException, AbortError, SyntaxError, NotSupportedError, NotFoundError, NetworkError, NoModificationAllowedError, SecurityError are defined in [DOM4].

Promise, JSON, JSON.stringify and JSON.parse are defined in [ECMASCRIPT].

The algorithms utf-8 encode, and utf-8 decode are defined in [ENCODING].

IANA media types (formerly known as MIME types) are defined in RFC2046.

2.2 NFC specific terms

NFC stands for Near Field Communications, short-range wireless technology operating at 13.56 MHz which enables communication between devices at a distance less than 10 cm. The NFC communications protocols and data exchange formats, and are based on existing radio-frequency identification (RFID) standards, including ISO/IEC 14443 and FeliCa. The NFC standards include ISO/IEC 18092[5] and those defined by the NFC Forum. See https://www.nfc-forum.org/specs/spec_list/ for a complete listing.

An NFC adapter is the software entity in the underlying platform which provides access to NFC functionality implemented in a given hardware element (NFC chip). A device may have multiple NFC adapters, for instance a built-in one, and one or more attached via USB.

An NFC tag is a passive NFC device. The NFC tag is powered by magnetic induction when an active NFC device is in proximity range. An NFC tag contains a single NDEF message.

Note

The way of reading the message may happen through proprietary technologies, which require the reader and the tag to be of the same manufacturer. Implementations are expected to encapsulate this.

An NFC peer is an active, powered device, which can interact with other devices in order to exchange data using NFC.

An NFC device is either an NFC peer, or an NFC tag.

An NDEF message encapsulates one or more application-defined NDEF records. NDEF is an abbreviation for NFC Forum Data Exchange Format, a lightweight binary message format. NDEF messages can be stored on an NFC tag or exchanged between NFC-enabled devices.

The term NFC content is a synonym for NDEF message, which can originate either from an NFC tag or an NFC peer.

An NDEF record is a part of an NDEF message that has a single associated type information to its payload. It contains a Type Name Format (TNF) field, the payload size, the payload type, an optional identifier which is a URL, and a payload of maximum size of 2^32-1 bytes. The NFC Forum has standardized a small set of useful data types for use in NDEF 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, and handover records.

The TNF (Type Name Format) field of the NDEF record can take binary values denoting the following NDEF record payload types:

TNF value	NDEF record type
0	Empty
1	NFC Forum Well-Known Type
2	Media Type
3	Absolute URI
4	NFC Forum External Type
5	Unknown
6	Unchanged
7	Reserved

NFC Forum Well-Known Type includes record types text, URI, Smart Poster (containing an URL or other data, and possible actions).

An NFC watch is a mechanism used to watch for available Web NFC messages fulfilling certain criteria. It is defined in more detail in The watch() method section.

A Web NFC message consists of a set of NDEF records, one of which is a Web NFC record.

The Web NFC message origin is an ASCII serialized origin with "https" scheme, stored in the Web NFC record. For NFC content that is not a Web NFC message, it is null.

The Web NFC Id is a URL according to [RFC3986], specifically the Web NFC message origin optionally followed by a URL path, stored in the Web NFC Record. This enables matching Web NFC content with URL patterns specified by NFC watches.

A Web NFC record is an NDEF record of External Type, specific to Web NFC. It 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 of a Web NFC record is as follows:

Uses NFC Forum External Type record (TNF=4) with the External Type field set to urn:nfc:ext:w3.org:webnfc.
The payload contains the Web NFC Id of the Web NFC message.

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

Note

As part of the NDEF record, an NDEF Id field may be present for application specific usages. According to the [NFC-STANDARDS] it contains a URL with the maximum length of 256 octets. This URL is used for identifying the NDEF record payload in an application specific way. This version of the specification does not use NDEF Id for NDEF record level payload identification, since NDEF message level identification is used.

An NFC handover defines NFC Forum Well Known Types 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.

5.1 Reading an NFC tag

Reading an NFC tag containing a Web NFC message, when a web page using the Web NFC API is open and in focus. For instance, a web page instructs the user to tap an NFC tag, and then receives information from the tag.
Reading an NFC tag containing other than Web NFC message, when a web page using the Web NFC API is open and in focus.
Reading an NFC tag when no web site using the Web NFC API is open or in focus. This use case is not supported in this version of the specification, and is has low priority for future versions as well.

5.2 Writing to an NFC tag

The user opens a web page which can write an NFC tag. The write operations may be one of the following:

Writing to an empty NFC tag.
Writing to an NFC tag which already contains a Web NFC message with a different Web NFC message origin (i.e. overwriting a web-specific tag).
Writing to an NFC tag which already contains a Web NFC message with the same Web NFC message origin (i.e. updating own tag).
Writing to other, writable NFC tags (i.e. overwriting a generic tag).

Note that an NFC write operation to an NFC tag always involves also a read operation.

5.3 Pushing data to an NFC peer device

In general, pushing data to another Web NFC capable device requires that on the initiating device the user would first have to navigate to a web site. The user would then touch the device against another Web NFC equipped device, and data transfer would occur. On the receiving device the UA will dispatch the content to an application registered and eligible to handle the content, and if that application is a browser which has a web page open and in focus that uses the Web NFC API and has set up a NFC watch to listen to Web NFC content, then the content is delivered to the web page through the parameters of an NFCMessageCallback.

5.4 Handover to another wireless connection type

NFC supports handover protocols to Bluetooth or WiFi connectivity for the purpose of larger volume data transfer. The user touches another NFC capable device, and as a result configuration data is sent for a new Bluetooth or WiFi connection, which is then established between the devices. This use case is not supported in this version of the specification.

5.5 Payment scenarios

The user buys goods in a store, and payments options include NFC. In general, touching the device to the point of sales terminal receiver area will result in a transaction between the secure element from the device and the point of sales terminal. With the Web NFC API, if the user navigates to a web site before paying, there may be interaction with that site regarding the payment, e.g. the user could get points and discounts, or get delivered application or service specific data (e.g. tickets, keys, etc) to the device. This use case is not supported in this version of the specification.

5.6 Support for multiple NFC adapters

Users may attach one or more external NFC adapters to their devices, in addition to a built-in adapter. Users may use either NFC adapter.

7. Security and Privacy

The trust model, attacker model, threat model and possible mitigation proposals for the Web NFC API are presented in the Security and Privacy document. This section presents the chosen security and privacy model through normative requirements to implementations.

7.1 Chain of trust

Web pages using the Web NFC API are not trusted. This means that the user needs to be aware of exactly what a web page is intending to do with NFC at any given moment. Implementations need to make sure that when the user authorizes a method of this API, then only that action is run, without side effects, and exactly in the context and the number of times the user allows the execution of NFC related operations, according to the algorithmic steps detailed in this specification.

The integrity of NFC content SHOULD NOT be trusted when used for implementing security policies, for instance the authenticity of origins saved in the Web NFC Id, unless a prearranged trust relationship exists.

7.2 Threats

The main threats are summarized in the Security and Privacy document.

In this specification the following threats are handled with the highest priority:

User data privacy: involuntary sharing of user data (such as location, contacts, personal data, etc) from an NFC-capable device such as a phone, tablet, or PC.
Protecting existing NFC tags from being overwritten by malicious web pages.

7.3 Permissions and user prompts

This specification attempts to minimize user prompting and uses implicit security policies to address the threats. However, this specification does not describe, nor does it mandate specific user prompting policies. The term obtain permission is used for acquiring trust for a given operation.

Note

The Permissions API is suggested to be used by UAs for implementing NFC related [permissions] in order to minimize the need for user prompting.

All expressed permissions that are preserved beyond the current browsing session MUST be revocable.

7.4 Security policies

This section is non-normative.

This section summarizes the security policies which are specified as normative requirements in the respective algorithms of this specification:

Only script execution environments of Documents with a browsing context, and an incumbent settings object which is a secure context are allowed to access NFC content. Browsers may ignore this rule for development purposes only.
In order to use NFC, the Window object associated with the Document contained by the top level browsing context using the Web NFC API must be visible and in focus. This also means that UAs should block access to the NFC radio if the display is off or the device is locked. For backgrounded web pages, receiving and pushing NFC content must be suspended.
When pushing Web NFC content, the ASCII serialized origin and the URL path of the incumbent settings object of the script execution environment requesting the operation must be recorded in each sent NDEF message's Web NFC record. For details see the Writing or pushing content section.
When setting up NFC watches, when pushing NFC content, the UA may warn the user that the given origin may be able to infer physical location.
Pushing Web NFC content to an NFC tag does not need to obtain permission, if the Web NFC message origin of the Web NFC message on that NFC tag is equal to the ASCII serialized origin of the incumbent settings object. Otherwise the UA must obtain permission for pushing NFC content which overwrites existing information. See also the Writing or pushing content section.
Pushing NFC content to an NFC peer does not need to obtain permission, but the previous rules apply. See the Writing or pushing content section.
Making an NFC tag read-only must obtain permission, or otherwise fail.
Setting up listeners for reading NFC content should obtain permission.
The process of reading an NDEF message does not need to obtain permission.
The payload data on NFC content is untrusted, and must not be used by the UA to do automatic handling such as opening a web page with a URL found in an NFC tag, unless the user approves that.
Since all local content that a web page has access to can be shared with NFC, the user needs to be clearly aware about the permissions granted to the web page using the Web NFC API.

8. Data Representation

8.1 The NFCRecord dictionary

The content of any NDEF record is exposed by the NFCRecord dictionary:

enum NFCRecordType {
    "empty",
    "text",
    "url",
    "json",
    "opaque"
};

typedef (DOMString or unrestricted double or ArrayBuffer or Dictionary) NFCRecordData;

dictionary NFCRecord {
    NFCRecordType recordType;
    USVString     mediaType;
    NFCRecordData data;
};

The NFCRecord.mediaType property represents the IANA media type of the NDEF record payload.

The NFCRecord.data property represents the payload data of the NDEF record with an appropriate ECMAScript type, which depends on the IANA media type.

The NFCRecord.recordType property represents the NDEF record types. The mapping from data types of an NFCRecord to and from NDEF record types is presented in the algorithmic steps which handle the data and described in the Receiving and parsing content and Writing or pushing content sections.

8.2 The NFCMessage dictionary

The content of any Web NFC message is exposed by the NFCMessage dictionary:

dictionary NFCMessage {
    sequence<NFCRecord> data;
    USVString           url;
};

The NFCMessage.url property represents the Web NFC Id of a received Web NFC message. When used in the NFC.push() method, it represents a URL path used for constructing the Web NFC Id of the pushed Web NFC content.

The NFCMessage.data property represents the NDEF message defining the Web NFC message.

8.3 Data mapping

A JSON compatible IANA media type is defined by the following ABNF:

      "application/" ("json" / <VCHAR except '/' and "*"> "+json")

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

NFCRecord recordType	NFCRecord mediaType	NFCRecord data	NDEF record type
"empty"	not used	not used	NFC Forum Empty Type (TNF=0)
"text"	not used	`DOMString`	NFC Forum Well Known Type (TNF=1) with type Text
"url"	not used	`DOMString`	NFC Forum Well Known Type (TNF=1) with type URI
"json"	JSON compatible IANA media type	`null` or `DOMString` or `Number` or `Dictionary`	Media Type as defined in [RFC2046] (TNF=2) with IANA media type specified in the `type` attribute.
"opaque"	IANA media type	`ArrayBuffer`	Media Type as defined in [RFC2046] (TNF=2)
"opaque"	`""` (empty)	`ArrayBuffer` or typed array	NFC Forum External Type (TNF=4)

The mapping from NDEF record types to NFCRecord, as used for incoming NDEF messages described in the Receiving and parsing content section, is as follows:

NDEF record type	NFCRecord recordType	NFCRecord mediaType	NFCRecord data
NFC Forum Empty Type (TNF=0)	"empty"	""	`null`
NFC Forum Well Known Type (TNF=1) with type Text	"text"	"text/plain"	`DOMString`
NFC Forum Well Known Type (TNF=1) with type URI	"url"	"text/plain"	`DOMString`
NFC Forum Well Known Type (TNF=1) with type Smart Poster	"url"	"text/plain"	`DOMString`
Absolute URI as defined in [RFC3986] (TNF=3)	"url"	"text/plain"	`DOMString`
Media Type as defined in [RFC2046] (TNF=2) with JSON compatible IANA media type	"json"	The IANA media type used in the NDEF record	`null` or `DOMString` or `Number` or `Dictionary`
Media Type as defined in [RFC2046] (TNF=2)	"opaque"	The IANA media type used in the NDEF record	`ArrayBuffer`
NFC Forum External Type (TNF=4) with type other than `urn:nfc:ext:w3.org:webnfc*`	"opaque"	"application/octet-stream"	`ArrayBuffer`
Any other NDEF record type	"opaque"	"application/octet-stream"	`ArrayBuffer`

The Web NFC records MUST NOT be exposed to client browsing contexts.

9. Extensions to the Navigator interface

The HTML document defines a Navigator interface [HTML] which this specification extends.

partial interface Navigator {
    readonly    attribute NFC nfc;
};

9.1 The nfc attribute

On getting the nfc attribute, the UA MUST return the NFC object, which provides NFC related functionality.

10. The NFC interface

The NFC object provides a way for the browsing context to use NFC functionality. It allows for pushing Web NFC messages to NFC tags or NFC peers within range, and to set up and cancel NFC watches to handle incoming Web NFC messages either from an NFC tag or an NFC peer.

typedef (DOMString or ArrayBuffer or NFCMessage) NFCPushMessage;

interface NFC {
    Promise<void> push(NFCPushMessage message, optional NFCPushOptions options);
    Promise<void> cancelPush(optional NFCPushTarget target = "any");
    Promise<long> watch(MessageCallback callback, optional NFCWatchOptions options);
    Promise<void> cancelWatch(optional long id);
};

callback MessageCallback = void (NFCMessage message);

Note

In later versions cancelPush() and cancelWatch() may be obsoleted by cancelable Promises used with push() and watch(), respectively.

10.1 Internal slots of NFC

The NFC object is created with the internal slots described in the following table:

Internal Slot	Description (non-normative)
[[suspended]]	A boolean flag indicating whether NFC functionality is suspended or not, initially `false`.
[[watchList]]	A list of NFC watches initially set to empty list.

10.2 Handling NFC adapters

Implementations MAY use multiple NFC adapters according to the algorithmic steps described in this specification. The NFC object represents all NFC hardware devices that can read and write NFC content.

10.3 Handling Window visibility and focus

Each Window object connected to the script execution environment has a separate NFC instance. The visibility and focus state of the Window object determines the suspended state of the associated NFC instance.

The term suspended in this specification refers to NFC operations being suspended, i.e. no NFC content is pushed, and no received NFC content is presented via watches while suspended. However, platform level timers for the NFC.push() method continue running, and if they expire, the event should be recorded and handled when execution next resumes, i.e. when the focus event is fired on the Window object.

When the Window object associated with the Document using the Web NFC API becomes visible and in focus, then run the following steps:

Set NFC@[[suspended]] to false.

When the Window object associated with the Document using the Web NFC API loses focus, then run the following steps:

Set NFC@[[suspended]] to true.

10.4 Releasing NFC

If a user agent is to make disappear an NFC object nfc, run the following NFC release steps, given nfc:

Set nfc@[[suspended]] to true.
Run the nfc.cancelPush() steps with "tag" as parameter.
Run the nfc.cancelPush() steps with "peer" as parameter.
Stop the dispatch NFC content steps.
Clear nfc@[[watchList]].
Release the NFC resources associated with nfc on the underlying platform.

The UA should run the NFC release steps, given nfc, as additional steps to the unloading document cleanup steps.

10.5 The NFCPushOptions dictionary

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

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

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

The NFCPushOptions.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 Web NFC message can be set for pushing.

When the value of the NFCPushOptions.ignoreRead property is true, the push algorithm will skip invoking the receiving and parsing steps for an NFC tag.

10.6 The NFCWatchOptions dictionary

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

enum NFCWatchMode {
    "web-nfc-only",
    "any"
};

dictionary NFCWatchOptions {
    USVString      url = "";
    NFCRecordType? recordType;
    USVString      mediaType = "";
    NFCWatchMode   mode = "web-nfc-only";
};

The NFCWatchOptions.url property denotes the URL pattern which is used for matching the Web NFC Id of Web NFC messages which are being read. The default value "" means that no matching happens.

The NFCWatchOptions.recordType property denotes the string value which is used for matching the type property of each NFCRecord object in a Web NFC message. The default value "" means that no matching happens.

The NFCWatchOptions.mediaType property denotes the match pattern which is used for matching the type property of each NFCRecord object in a Web NFC message. The default value "" means that no matching happens.

The NFCWatchOptions.mode property denotes the NFCWatchMode value telling whether only Web NFC content or any NFC content will be watched. The "web-nfc-only" value means that only those NDEF messages are exposed which contain a Web NFC record, i.e. which are meant for web pages. The "any" value means that all NDEF messages are exposed.

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

var watchOptions = {
  url: "https://www.w3.org/*",  // any path from the domain is accepted
  recordType: "json",
  mediaType: "application/*+json"  // any JSON-based IANA media type
}

Example 10: Filter which only accept binary content from a given path but any domain

var watchOptions = {
  url: "*://*/info/restaurant/daily-menu/",  // accepted from any domain
  recordType: "opaque",
  mediaType: "application/octet-stream"
}

10.7 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 Web NFC 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, or a timeout happens, or the push is canceled by the cancelPush() method.

10.7.1 The push() method

The NFC.push(message, options) method, when invoked, MUST run the push a message algorithm:

Return a new Promise promise, and then continue running this algorithm in parallel.
If any exception occurs while running these steps, reject promise with that exception and abort these steps.
If the incumbent settings object is not a secure context, reject promise with "SecurityError" and abort these steps.
Note
Browsers may ignore this rule for development purposes only.
An implementation MAY reject promise with "NotSupportedError" 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.
Let target be options.target.
Let timeout be options.timeout.
If the type of the message parameter is not DOMString or ArrayBuffer, and it is not an instance of NFCPushMessage, reject promise with "SyntaxError", and abort these steps.
If the message parameter is instance of NFCPushMessage, and message.data is an empty sequence, reject promise with "SyntaxError" and abort these steps.
If timeout value is not valid or it is not supported by the UA, reject promise with "SyntaxError" and abort these steps.
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 promise with that exception and abort these steps.
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.

If there are any existing instance of this algorithm running whose target is equal to slot, abort that instance of this algorithm by rejecting its promise with "AbortError".
Note
In other words, the current invocation of push() rejects and replaces existing running invocations handling the same slot. At any given moment there may be maximum two instances of this algorithm running: one targeting NFC tags, and another targeting NFC peers.

Note
Implementations are expected to clean up state on aborting these steps, e.g. stop the related timer, clear the related push message, as well as release any resources bound to NFC functionality, so that new invocations of this algorithm do not depend on previous invocations.
Associate output with slot.

If timeout value is not equal to Infinity, start a timer timer with the timeout value set to timeout.
Wait until one of the following events happens:
- If timer expires, reject promise with "TimeoutError" and abort these steps.
- If the cancelPush() method is called while timer is active with target or "any", then reject promise with "AbortError" and abort these steps, as described in the cancelPush() steps.
- If an NFC device device comes within communication range, 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"
  - this@[[suspended]] is false.
  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.ignoreRead is not equal to true, run the receiving steps.
    - If the Web NFC message origin of the read NFC content is null, or it is different than the ASCII serialized origin of the incumbent settings object, and the obtain push permission steps return false, then reject promise with "SecurityError" 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 promise with "NetworkError" 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 promise.

10.7.1.1 Obtaining push permission

To obtain push permission, run these steps:

If there is a prearranged trust relationship, return true.
Run the query permission status steps for the Web NFC permission name until completion.
- 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.
- 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, store the result in the permission store, and on success return true.
Return false.

10.7.1.2 Creating Web NFC message

To create Web NFC message given a message run 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 NFCRecord record in the sequence message.data, run the following steps, or make sure that the underlying platform provides equivalent values to ndef:
1. If record.recordType is undefined, then:
  1. If record.data is instance of ArrayBuffer, then set record.mediaType to "application/octet-stream" and record.recordType to "opaque".
  2. Otherwise, if the type of record.data is "object", then set record.mediaType to "application/json" and record.recordType to "json".
  3. Otherwise, if the type of record.data is "number" or "string", then set record.mediaType to "plain/text" and record.recordType to "text".
  4. Otherwise reject promise with "SyntaxError" and abort these steps.
2. If record.recordType is "empty", then Let ndef be the result of passing record to map empty record to NDEF. If this throws an exception, reject promise with that exception and abort these steps.
3. Otherwise, if record.recordType is "text", then let ndef be the result of passing record to map text to NDEF. If this throws an exception, reject promise with that exception and abort these steps.
4. Otherwise, if record.recordType is "url", then let ndef the be result of passing record to map a URL to NDEF. If this throws an exception, reject promise with that exception and abort these steps.
5. Otherwise, if record.recordType is "json", then let ndef the be result of passing record to map a JSON object to NDEF. If this throws an exception, reject promise with that exception and abort these steps.
6. Otherwise, if record.recordType is "opaque", then let ndef the be result of passing record to map binary data to NDEF. If this throws an exception, reject promise with that exception and abort these steps.
7. Add ndef to output.
Let webnfc be the result of invoking create a Web NFC record given message.url. If this throws an exception, reject promise with that exception and abort these steps.
Add webnfc to output.
Note
Implementations may choose the location of the Web NFC record within the NDEF message.

10.7.1.3 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.TNF field to 0 (NFC Empty Type record).
Set ndef.TYPE_LENGTH, ndef.ID_LENGTH and ndef.PAYLOAD_LENGTH fields to 0, and omit the associated fields from the NDEF record: ndef.TYPE, ndef.ID, ndef.PAYLOAD.
Return ndef.

10.7.1.4 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 an NDEF Well Known Type Text record. Other options would be to use the value "opaque" with an explicit IANA media type text type, which allows for better differentiation, e.g. when using "text/xml", or "text/vcard".

If record.data is not a string or number, throw a "SyntaxError" exception and abort these steps.
If record.mediaType is not a string or starts with "text/", then throw a "SyntaxError" exception and abort these steps. In addition, UAs MAY check that record.mediaType is an IANA registered media type for text. If not, then the UA MAY throw a "SyntaxError" exception and abort these steps.
Let language be "en". If record.mediaType includes a lang= parameter, detailing the language encoding (e.g. "text/plain; lang=fr"), then set language to the language code extracted from record.mediaType. If language is not one of the language codes listed in the IANA language registry (or [ISO-639.2]), then UAs MAY throw a "SyntaxError" exception and abort these steps.
Note
Note that lang= is not standard parameter to IANA media types, but it is used in this specification in order to maintain compatibility with [NFC-STANDARDS].
Let ndef be the notation for the NDEF record to be created by the UA.
Set the ndef.TNF field to 1 (NFC Well Known Type).
Set the def.TYPE field to "T" (value 0x54 following NFC binary encoding).
Set the ndef.PAYLOAD field to record.data encoded according to the [NFC-STANDARDS], NFC Forum Text Record Type Definition specification:
1. The first octet is a status byte containing bit flags.
  1. If record.mediaType contains the parameter "charset=UTF-8" (e.g. "text/plain; charset=UTF-8;"), then set bit 7 (MSB) to 0 (UTF-8 encoding), otherwise to 1 (UTF-16 encoding).
  2. Set bit 6 to 0.
  3. Set bits 5 to 0 to the length of the language string.
2. Set the consecutive octets of ndef.PAYLOAD to the value of language encoded as US-ASCII.
3. Set the consecutive payload octets to record.data in the encoding set by the MSB bit of the first payload octet (by default UTF-16, or UTF-8 on special request).
Return ndef.

10.7.1.5 Mapping URL to NDEF

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

If record.data is not a string, throw a "SyntaxError" exception and abort these steps.
Let ndef be the notation for the NDEF record to be created by the UA.
Set the ndef.TNF field to 1 (Well Known Type).
Set the ndef.TYPE field to "U" (0x55 following NFC binary encoding).
Set the ndef.PAYLOAD field to record.data encoded according to the [NFC-STANDARDS], NFC Forum URI Record Type Definition specification: set the first octet according to the applicable scheme abbreviation, and set the rest of the payload bytes to record.data in UTF-8 encoding.
Return ndef.

10.7.1.6 Mapping JSON to NDEF

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

Let data be the result of serializing record.data and if that throws, throw a "TypeError" exception and abort these steps.
If record.mediaType doesn't match "application/json", or any other IANA media type for JSON (starting with "application/" and ending with "+json"), throw a "SyntaxError" exception and abort these steps.
Let ndef be the notation for the NDEF record to be created by the UA.
Set the ndef.TNF field to 2 (Media Type).
Set the ndef.TYPE field to record.mediaType.
Set the ndef.PAYLOAD field to data according to the [NFC-STANDARDS], i.e. as an opaque octet stream.
Return ndef.

10.7.1.7 Mapping binary data to NDEF

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

If record.data is not of instance of ArrayBuffer, reject promise with "SyntaxError" and abort these steps.
The UA MAY check if record.mediaType is a valid IANA registered type. If not, then MAY throw a "SyntaxError" exception and abort these steps.
Let ndef be the notation for the NDEF record to be created by the UA.
Set the ndef.TNF field to 2 (Media Type).
Set the ndef.TYPE field to record.mediaType.
Set the ndef.PAYLOAD field to record.data according to the [NFC-STANDARDS], i.e. as an opaque octet stream.
Return ndef.

10.7.1.8 Creating a Web NFC record

To create a Web NFC record given url, run these steps:

Let ndef be the notation for the NDEF record to be created by the UA.
Set ndef.TNF to 4 (NDEF External Type).
Set ndef.TYPE to "urn:nfc:ext:w3.org:webnfc".
Let payload be the result of invoking create a Web NFC Id given url. If this throws an exception, re-throw it.
Set ndef.PAYLOAD to the URL path of the browsing context, encoded as UTF-16. This is going to be used by NFC watch filters.
Note
In future versions a list of "allowed-origins" may be supported. It is still up for discussions due to security issues. See the Security and Privacy document.
Return ndef.

10.7.1.9 Creating a Web NFC Id

To create a Web NFC Id given url, run these steps:

Let id be the ASCII serialized origin of the browsing context, appended with url.
If id is a not a valid URL, throw a "SyntaxError" exception and abort these steps.
Note
This means url should be a valid URL path.
Return id, encoded in UTF-16.

10.7.2 The cancelPush method

The NFC.cancelPush(target) method, when invoked, MUST run cancel push algorithm:

Return a new Promise promise and then continue running this algorithm in parallel.
If the incumbent settings object is not a secure context, reject promise with "SecurityError" and abort these steps.
Note
Browsers may ignore this rule for development purposes only.
If there is an instance of the NFC.push() algorithm running with its options.target equal to target or "any", then
1. Stop the instance's timer if it is active.
2. If the instance has already initiated NFC data transfer, reject promise with "NoModificationAllowedError" and abort these steps.
3. Reject the instance's pending promise with "AbortError" and abort the steps of the instance.
Resolve promise.

Note

The cancelPush() method does not interrupt ongoing transfers, it only cancels pushing before an NFC device comes in range.

10.8 Watching for content

In order to receive NFC content, the client needs to call the NFC.watch() to opt into content of interest.

10.8.1 Match patterns

A match pattern is defined by the following ABNF:

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

A match pattern is a glob used for matching IANA media 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.8.2 URL patterns

A URL pattern is a URL which may contain the '*' wildcard character. It consists of a scheme, a host and (optionally) a path, defined by the following ABNF:

          url-pattern = scheme "://" host path
          scheme      = "*" / "https"
          host        = "*" / "*." <VCHAR except "/" and "*">
          path        = "/" <VCHAR>

Most characters match themselves, however '*' (wildcard) matches a sequence of visible characters. A URL pattern that doesn't conform to the above ABNF is a non-match.

Note

Though '*' matches a sequence of characters, only URLs with scheme "https" are accepted in the algorithms taking a URL pattern.

For example, '*://*.mydomain.com/*' will match 'https://services.mydomain.com/myservice1/myapp2/' and 'https://info.mydomain.com/general/'.

10.8.3 The watch() method

This method enables listening to incoming NDEF messages. The NFC content to which clients listen can be filtered based on its data type, and based on the URL path of the browsing context which has been saved to the Web NFC record of the NFC content. The latter is matched against URL patterns used in NFC watches.

An NFC watch is referring to a NFCWatchOptions filter saved together with the NFC instance it belongs to, and a locally unique identifier which is used for cancellation. The section Receiving and parsing content uses NFC watches to match incoming NFC content.

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

When the NFC.watch(options, callback) method is invoked, the UA MUST run the following NFC watch algorithm:

Let promise be a new Promise object.
Return promise and continue the following steps in parallel.
If any exception occurs while running these steps, reject promise with that exception and abort these steps.
If the incumbent settings object is not a secure context, reject promise with "SecurityError" and abort these steps.
Note
Browsers may ignore this rule for development purposes only.
If there is no support for the functionality of receiving data from an NFC peer or NFC tag in proximity range, reject promise with "NotSupportedError" and abort these steps.
If the obtain watch permission steps return false, then reject promise with "SecurityError" and abort these steps.
If this is the first watch being set up, then make a request to all NFC adapters to listen to NDEF messages.
If the request fails, reject promise with "NotSupportedError" and abort these steps.
Let watchId be a number that will identify this NFC watch.
Add watchId, options, and callback together as an NFC watch to this@[[watchList]].
Resolve promise with watchId.
If the browsing context loses focus (e.g. the user navigated to another page), then the registered watches still SHOULD continue to exist, but SHOULD become paused, i.e. the UA SHOULD NOT check and use them until the focus is regained.

To obtain watch 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 watch() 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. In addition, if "any" NFCWatchMode is used, then also include in this information that the origin is requesting to read not only NFC content meant for web pages, but any NFC content.
Return true.

10.8.4 The cancelWatch() method

When the NFC.cancelWatch(id) method is invoked, the UA MUST return a Promise promise and run the following steps in parallel.

If the incumbent settings object is not a secure context, reject promise with "SecurityError" and abort these steps.
Note
Browsers may ignore this rule for development purposes only.
If the parameter id is undefined, then remove all watches and filters set by successive calls of the NFC watch() method on all NFC adapters.
Otherwise, if the parameter id matches the local identifier of one of the previously set up watches, remove the corresponding watch.
Otherwise, reject promise with "NotFoundError" and abort these steps.
If there are no more watches, then make a request to stop listening to NDEF messages on all NFC adapters.
Resolve promise.

10.9 Receiving and parsing content

If there are any NFC watches set up in NFC@[[watchList]], then UAs MUST listen to NDEF messages, according to step 7 of the NFC watch algorithm.

10.9.1 The NDEF parsing algorithm

When the UA is to receive an NDEF message it MUST run the following algorithm:

Note

The UA SHOULD represent an unformatted NFC tag as an NDEF message containing a single empty NDEF record.

If NFC@[[suspended]] is true, abort these steps.
Let message be a new NFCMessage object, with message.url set to null and message.data set to empty sequence.
Let input be the notation for the NDEF message which has been received.
For each NDEF record which is part of input, run the following sub-steps for parsing NDEF record:
1. Let ndef be the notation for the current NDEF record. The fields of ndef are described by the [NFC-STANDARDS].
2. Let record be a new NFCRecord object.
3. If ndef.TNF is 0 (NFC Empty Record), then set record.recordType to "empty" and set record.mediaType to "".
4. If ndef.TNF is 1 (NFC Well Known Type Record), and ndef.TYPE is "T" (value 0x54 following NFC binary encoding), then run the following sub-steps for parsing NDEF Text record, or ensure that the underlying platform provides equivalent values to the record object properties:
  1. Set record.recordType to "text".
  2. Set record.mediaType to "text/plain".
  3. Read the first octet of ndef.PAYLOAD. Let offset be the value given by bits 5 to 0 of the first payload octet.
  4. Let language be the string defined by the consecutive offset number of octets, converted from US-ASCII encoding. Append ";lang=" and then the value of language to record.mediaType.
  5. Set record.data to the string created from the consecutive ndef.PAYLOAD octets, converted to UTF-16 encoding.
5. If ndef.TNF is 1 (NFC Well Known Type Record), and ndef.TYPE is "U" (value 0x55 in NFC binary encoding), then run the following sub-steps for parsing NDEF URL record, or make sure that the underlying platform provides equivalent values to the record object properties:
  1. Set record.recordType to "url".
  2. Set record.mediaType to "text/plain".
  3. Let scheme be the value of the first octet of ndef.PAYLOAD.
  4. If scheme is not 0, then set record.data to the string obtained from mapping the value of scheme to the URL scheme as specified in the [NFC-STANDARDS] URI Record Type Definition specification, Section 3.2.2.
  5. Set record.data to the UTF-16 string converted from the octets of ndef.PAYLOAD except the first octet.
6. If ndef.TNF is 3 (NFC Absolute URI Type record), then set record.recordType to "url", set record.mediaType to "text/plain" and set record.data to the string converted from ndef.PAYLOAD.
7. If ndef.TNF is 2 (NFC Media Type record), then run the following sub-steps for parsing NDEF Media record, or make sure that the underlying platform provides equivalent values to the record object properties:
  1. If ndef.TYPE matches the match pattern "application/*json", then
    1. Set record.recordType to "json".
    2. Set record.mediaType to ndef.TYPE.
    3. Let payload be ndef.PAYLOAD converted to UTF-16, and set record.data to the result of parsing payload. If parsing throws an error, skip to the next NDEF record.
  2. Otherwise,
    1. Set record.recordType to "opaque".
    2. Set record.mediaType to ndef.TYPE.
    3. Set record.data to a new ArrayBuffer object constructed from the octets of ndef.PAYLOAD.
8. If ndef.TNF is 4 (NFC External Type record), and ndef.TYPE is urn:nfc:ext:w3.org:webnfc, then set message.url to the value decoded from ndef.PAYLOAD in UTF-16.
9. Otherwise, if ndef.TNF is 4 (NFC External Type record), or 5 (NFC Unknown Type record) then run the following sub-steps, or make sure that the underlying platform provides equivalent values to the record object properties:
  1. Set record.recordType to "opaque".
  2. If ndef.TYPE is defined, then set record.mediaType to that string value, otherwise to "application/octet-stream.
  3. Set record.data to a new ArrayBuffer object constructed from the octets of ndef.PAYLOAD.
10. Otherwise, skip to the next NDEF record in input.
11. Add record to message.data.
If NFC@[[suspended]] is false and message.data is not empty, run the dispatch NFC content steps given message.

10.9.2 Dispatching NFC content

To dispatch NFC content given a message of type NFCMessage run these steps:

For each NFC watch watch that has been registered using the watch() method in this@[[watchList]], run the following sub-steps:
1. Let options be the NFCWatchOptions saved with watch, and let callback be the registered callback function.
2. If options.mode is "web-nfc-only" and message.url is null, skip to the next NFC watch.
3. Otherwise, if options.mode is "any", set options.url to "".
4. If the URL pattern options.url is not "" and it does not match message.url, skip to the next NFC watch.
5. If options.recordType is not "" and it is not equal to any record.recordType where record is an element of message, skip to the next NFC watch.
6. If options.mediaType is not "" and it is not equal to any record.mediaType where record is an element of message, skip to the next NFC watch.
7. Queue a task using the Web NFC task source to invoke the MessageCallbackvar>callback with message as its argument.

B. Open issues

The following problems are being discussed and need most attention:

This version addresses the issues above, and also other issues.

C. Acknowledgements

The editors would like to thank Jeffrey Yasskin, Anne van Kesteren, Anssi Kostiainen, Alexander Shalamov, Domenic Denicola, Jonas Sicking, Don Coleman, Salvatore Iovene and Rijubrata Bhaumik for their contributions to this document. Special thanks goes to the former editors Luc Yriarte and Samuel Ortiz for their initial work on exposing NFC to the Web Platform, and for their supports for our new approach.

D.1 Normative references

[DOM4]: Anne van Kesteren; Aryeh Gregor; Ms2ger; Alex Russell; Robin Berjon. W3C DOM4. 6 October 2015. W3C Proposed Recommendation. URL: http://www.w3.org/TR/dom/
[ECMASCRIPT]: ECMAScript Language Specification. URL: https://tc39.github.io/ecma262/
[ENCODING]: Anne van Kesteren; Joshua Bell; Addison Phillips. Encoding. 20 October 2015. W3C Candidate Recommendation. URL: http://www.w3.org/TR/encoding/
[HTML5]: Ian Hickson; Robin Berjon; Steve Faulkner; Travis Leithead; Erika Doyle Navara; Edward O'Connor; Silvia Pfeiffer. HTML5. 28 October 2014. W3C Recommendation. URL: http://www.w3.org/TR/html5/
[NFC-STANDARDS]: NFC Forum Technical Specifications. 24 July 2006. URL: http://members.nfc-forum.org/specs/spec_list/
[RFC2119]: S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Best Current Practice. URL: https://tools.ietf.org/html/rfc2119
[URL]: Anne van Kesteren; Sam Ruby. URL. 9 December 2014. W3C Working Draft. URL: http://www.w3.org/TR/url-1/
[WEBAPPSEC]: Secure Contexts. 17 July 2015. URL: https://w3c.github.io/webappsec/specs/powerfulfeatures
[WEBIDL]: Cameron McCormack; Boris Zbarsky. WebIDL Level 1. 4 August 2015. W3C Working Draft. URL: http://www.w3.org/TR/WebIDL-1/

D.2 Informative references

[ISO-639.2]: Codes for the Representation of Names of Languages. 18 March 2014. URL: https://www.loc.gov/standards/iso639-2/php/code_list.php
[RFC2046]: N. Freed; N. Borenstein. Multipurpose Internet Mail Extensions (MIME) Part Two: Media Types. November 1996. Draft Standard. URL: https://tools.ietf.org/html/rfc2046
[RFC3986]: T. Berners-Lee; R. Fielding; L. Masinter. Uniform Resource Identifier (URI): Generic Syntax. January 2005. Internet Standard. URL: https://tools.ietf.org/html/rfc3986
[RFC5234]: D. Crocker, Ed.; P. Overell. Augmented BNF for Syntax Specifications: ABNF. January 2008. Internet Standard. URL: https://tools.ietf.org/html/rfc5234
[permissions]: Mounir Lamouri; Marcos Caceres. The Permissions API. 7 April 2015. W3C Working Draft. URL: http://www.w3.org/TR/permissions/

Abstract

Status of This Document

Table of Contents

1. Conformance

2. Terminology and conventions

2.1 Security related terms

2.2 NFC specific terms

3. Introduction

4. Examples

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. Security and Privacy

7.1 Chain of trust

7.2 Threats

7.3 Permissions and user prompts

7.4 Security policies

8. Data Representation

8.1 The NFCRecord dictionary

8.2 The NFCMessage dictionary

8.3 Data mapping

9. Extensions to the Navigator interface

9.1 The nfc attribute

10. The NFC interface

10.1 Internal slots of NFC

10.2 Handling NFC adapters

10.3 Handling Window visibility and focus

10.4 Releasing NFC

10.5 The NFCPushOptions dictionary

10.6 The NFCWatchOptions dictionary

10.7 Writing or pushing content

10.7.1 The push() method

10.7.1.1 Obtaining push permission

10.7.1.2 Creating Web NFC message

10.7.1.3 Mapping empty record to NDEF

10.7.1.4 Mapping string to NDEF

10.7.1.5 Mapping URL to NDEF

10.7.1.6 Mapping JSON to NDEF

10.7.1.7 Mapping binary data to NDEF

10.7.1.8 Creating a Web NFC record

10.7.1.9 Creating a Web NFC Id

10.7.2 The cancelPush method

10.8 Watching for content

10.8.1 Match patterns

10.8.2 URL patterns

10.8.3 The watch() method

10.8.4 The cancelWatch() method

10.9 Receiving and parsing content

10.9.1 The NDEF parsing algorithm

10.9.2 Dispatching NFC content

A. Changes

B. Open issues

C. Acknowledgements

D. References

D.1 Normative references

D.2 Informative references