- From: Wayne Carr <wayne.carr@linux.intel.com>
- Date: Thu, 12 Mar 2015 09:27:06 -0700
- To: public-web-nfc-contrib@w3.org
- Message-ID: <5501BE5A.6000607@linux.intel.com>
This will separately be put in this Community Group's GitHub
repository. It's being posted here just to be clear that this is a
contribution this to the Web NFC Community Group.
Web NFC API
Editors:
Kenneth Rohde Christiansen, Intel <http://www.intel.com/>
Zoltan Kis, Intel <http://www.intel.com/>
------------------------------------------------------------------------
Abstract
Near Field Communication (NFC) enables wireless communication between
two devices at close proximity, usually less than a few centimeters. NFC
is an international standard (ISO/IEC 18092) defining an interface and
protocol for simple wireless interconnection of closely coupled devices
operating at 13.56 MHz (see http://www.nfc-forum.org/specs/spec_list/
<http://www.nfc-forum.org/specs/spec_list/>).
This specification defines an API to manage selected NFC use-cases from
Web applications and pages, and to enable new use-cases based on NFC
technology.
The generic use-cases covered in this specification are:
* Enabling reading and writing simple consumer NFC tag
<http://w3c.github.io/nfc/#dfn-nfc-tag>s
* Allowing pushing data to another NFC peer
<http://w3c.github.io/nfc/#dfn-nfc-peer> device when it is within
range.
Table of Contents
* 1. Conformance <http://w3c.github.io/nfc/#conformance>
* 2. Terminology <http://w3c.github.io/nfc/#terminology>
* 3. Introduction <http://w3c.github.io/nfc/#introduction>
o 3.1 Use Cases <http://w3c.github.io/nfc/#use-cases>
+ 3.1.1 Reading NFC tags
<http://w3c.github.io/nfc/#reading-nfc-tags>
+ 3.1.2 Writing NFC tags
<http://w3c.github.io/nfc/#writing-nfc-tags>
+ 3.1.3 Sending data to NFC peers
<http://w3c.github.io/nfc/#sending-data-to-nfc-peers>
+ 3.1.4 Handover to another wireless connection type
<http://w3c.github.io/nfc/#handover-to-another-wireless-connection-type>
+ 3.1.5 Payment scenarios
<http://w3c.github.io/nfc/#payment-scenarios>
o 3.2 Features <http://w3c.github.io/nfc/#features>
o 3.3 Technical requirements
<http://w3c.github.io/nfc/#technical-requirements>
o 3.4 Mapping data types to NDEF messages
<http://w3c.github.io/nfc/#mapping-data-types-to-ndef-messages>
* 4. Examples <http://w3c.github.io/nfc/#examples>
* 5. Security and Privacy Considerations
<http://w3c.github.io/nfc/#security-and-privacy-considerations>
* 6. Extensions to the *Navigator* interface
<http://w3c.github.io/nfc/#extensions-to-the-navigator-interface>
o 6.1 The *nfc* attribute
<http://w3c.github.io/nfc/#the-nfc-attribute>
* 7. The *NFC* interface <http://w3c.github.io/nfc/#the-nfc-interface>
* 8. The *NfcAdapter* interface
<http://w3c.github.io/nfc/#the-nfcadapter-interface>
o 8.1 Events used with the *NfcAdapter* interface
<http://w3c.github.io/nfc/#events-used-with-the-nfcadapter-interface>
+ 8.1.1 The *read* event
<http://w3c.github.io/nfc/#the-read-event>
+ 8.1.2 The *push* event
<http://w3c.github.io/nfc/#the-push-event>
+ 8.1.3 The *NdefPushEvent* interface
<http://w3c.github.io/nfc/#the-ndefpushevent-interface>
+ 8.1.4 The *NdefReadEvent* interface
<http://w3c.github.io/nfc/#the-ndefreadevent-interface>
+ 8.1.5 The *NdefRecordData* interface
<http://w3c.github.io/nfc/#the-ndefrecorddata-interface>
o 8.2 The *watch()* method
<http://w3c.github.io/nfc/#the-watch-method>
+ 8.2.1 The *WatchOptions* dictionary
<http://w3c.github.io/nfc/#the-watchoptions-dictionary>
+ 8.2.2 The *within-scope* algorithm
<http://w3c.github.io/nfc/#the-within-scope-algorithm>
o 8.3 The *clearWatch*() method
<http://w3c.github.io/nfc/#the-clearwatch-method>
o 8.4 The *write*() method
<http://w3c.github.io/nfc/#the-write-method>
o 8.5 The *setPushMessage()* method
<http://w3c.github.io/nfc/#the-setpushmessage-method>
o 8.6 The *clearPushMessage*() method
<http://w3c.github.io/nfc/#the-clearpushmessage-method>
* A. Changes <http://w3c.github.io/nfc/#Changes>
* B. Acknowledgements <http://w3c.github.io/nfc/#acknowledgements>
* C. References <http://w3c.github.io/nfc/#references>
o C.1 Normative references
<http://w3c.github.io/nfc/#normative-references>
o C.2 Informative references
<http://w3c.github.io/nfc/#informative-references>
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 /MUST/, /MUST NOT/, and /SHOULD/ are to be interpreted as
described in [RFC2119 <http://w3c.github.io/nfc/#bib-RFC2119>].
This specification defines conformance criteria that apply to a single
product: the user agent that implements the interfaces it contains.
Implementations that use ECMAScript to implement the APIs defined in
this specification /MUST/ implement them in a manner consistent with the
ECMAScript Bindings defined in the Web IDL specification [WEBIDL
<http://w3c.github.io/nfc/#bib-WEBIDL>], as this specification uses that
specification and terminology.
2. Terminology
The |EventHandler|
<http://dev.w3.org/html5/spec/webappapis.html#eventhandler> interface
represents a callback used for event handlers as defined in [HTML5
<http://w3c.github.io/nfc/#bib-HTML5>].
The concepts queue a task
<http://dev.w3.org/html5/spec/webappapis.html#queue-a-task> and fire a
simple event
<http://dev.w3.org/html5/spec/webappapis.html#fire-a-simple-event> are
defined in [HTML5 <http://w3c.github.io/nfc/#bib-HTML5>].
The terms event handler
<http://dev.w3.org/html5/spec/webappapis.html#event-handlers> and event
handler event types
<http://dev.w3.org/html5/spec/webappapis.html#event-handler-event-type>
are defined in [HTML5 <http://w3c.github.io/nfc/#bib-HTML5>].
|Promise|
<http://people.mozilla.org/%7Ejorendorff/es6-draft.html#sec-promise-objects>,
and |JSON.parse|
<https://people.mozilla.org/%7Ejorendorff/es6-draft.html#sec-json.parse>
are defined in [ECMASCRIPT <http://w3c.github.io/nfc/#bib-ECMASCRIPT>].
The algorithms utf-8 encode
<http://www.w3.org/TR/encoding/#utf-8-encode>, and utf-8 decode
<http://www.w3.org/TR/encoding/#utf-8-decode> are defined in [ENCODING
<http://w3c.github.io/nfc/#bib-ENCODING>].
EventInit <http://www.w3.org/TR/dom/#eventinit>, DOMException
<http://www.w3.org/TR/dom/#domexception>, AbortError
<http://www.w3.org/TR/dom/#aborterror>, SyntaxError
<http://www.w3.org/TR/dom/#syntaxerror>, NotSupportedError
<http://www.w3.org/TR/dom/#notsupportederror>, NotFoundError
<http://www.w3.org/TR/dom/#notfounderror>, and SecurityError
<http://www.w3.org/TR/dom/#securityerror> are defined in [DOM4
<http://w3c.github.io/nfc/#bib-DOM4>].
The term web app refers to a Web application, i.e. an application
implemented using Web technologies, and executing within the context of
a Web user agent <http://w3c.github.io/nfc/#dfn-user-agent>, e.g. a Web
browser or other Web-based runtime environments.
The term expressed permission refers to an act by the user, e.g. via
user interface or host device platform features, via which the user
approves the permission of a web app
<http://w3c.github.io/nfc/#dfn-web-app> to access the Web NFC API.
|Blob <http://www.w3.org/TR/FileAPI/#blob> | is defined in [FILEAPI
<http://w3c.github.io/nfc/#bib-FILEAPI>].
|DOMString| <http://heycam.github.io/webidl/#idl-DOMString>,
|ArrayBuffer| <http://heycam.github.io/webidl/#idl-ArrayBuffer>,
|BufferSource| <http://heycam.github.io/webidl/#common-BufferSource> and
|any| <http://www.w3.org/TR/WebIDL/#idl-any> are defined in [WEBIDL
<http://w3c.github.io/nfc/#bib-WEBIDL>].
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 http://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 contain multiple NFC adapters.
An NFC tag is a passive, unpowered NFC device. The NFC tag
<http://w3c.github.io/nfc/#dfn-nfc-tag> is powered by magnetic induction
when an active NFC device is in proximity range. A NFC tag
<http://w3c.github.io/nfc/#dfn-nfc-tag> contains a single NDEF message
<http://w3c.github.io/nfc/#dfn-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 another device, which can interact with other devices in
order to exchange data using NFC.
An NDEF message encapsulates one or more application-defined NDEF record
<http://w3c.github.io/nfc/#dfn-ndef-record>s. NDEF stands for NFC Forum
Data Exchange Format, a lightweight binary message format. NDEF messages
can be stored on a NFC tag <http://w3c.github.io/nfc/#dfn-nfc-tag> or
exchanged between NFC-enabled devices.
An NDEF record has a maximum payload of 2^32-1 bytes. The record also
contains information about the payload size, type, and an optional
identifier. NFC Forum standardized a small set of useful data types to
be used in NDEF record <http://w3c.github.io/nfc/#dfn-ndef-record>s, for
instance text, URL, media. In addition, there are record types designed
for more complex interactions, such as Smart Poster, and handover records.
Part of the NDEF record <http://w3c.github.io/nfc/#dfn-ndef-record> is
the TNF field, standing for Type Name Format. It can take binary values
representing the following 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
<http://w3c.github.io/nfc/#dfn-well-known-type> includes record types
/text/, /URI/, /Smart Poster/ (containing a URI or other data and
possible actions).
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.
The term sufficient permission in this document means that a web app
<http://w3c.github.io/nfc/#dfn-web-app> which is invoking the methods of
this API has been checked to comply with the security policies set by
the underlying platform and API implementation in the moment and context
of invoking the API method.
The term document base URL
<http://www.w3.org/TR/2011/WD-html5-20110113/urls.html#document-base-url> is
defined in [HTML5 <http://w3c.github.io/nfc/#bib-HTML5>].
The term URL scope is introduced in this document for NFC operations as
a sub-string match to the web app
<http://w3c.github.io/nfc/#dfn-web-app>'s document URL, which includes
the domain of the calling web app
<http://w3c.github.io/nfc/#dfn-web-app>. The URL scope is stored in the
identifier field of an NDEF record
<http://w3c.github.io/nfc/#dfn-ndef-record>.
3. Introduction
/This section is non-normative./
There are three groups of user scenarios for NFC:
* Hold a device close to a passive wireless tag (which could be in the
form of a plastic card) to read and write or overwrite data (in the
case the tag is not read-only).
* Hold two powered devices, e.g. phones or tablets, close to each
other in order to push data from one to the other, or to initiate a
connection using another wireless carrier such as Bluetooth or WiFi.
* Card emulation
1. With a secure element: for payments by holding your phone close
to a point-of-sales terminal, instead of swiping a payment card.
2. With host card emulation: for allowing use-cases like using a
phone as a hotel room key card.
NFC works using magnetic induction, meaning that the reader will emit a
small electric charge which then creates a magnetic field. This field
powers the passive device which turns it in to electrical impulses to
communicate data. Thus, when the devices are within range, a read is
always performed (see NFC Analog Specification and NFC Digital Protocol,
NFC Forum, 2006). The peer-to-peer connection works in a similar way, as
the device periodically switches into a so-called initiator mode in
order to scan for targets, for then to fall back into target mode. If a
target is found, the data is read the same way as for tags.
As |NFC| <http://w3c.github.io/nfc/#idl-def-NFC> is based on existing
RFID standards, many NFC chipsets support reading legacy RFIDs tags, but
many of these are only supported by single vendors and not part of the
NFC standards. Though certain devices support reading and writing to
these, it is not a goal of this specification to support proprietary
tags or support interoperability with legacy systems.
The NFC Forum has mandated the support of four different tag types to be
operable with NFC devices. The same is required on operating systems
such as Android.
1. *NFC Forum Type 1*: This tag is based on the ISO/IEC 14443-3A (also
known as NFC-A, as defined in ISO/IEC 14443-3:2011, Part 3:
Initialization and anticollision). The tags are rewritable and can
be configured to become read-only. Memory size can be between 96
bytes and 2 Kbytes. Communication speed is 106 kbit/sec.
2. *NFC Forum Type 2*: This tag is also based on the ISO/IEC 14443-3A
(NFC-A). The tags are rewritable and can be configured to become
read-only. Memory size can be between 48 bytes and 2 Kbytes.
Communication speed is 106 kbit/sec. In contrast to Type 1, Type 2
has anti-collision protection for dealing with multiple tags within
the NFC field.
3. *NFC Forum Type 3*: This tag is based on the Japanese Industrial
Standard (JIS) X 6319-4, commonly known as FeliCa. The tags are
preconfigured to be either rewritable or read-only. Memory
availability is variable, theoretical memory limit is 1MByte per
service. Communication speed is 106 kbit/sec. Like Type 2, it
supports anti-collision protection.
4. *NFC Forum Type 4* (November 2010): This tag is based on the ISO/IEC
14443 like Type 1 and 2, but it support either NFC-A or NFC-B for
communication. On top of that the tag may support the Data Exchange
Protocol (aka ISO-DEP) defined in ISO/IEC 14443 (ISO/IEC
14443-4:2008 Part 4: Transmission protocol). Like Type 3, the tags
are preconfigured to be either rewritable or read-only. Variable
memory, up to 32 KB per service. Supports three different
communication speeds 106 or 212 or 424 Kbits/s.
In addition to data types standardized for NDEF record
<http://w3c.github.io/nfc/#dfn-ndef-record>s by the NFC Forum, many
commercial products, e.g. bus cards, door openers etc, use different
card specific data and protocol extensions which require specific NFC
chips (same vendor of card and reader) in order to work.
Card emulation mode capabilities also depend on the NFC chip in the
device. For payments, a Secure Element is often needed.
3.1 Use Cases
/This section is non-normative./
A few Web NFC user scenarios are described in this
<http://w3c.github.io/nfc/use-cases.html> document. These user scenarios
can be grouped along criteria based on security, privacy and feature
categories, resulting in generic flows as follows.
3.1.1 Reading NFC tag <http://w3c.github.io/nfc/#dfn-nfc-tag>s
1. Reading arbitrary tags when no web site is open: when the user
touches a device to an NFC tag
<http://w3c.github.io/nfc/#dfn-nfc-tag> when no web site is
currently open, the user agent
<http://w3c.github.io/nfc/#dfn-user-agent> can open a website to
handle that tag. If multiple websites can handle the tag, a choice
is presented to the user to pick the preferred web site for handling
the tag. Web sites have a programmatic means to tell the user agent
<http://w3c.github.io/nfc/#dfn-user-agent> they are able and
interested to handle NFC tag
<http://w3c.github.io/nfc/#dfn-nfc-tag>s of certain type.
2. Reading arbitrary tags when a website is currently open: if the user
has a website open and that website has indicated that it's able to
read a set of tags, it might be fine to allow that website to read a
readonly tag that the user taps without presenting any permission or
security dialog to the user.
3. Reading "Web NFC" tags: if there is a mechanism which NFC tag
<http://w3c.github.io/nfc/#dfn-nfc-tag>s use to indicate which
website that they can be read by, the user can tap on the tag and we
can open the web site automatically. There is no need for the user
to have visited the web site first or to have the website open, and
the user agent <http://w3c.github.io/nfc/#dfn-user-agent> is not
required to display a dialogue asking the user which website to use.
3.1.2 Writing NFC tag <http://w3c.github.io/nfc/#dfn-nfc-tag>s
1. Writing to arbitrary writable tags: the user opens a web page which
can write an NFC tag <http://w3c.github.io/nfc/#dfn-nfc-tag>. This
use case should be restricted or de-scoped for security and privacy
reasons.
2. Writing to "Web NFC" tags: if a tag indicates that it is connected
to a given website, then user agent
<http://w3c.github.io/nfc/#dfn-user-agent>s may allow that web site
to write to the tag without any special security dialogs.
3.1.3 Sending data to NFC peer
<http://w3c.github.io/nfc/#dfn-nfc-peer>s
In general, sending 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 user agent <http://w3c.github.io/nfc/#dfn-user-agent> will dispatch
the content to a web site registered to handle the content and in case
of multiple such web sites, the one chosen by the second user.
3.1.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.
3.1.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.
3.2 Features
High level features for the Web NFC specification include the following:
1. Support devices with single or multiple NFC adapters.
2. Support communication with active (powered devices such as readers,
phones) and passive (smart cards, tags, etc) devices.
3. Allow users to act on (e.g. read, write or transceive) discovered
NFC devices (passive and active) as well as access the NDEF records
which were read in the process.
4. Allow the user to write a payload via NDEF records to compatible
devices, such as writeable tags, when they come in range.
5. [future] Allow manual connection for various technologies such as
NFC-A and NFC-F depending on secondary device.
6. [future] Allow NFC handover
<http://w3c.github.io/nfc/#dfn-nfc-handover> to Bluetooth or WiFi.
7. [future] Allow card emulation with secure element or host card
emulation.
NFC is usually deeply integrated into device platforms (e.g. Android,
Windows, etc), because end-to-end user experience implications (e.g.
users need to be presented platform specific dialogs for selecting
applications and actions). Also, privacy and security related issues
require platform specific solutions.
The various integrated technologies, wide variety of use cases, and
platform integration issues make standardization of NFC for the web a
challenge. Therefore this specification makes a few simplifications in
what use cases and data types are possible to handle by users of this API:
* Expose data types already known to web browsers as MIME types.
* Use the web security model.
* Implementations encapsulate NDEF record
<http://w3c.github.io/nfc/#dfn-ndef-record> handling and the API
exposes only data and control events.
3.3 Technical requirements
The following high level technical requirements result from the
enumerated use cases and high level features:
1. Enumerate NFC adapters.
2. Set up watchers to read for a given scope (a default scope being set
by implementations to the origin of the page).
3. Provide event for read completed as NDEF records from tag or peer
device. Expose payload as MIME type. Eventually expose binary
content of NDEF records.
4. Set a predefined payload, or full binary NDEF records that the user
can push to another device when within range. Provide event for
completed push.
5. [future] Manage manual connections for various NFC technologies.
Provide proximity events when tags and peers appear and disappears
6. [future] Set up the card content to be read by other devices for
Host Card Emulation.
7. [future] Configure a predefined handover to Bluetooth or WiFi.
3.4 Mapping data types to NDEF messages
The following types can be used when writing NFC tag
<http://w3c.github.io/nfc/#dfn-nfc-tag>s, sending data to NFC peer
<http://w3c.github.io/nfc/#dfn-nfc-peer>s, and when reading NDEF message
<http://w3c.github.io/nfc/#dfn-ndef-message>s.
typedefNdefData = DOMString or URL or Blob or JSON;
|NdefData| denotes the data types supported as NDEF record
<http://w3c.github.io/nfc/#dfn-ndef-record> payload in read and write
operations in this API.
The mapping from supported |NdefData| to NDEF record
<http://w3c.github.io/nfc/#dfn-ndef-record> types is as follows:
NdefData NDEF record type
*DOMString* NFC Forum Well Known Type (TNF
<http://w3c.github.io/nfc/#dfn-tnf>=1) with type /Text/
*URL*
* NFC Forum Well Known Type (TNF
<http://w3c.github.io/nfc/#dfn-tnf>=1) with type /URI/
* NFC Forum Well Known Type (TNF
<http://w3c.github.io/nfc/#dfn-tnf>=1) with type /Smart Poster/
* Absolute URI as defined in RFC 3986 (TNF
<http://w3c.github.io/nfc/#dfn-tnf>=3)
*JSON* Media-type as defined in RFC 2046 (TNF
<http://w3c.github.io/nfc/#dfn-tnf>=2) with associated /MIME type/
|"application/webnfc+json"|
*Blob*
* Media-type as defined in RFC 2046 (TNF
<http://w3c.github.io/nfc/#dfn-tnf>=2)
* NFC Forum External Type (TNF <http://w3c.github.io/nfc/#dfn-tnf>=4)
* Unknown (TNF <http://w3c.github.io/nfc/#dfn-tnf>=5)
* Any NDEF record <http://w3c.github.io/nfc/#dfn-ndef-record> type
that is not covered by DOMString, URL and JSON types.
4. Examples
/This section is non-normative./
This section shows how developers can make use of the various features
of this specification.
Example 1: Read and write tag
navigator.nfc.findAdapters().then(function(adapters) {
var adapter= adapters[0];
var scope= "example.com/tag/updater";
adapter.onread= (msg) => {
var timesRead= (msg.data.length> 0) ? msg.data[0].json().timesRead: 0;
if (msg.writeable)
adapter.write([{ timesRead: (timesRead+ 1) % 1000 }], scope);
else
console.log("Read-only tag; value =" + timesRead);
};
var watchOptions= {
scope: scope,
watchType: "tag-only"
};
adapter.watch(watchOptions).then(function() {
console.log("We are now watching tags via NFC");
});
}).catch(function(err) {
console.log("No NFC adapters found");
});
Example 2: Save and restore game progress with another device
navigator.nfc.findAdapters().then(function(adapters) {
var adapter= adapters[0];
var scope= "/example.com/mygame";
adapter.onread= (event) => {
console.log("Game state received from:" + event.scope);
console.log("Game state:" + event.data.json());
};
adapter.onpush= (event) => { // update values
console.log("Successfully pushed a message to:" + event.scope);
updateGameState();
}
// fetch game state and update push message
function updateGameState() {
var msg= [ { level: 3, points: 4500, lives: 3 } ];
adapter.setPushMessage(msg, scope).then(function() {
console.log("Game state updated for push");
});
};
var withOptions= {
scope: scope,
watchType: "peer-only"
};
adapter.watch(withOptions).then(function() {
console.log("We are now watching game progress via NFC");
});
});
5. Security and Privacy Considerations
User agents <http://w3c.github.io/nfc/#dfn-user-agent> /MUST NOT/
provide Web NFC API access to web app
<http://w3c.github.io/nfc/#dfn-web-app>s without the expressed
permission <http://w3c.github.io/nfc/#dfn-expressed-permission> of the
user. User agents must acquire consent for permission through a user
interface for each call to the methods of this API, unless a prearranged
trust relationship applies.
User agents may support prearranged trust relationships that do not
require such per-request user interfaces.
Note
Considering adding the following: User agents /MUST/ implement the
WebNFC API to be HTTPS-only. SSL-only support provides better protection
for the user against man-in-the-middle attacks intended to obtain push
registration data. Browsers may ignore this rule for development
purposes only.
Permissions that are preserved beyond the current browsing session must
be revocable.
6. Extensions to the *Navigator* interface
The HTML specification defines a |Navigator|
<http://www.whatwg.org/specs/web-apps/current-work/#dom-navigator>
interface [HTML] which this specification extends.
partial interfaceNavigator {
readonly attribute|NFC| <http://w3c.github.io/nfc/#idl-def-NFC> nfc <http://w3c.github.io/nfc/#widl-Navigator-nfc>;
};
6.1 The *nfc* attribute
When getting the nfc attribute, the user agent
<http://w3c.github.io/nfc/#dfn-user-agent> /MUST/ return the |NFC|
<http://w3c.github.io/nfc/#idl-def-NFC> object, which provides NFC
related functionality.
7. The *NFC* interface
interfaceNFC {
Promise<sequence<|NfcAdapter| <http://w3c.github.io/nfc/#idl-def-NfcAdapter>>> findAdapters <http://w3c.github.io/nfc/#widl-NFC-findAdapters-Promise-sequence-NfcAdapter> ();
};
Implementations might expose multiple NFC adapters. By using the
findAdapters() method, web app <http://w3c.github.io/nfc/#dfn-web-app>s
can obtain adapter objects providing NFC functionality, in a similar way
to that of service worker extensions [SERVICE-WORKERS
<http://w3c.github.io/nfc/#bib-SERVICE-WORKERS>]. When this method is
invoked, the user agent <http://w3c.github.io/nfc/#dfn-user-agent>
/MUST/ run the following steps:
1. Let promise be a new |Promise|
<http://w3c.github.io/nfc/#dfn-promise> object.
2. Return promise and continue the following steps asynchronously.
3. If there are no sufficient permission
<http://w3c.github.io/nfc/#dfn-sufficient-permission>s to use this
method, that is, to use NFC technology from the calling web app
<http://w3c.github.io/nfc/#dfn-web-app>, then reject promise with a
new |DOMException <http://w3c.github.io/nfc/#dfn-domexception>|
object whose name property is set to |"SecurityError
<http://w3c.github.io/nfc/#dfn-securityerror>"|, and terminate these
steps.
4. If there is no support for NFC adapter
<http://w3c.github.io/nfc/#dfn-nfc-adapter> handling functionality
in hardware, software, or due to physical incompatibility, then
reject promise with a new |DOMException
<http://w3c.github.io/nfc/#dfn-domexception>| object whose name
property is set to |"NotSupportedError
<http://w3c.github.io/nfc/#dfn-notsupportederror>"|, and terminate
these steps.
5. Make a request to the underlying platform to initialize NFC
functionality and enumerate available adapters. If the request
fails, then reject promise with a new |DOMException
<http://w3c.github.io/nfc/#dfn-domexception>| object whose name
property is set to |"NotSupportedError
<http://w3c.github.io/nfc/#dfn-notsupportederror>"|, and terminate
these steps.
6. If the request is successful, then resolve promise with an array of
||NfcAdapter| <http://w3c.github.io/nfc/#idl-def-NfcAdapter>|
objects. Implementations /SHOULD/ maintain a default adapter, which
/SHOULD/ be exposed as the first element in the returned array.
8. The *NfcAdapter* interface
interfaceNfcAdapter :EventHandler <http://w3c.github.io/nfc/#dfn-eventhandler> {
attributeEventHandler <http://w3c.github.io/nfc/#dfn-eventhandler> onread <http://w3c.github.io/nfc/#widl-NfcAdapter-onread>;
attributeEventHandler <http://w3c.github.io/nfc/#dfn-eventhandler> onpush <http://w3c.github.io/nfc/#widl-NfcAdapter-onpush>;
Promise<long> watch <http://w3c.github.io/nfc/#widl-NfcAdapter-watch-Promise-long--WatchOptions-options> (|WatchOptions| <http://w3c.github.io/nfc/#idl-def-WatchOptions>? options);
Promise<void> clearWatch <http://w3c.github.io/nfc/#widl-NfcAdapter-clearWatch-Promise-void--long-id> (optionallong id);
Promise<void> write <http://w3c.github.io/nfc/#widl-NfcAdapter-write-Promise-void--NdefDataArray-data-USVString-scope> ((NdefData <http://w3c.github.io/nfc/#dfn-ndefdata>)[] data,optionalUSVString scope);
Promise<void> setPushMessage <http://w3c.github.io/nfc/#widl-NfcAdapter-setPushMessage-Promise-void--NdefDataArray-data-USVString-scope> ((NdefData <http://w3c.github.io/nfc/#dfn-ndefdata>)[] data,optionalUSVString scope);
Promise<void> clearPushMessage <http://w3c.github.io/nfc/#widl-NfcAdapter-clearPushMessage-Promise-void--USVString-scope> (optionalUSVString scope);
};
The |NfcAdapter| interface handles incoming NDEF message
<http://w3c.github.io/nfc/#dfn-ndef-message>s, exposed by the
||NdefReadEvent| <http://w3c.github.io/nfc/#idl-def-NdefReadEvent>|
event, both from NFC tag <http://w3c.github.io/nfc/#dfn-nfc-tag>s and
NFC peer <http://w3c.github.io/nfc/#dfn-nfc-peer>s. By default,
listening to this event /SHOULD/ be disabled. Applications can subscribe
to NDEF message <http://w3c.github.io/nfc/#dfn-ndef-message>s
originating from a given URL scope
<http://w3c.github.io/nfc/#dfn-url-scope> by using the |watch()| method.
Applications can write to an NFC tag
<http://w3c.github.io/nfc/#dfn-nfc-tag>, and set up push messages to NFC
peer <http://w3c.github.io/nfc/#dfn-nfc-peer>s.
8.1 Events used with the *NfcAdapter* interface
The following are the event handlers implemented by the ||NfcAdapter|
<http://w3c.github.io/nfc/#idl-def-NfcAdapter>| interface.
event handler event name event type
|onread| |read| ||NdefReadEvent|
<http://w3c.github.io/nfc/#idl-def-NdefReadEvent>|
|onpush| |push| ||NdefPushEvent|
<http://w3c.github.io/nfc/#idl-def-NdefPushEvent>|
8.1.1 The *read* event
The |read| event is used for notifying the adapter object about a
message dispatched to the web app
<http://w3c.github.io/nfc/#dfn-web-app> via NFC.
8.1.2 The *push* event
As messages are not automatically pushed to peers when they detect each
other, but most often requires some kind of user interaction, the |push|
event is used for notifying the adapter object about a message
successfully pushed to an NFC peer
<http://w3c.github.io/nfc/#dfn-nfc-peer> with a matching URL scope
<http://w3c.github.io/nfc/#dfn-url-scope> in range via NFC.
8.1.3 The *NdefPushEvent* interface
interfaceNdefPushEvent :Event {
readonly attributeUSVString scope <http://w3c.github.io/nfc/#widl-NdefPushEvent-scope>;
ArrayBuffer <http://w3c.github.io/nfc/#dfn-arraybuffer> readAsMessageBuffer <http://w3c.github.io/nfc/#widl-NdefPushEvent-readAsMessageBuffer-ArrayBuffer> ();
};
The |scope| property represents the URL scope
<http://w3c.github.io/nfc/#dfn-url-scope> of the NDEF message
<http://w3c.github.io/nfc/#dfn-ndef-message>.
When the |readAsMessageBuffer| method is invoked, the user agent
<http://w3c.github.io/nfc/#dfn-user-agent> /MUST/ run the following steps:
1. Let arrayBuffer be a new |ArrayBuffer|
<http://w3c.github.io/nfc/#dfn-arraybuffer> object.
2. Read the content of the full NDEF message
<http://w3c.github.io/nfc/#dfn-ndef-message> raw binary data and
copy it to arrayBuffer.
3. Return arrayBuffer.
8.1.4 The *NdefReadEvent* interface
In this specification, NDEF message
<http://w3c.github.io/nfc/#dfn-ndef-message> content is delivered by an
|NdefReadEvent| <http://w3c.github.io/nfc/#idl-def-NdefReadEvent> event.
|NdefReadEvent| <http://w3c.github.io/nfc/#idl-def-NdefReadEvent> implements|NdefPushEvent| <http://w3c.github.io/nfc/#idl-def-NdefPushEvent>;
The |NdefReadEvent| has all properties and methods of the
||NdefPushEvent| <http://w3c.github.io/nfc/#idl-def-NdefPushEvent>|
interface, and the following additional properties:
interfaceNdefReadEvent :Event {
readonly attributeboolean passive <http://w3c.github.io/nfc/#widl-NdefReadEvent-passive>;
readonly attributeboolean writeable <http://w3c.github.io/nfc/#widl-NdefReadEvent-writeable>;
readonly attribute|NdefRecordData| <http://w3c.github.io/nfc/#idl-def-NdefRecordData>[] data <http://w3c.github.io/nfc/#widl-NdefReadEvent-data>;
};
The |passive| property /MUST/ return |true| if the source of the NFC
data is a passive NFC tag <http://w3c.github.io/nfc/#dfn-nfc-tag>, and
|false| otherwise.
The |writeable| property /MUST/ return |true| if the source of the NFC
data is a passive NFC tag <http://w3c.github.io/nfc/#dfn-nfc-tag> which
is writeable, and |false| otherwise.
The |data| property represents the array of ||NdefRecordData|
<http://w3c.github.io/nfc/#idl-def-NdefRecordData>| content
corresponding to the array of NDEF record
<http://w3c.github.io/nfc/#dfn-ndef-record>s payload data of the NDEF
message <http://w3c.github.io/nfc/#dfn-ndef-message>.
8.1.5 The *NdefRecordData* interface
The content of the NDEF message
<http://w3c.github.io/nfc/#dfn-ndef-message> is exposed by the following
interface:
[NoInterfaceObject]
interfaceNdefRecordData {
readonly attributeDOMString <http://w3c.github.io/nfc/#dfn-domstring> contentType <http://w3c.github.io/nfc/#widl-NdefRecordData-contentType>;
DOMString <http://w3c.github.io/nfc/#dfn-domstring> url <http://w3c.github.io/nfc/#widl-NdefRecordData-url-DOMString> ();
Blob <http://w3c.github.io/nfc/#dfn-blob> blob <http://w3c.github.io/nfc/#widl-NdefRecordData-blob-Blob> ();
any <http://w3c.github.io/nfc/#dfn-any> json <http://w3c.github.io/nfc/#widl-NdefRecordData-json-any> ();
DOMString <http://w3c.github.io/nfc/#dfn-domstring> text <http://w3c.github.io/nfc/#widl-NdefRecordData-text-DOMString> ();
ArrayBuffer <http://w3c.github.io/nfc/#dfn-arraybuffer> arrayBuffer <http://w3c.github.io/nfc/#widl-NdefRecordData-arrayBuffer-ArrayBuffer> ();
};
|NdefRecordData| <http://w3c.github.io/nfc/#idl-def-NdefRecordData>
objects have associated data read by the NFC chip upon creation.
The |contentType| attribute describes the type of data such as MIME type
and additional information for text messages, e.g.
|"text/plain;charset=UTF-8;"|
The |url()| method, when invoked, /MUST/ return a |DOMString|
<http://w3c.github.io/nfc/#dfn-domstring> representing any URL stored in
the NDEF message <http://w3c.github.io/nfc/#dfn-ndef-message> or
|undefined|.
The |blob()| method, when invoked, /MUST/ return a |Blob|
<http://w3c.github.io/nfc/#dfn-blob> whose contents are bytes.
The |json()| method, when invoked, /MUST/ return the result of invoking
the initial value of |JSON.parse|
<http://w3c.github.io/nfc/#dfn-json.parse> with the result of running
utf-8 decode <http://w3c.github.io/nfc/#dfn-utf-8-decode> on bytes as
argument. Re-throw any exceptions thrown by |JSON.parse|
<http://w3c.github.io/nfc/#dfn-json.parse>.
The |text() | method, when invoked, /MUST/ return the result of running
utf-8 decode <http://w3c.github.io/nfc/#dfn-utf-8-decode> onbytes.
The |arrayBuffer()| method, when invoked, /MUST/ return an |ArrayBuffer|
<http://w3c.github.io/nfc/#dfn-arraybuffer> whose contents are bytes.
8.2 The *watch()* method
The |watch()| method enables listening to incoming NDEF message
<http://w3c.github.io/nfc/#dfn-ndef-message>s.
As web app <http://w3c.github.io/nfc/#dfn-web-app>s might not be
interested in all peer and tag messages, filtering is possible for
watched messages:
1. Messages have an associated identifier represented as a URL scope
<http://w3c.github.io/nfc/#dfn-url-scope>, which enables filtering
based on this scope.
2. Based on content types the web app
<http://w3c.github.io/nfc/#dfn-web-app> can or wants to handle.
3. Watch only NFC tag <http://w3c.github.io/nfc/#dfn-nfc-tag>s, only
NFC peer <http://w3c.github.io/nfc/#dfn-nfc-peer>s, or both.
Note
Future versions may add additional filtering criteria, e.g. based on NFC
Forum Tag types (such as Type 1 to 4), and NFC technologies (such as
NFC-A, NFC-B, etc).
When writing to tags or pushing messages to peers, the document base URL
<http://w3c.github.io/nfc/#dfn-document-base-url> serves as the default
scope, though another URL scope
<http://w3c.github.io/nfc/#dfn-url-scope> can be set with the
restriction that it /MUST/ include the document domain (e.g.
http://www.w3.org for any data exchange from http://www.w3.org/TR/nfc/).
To describe which messages an application is interested in, the
following dictionary is used:
8.2.1 The *WatchOptions* dictionary
enumWatchType {
"tag-only <http://w3c.github.io/nfc/#idl-def-WatchType.tag-only>",
"peer-only <http://w3c.github.io/nfc/#idl-def-WatchType.peer-only>",
"all <http://w3c.github.io/nfc/#idl-def-WatchType.all>"
};
dictionaryWatchOptions {
DOMString <http://w3c.github.io/nfc/#dfn-domstring>? scope <http://w3c.github.io/nfc/#widl-WatchOptions-scope>;
DOMString <http://w3c.github.io/nfc/#dfn-domstring>[] acceptedContentTypes <http://w3c.github.io/nfc/#widl-WatchOptions-acceptedContentTypes>;
|WatchType| <http://w3c.github.io/nfc/#idl-def-WatchType> watchType <http://w3c.github.io/nfc/#widl-WatchOptions-watchType>;
};
The scope property denotes the URL scope
<http://w3c.github.io/nfc/#dfn-url-scope> for which all messages /MUST/
belong to. If the value is |null| or |undefined|, then implementations
/SHOULD/ use the web app <http://w3c.github.io/nfc/#dfn-web-app>'s
document base URL <http://w3c.github.io/nfc/#dfn-document-base-url>.
The acceptedContentTypes property denotes the list of MIME types, that
the registrations wants to handle.
The watchType property tells whether to watch:
* NFC tag <http://w3c.github.io/nfc/#dfn-nfc-tag>s only, denoted by
the value |'tag-only'|.
* NFC peer <http://w3c.github.io/nfc/#dfn-nfc-peer>s only, denoted by
the value |'peer-only'|.
* Both NFC tag <http://w3c.github.io/nfc/#dfn-nfc-tag>s and NFC peer
<http://w3c.github.io/nfc/#dfn-nfc-peer>, denoted by the value |'all'|.
Example 3: Filter accepting only JSON based messages from
http://www.w3.org
var watchOptions= {
scope: "http://www.w3.org",
acceptedContentTypes: ["application/manifest+json", "application/json", "text/json"]
}
Example 4: Filter which only accept JSON based messages from tags
with scope https://01.org/registration for authentication
var watchOptions= {
scope: "https://01.org/registration",
acceptedContentTypes: ["application/json"],
watchType: 'tag-only'
}
8.2.2 The *within-scope* algorithm
*Inputs*:
1. url, a URL to be checked for being within scope;
2. registeredScope, the URL scope
<http://w3c.github.io/nfc/#dfn-url-scope> to check url against.
*Output*: |true| or |false|
When filtering NDEF message
<http://w3c.github.io/nfc/#dfn-ndef-message>s with identifiers
associated with url, based on URL scope
<http://w3c.github.io/nfc/#dfn-url-scope>, run the following steps
atomically.
1. If registeredScope is |undefined|, then let scope be the calling web
app <http://w3c.github.io/nfc/#dfn-web-app>'s document base URL
<http://w3c.github.io/nfc/#dfn-document-base-url>.
2. Otherwise let scope be registeredScope.
3. If url is a substring of scope, and scope ends with |"/*"|, then
return |true|.
4. If url is an exact match of scope, return |true|.
5. Otherwise return |false|.
When the |watch()| method is invoked, the user agent
<http://w3c.github.io/nfc/#dfn-user-agent> /MUST/ run the following steps:
1. Let promise be a new |Promise|
<http://w3c.github.io/nfc/#dfn-promise> object.
2. Return promise and continue the following steps asynchronously.
3. If there are no sufficient permissions to use this method, then
reject promise with a new |DOMException
<http://w3c.github.io/nfc/#dfn-domexception>| object whose name
property is set to |"SecurityError
<http://w3c.github.io/nfc/#dfn-securityerror>"|, and terminate these
steps.
4. Parse the argument options. If it is invalid in the given platform,
then reject promise with a new |DOMException
<http://w3c.github.io/nfc/#dfn-domexception>| object whose name
property is set to |"SyntaxError
<http://w3c.github.io/nfc/#dfn-syntaxerror>"|, and terminate these
steps.
5. Make a request to the underlying platform to listen to NDEF message
<http://w3c.github.io/nfc/#dfn-ndef-message>s, and set up
within-scope filtering for options.scope, and also set up filtering
for accepted content types, as described by the
options.acceptedContentTypes parameter.
6. As a consequence, fire |read| events only for messages, whose URL
scope <http://w3c.github.io/nfc/#dfn-url-scope> is within-scope for
any of the elements of the list of URL scope
<http://w3c.github.io/nfc/#dfn-url-scope>s registered during
successive calls of the |watch()| method, and for which the content
type matches the list of accepted content types.
7. If the request fails, then reject promise with a new |DOMException
<http://w3c.github.io/nfc/#dfn-domexception>| object whose name
property is set to |"NotSupportedError"| , and terminate these steps.
8. If the request is successful, then resolve promise with an
identifier for the listener, which later can be used with the
|clearWatch()| method to remove the listener.
9. Whenever the user agent <http://w3c.github.io/nfc/#dfn-user-agent>
detects an NFC tag <http://w3c.github.io/nfc/#dfn-nfc-tag> or NFC
peer <http://w3c.github.io/nfc/#dfn-nfc-peer> data that matches the
filtering options set by the watcher, queue a task
<http://w3c.github.io/nfc/#dfn-queue-a-task> to fire an |"read"|
event at the adapter object.
8.3 The *clearWatch*() method
When the |clearWatch()| method is invoked, the user agent
<http://w3c.github.io/nfc/#dfn-user-agent> /MUST/ run the following steps:
1. Let promise be a new |Promise|
<http://w3c.github.io/nfc/#dfn-promise> object.
2. Return promise and continue the following steps asynchronously.
3. If there are no sufficient permissions to use this method, then
reject promise with a new |DOMException
<http://w3c.github.io/nfc/#dfn-domexception>| object whose name
property is set to |"SecurityError
<http://w3c.github.io/nfc/#dfn-securityerror>"|, and terminate these
steps.
4. If the parameter id is |undefined|, then make a request to the
underlying platform to remove all listeners and filters set by
successive calls of the |watch()| method.
5. Otherwise, make a request to the underlying platform to remove the
listener corresponding to the value of id.
6. If the request fails, then reject promise with a new |DOMException
<http://w3c.github.io/nfc/#dfn-domexception>| object whose name
property is set to |"NotSupportedError"|, and terminate these steps.
7. If the request is successful, then resolve promise.
8.4 The *write*() method
The |write()| method is used for writing an NFC tag
<http://w3c.github.io/nfc/#dfn-nfc-tag>, if possible. When this method
is invoked, the user agent <http://w3c.github.io/nfc/#dfn-user-agent>
/MUST/ run the following steps:
1. Let promise be a new |Promise|
<http://w3c.github.io/nfc/#dfn-promise> object.
2. Return promise and continue the following steps asynchronously.
3. If there are no sufficient permissions to use this method, then
reject promise with a new |DOMException
<http://w3c.github.io/nfc/#dfn-domexception>| object whose name
property is set to |"SecurityError
<http://w3c.github.io/nfc/#dfn-securityerror>"|, and terminate these
steps.
4. If there is no support for the functionality of writing an NFC tag
<http://w3c.github.io/nfc/#dfn-nfc-tag> in proximity range, then
reject promise with a new |DOMException
<http://w3c.github.io/nfc/#dfn-domexception>| object whose name
property is set to |"NotSupportedError
<http://w3c.github.io/nfc/#dfn-notsupportederror>"|, and terminate
these steps.
5. Parse the argument scope. If it is invalid in the given platform,
then reject promise with a new |DOMException
<http://w3c.github.io/nfc/#dfn-domexception>| object whose name
property is set to |"SyntaxError
<http://w3c.github.io/nfc/#dfn-syntaxerror>"|, and terminate these
steps. If the value is |undefined|, then attribute to scope the
|DOMString| describing the document base URL
<http://w3c.github.io/nfc/#dfn-document-base-url>.
6. For each element the array argument data, check the type to be one
of the types defined in |NdefData
<http://w3c.github.io/nfc/#dfn-ndefdata>|. If the value is invalid
on the given platform, then reject promise with a new |DOMException
<http://w3c.github.io/nfc/#dfn-domexception>| object whose name
property is set to |"SyntaxError
<http://w3c.github.io/nfc/#dfn-syntaxerror>"|, and terminate these
steps. For each valid element create an NDEF record
<http://w3c.github.io/nfc/#dfn-ndef-record>. The implementation
choose the best suitable NDEF record
<http://w3c.github.io/nfc/#dfn-ndef-record> format for the given
platform. Each element in the input array given in data /SHOULD/ map
to a separate NDEF record
<http://w3c.github.io/nfc/#dfn-ndef-record> in the NDEF message
<http://w3c.github.io/nfc/#dfn-ndef-message> to be sent. Assemble an
NDEF message <http://w3c.github.io/nfc/#dfn-ndef-message> from the
NDEF record <http://w3c.github.io/nfc/#dfn-ndef-record>s and
referred to as output.
7. Make a request to the underlying platform to write output with the
URL scope <http://w3c.github.io/nfc/#dfn-url-scope> provided by
scope to the NFC tag <http://w3c.github.io/nfc/#dfn-nfc-tag> in
proximity range. If the request fails, then reject promise with a
new |DOMException <http://w3c.github.io/nfc/#dfn-domexception>|
object whose name property is set to |"NotSupportedError"|, and
terminate these steps.
8. If the request is successful, then resolve promise.
8.5 The *setPushMessage()* method
The |setPushMessage()| method is used for setting the messages which the
user can push to another peer when it gets into proximity range. When
this method is invoked, the user agent
<http://w3c.github.io/nfc/#dfn-user-agent> /MUST/ run the following steps:
1. Let promise be a new |Promise|
<http://w3c.github.io/nfc/#dfn-promise> object.
2. Return promise and continue the following steps asynchronously.
3. If there are no sufficient permissions to use this method, then
reject promise with a new |DOMException
<http://w3c.github.io/nfc/#dfn-domexception>| object whose name
property is set to |"SecurityError
<http://w3c.github.io/nfc/#dfn-securityerror>"|, and terminate these
steps.
4. If there is no support for the functionality of sending data to an
NFC peer <http://w3c.github.io/nfc/#dfn-nfc-peer> in proximity
range, then reject promise with a new |DOMException
<http://w3c.github.io/nfc/#dfn-domexception>| object whose name
property is set to |"NotSupportedError
<http://w3c.github.io/nfc/#dfn-notsupportederror>"|, and terminate
these steps.
5. Parse the argument scope. If it is invalid in the given platform,
then reject promise with a new |DOMException
<http://w3c.github.io/nfc/#dfn-domexception>| object whose name
property is set to |"SyntaxError
<http://w3c.github.io/nfc/#dfn-syntaxerror>"|, and terminate these
steps. If the value is |undefined|, then attribute to scope the
|DOMString| describing the document base URL
<http://w3c.github.io/nfc/#dfn-document-base-url>.
6. For each element the array argument data, check the type to be one
of the types defined in |NdefData
<http://w3c.github.io/nfc/#dfn-ndefdata>|. If the value is invalid
on the given platform, then reject promise with a new |DOMException
<http://w3c.github.io/nfc/#dfn-domexception>| object whose name
property is set to |"SyntaxError
<http://w3c.github.io/nfc/#dfn-syntaxerror>"|, and terminate these
steps. For each valid element create an NDEF record
<http://w3c.github.io/nfc/#dfn-ndef-record>. The implementation
choose the best suitable NDEF record
<http://w3c.github.io/nfc/#dfn-ndef-record> format for the given
platform. Each element in the input array given in data /SHOULD/ map
to a separate NDEF record
<http://w3c.github.io/nfc/#dfn-ndef-record> in the NDEF message
<http://w3c.github.io/nfc/#dfn-ndef-message> to be sent. Assemble an
NDEF message <http://w3c.github.io/nfc/#dfn-ndef-message> from the
NDEF record <http://w3c.github.io/nfc/#dfn-ndef-record>s and
referred to as output.
7. Make a request to the underlying platform to send output to the NFC
peer <http://w3c.github.io/nfc/#dfn-nfc-peer>s in proximity range.
If the request fails, then reject promise with a new |DOMException
<http://w3c.github.io/nfc/#dfn-domexception>| object whose name
property is set to |"NotSupportedError"|, and terminate these steps.
8. If the request is successful, then resolve promise.
8.6 The *clearPushMessage*() method
When the |clearPushMessage()| method is invoked, the user agent
<http://w3c.github.io/nfc/#dfn-user-agent> /MUST/ run the following steps:
1. Let promise be a new |Promise|
<http://w3c.github.io/nfc/#dfn-promise> object.
2. Return promise and continue the following steps asynchronously.
3. If there are no sufficient permissions to use this method, then
reject promise with a new |DOMException
<http://w3c.github.io/nfc/#dfn-domexception>| object whose name
property is set to |"SecurityError
<http://w3c.github.io/nfc/#dfn-securityerror>"|, and terminate these
steps.
4. If the parameter scope is |undefined|, then make a request to the
underlying platform to remove and cancel pushing any previously set
messages to NFC peer <http://w3c.github.io/nfc/#dfn-nfc-peer>
devices in range or coming into range.
5. Otherwise, make a request to the underlying platform to remove and
cancel pushing messages to NFC peer
<http://w3c.github.io/nfc/#dfn-nfc-peer> devices in range or coming
into range, whose URL scope
<http://w3c.github.io/nfc/#dfn-url-scope> is within-scope for scope.
6. If the request fails, then reject promise with a new |DOMException
<http://w3c.github.io/nfc/#dfn-domexception>| object whose name
property is set to |"NotSupportedError"|, and terminate these steps.
7. If the request is successful, then resolve promise.
A. Changes
The following is a list of substantial changes to the document. For a
complete list of changes, see the change log on Github
<https://github.com/w3c/nfc/commits/gh-pages>. You can also view the
recently closed bugs
<https://github.com/w3c/nfc/issues?page=1&state=closed>.
* Redesigned the API to follow contemporary web design patterns
* Change of editors
B. Acknowledgements
The editors would like to express their gratitude to the former editors
Luc Yriarte and Samuel Ortiz, and also to Don Coleman, Salvatore Iovene
and Jeffrey Yasskin for their technical guidance, implementation
feedback and support.
C. References
C.1 Normative references
[DOM4]
Anne van Kesteren; Aryeh Gregor; Ms2ger; Alex Russell; Robin Berjon.
W3C DOM4 <http://www.w3.org/TR/dom/>. 10 July 2014. W3C Last Call
Working Draft. URL: http://www.w3.org/TR/dom/
[ECMASCRIPT]
Allen Wirfs-Brock. ECMA-262 ECMAScript Language Specification,
Edition 6 <http://people.mozilla.org/%7Ejorendorff/es6-draft.html>.
Draft. URL: http://people.mozilla.org/~jorendorff/es6-draft.html
<http://people.mozilla.org/%7Ejorendorff/es6-draft.html>
[ENCODING]
Anne van Kesteren; Joshua Bell; Addison Phillips. Encoding
<http://www.w3.org/TR/encoding/>. 16 September 2014. W3C Candidate
Recommendation. URL: http://www.w3.org/TR/encoding/
[FILEAPI]
Arun Ranganathan; Jonas Sicking. File API
<http://www.w3.org/TR/FileAPI/>. 12 September 2013. W3C Last Call
Working Draft. URL: http://www.w3.org/TR/FileAPI/
[HTML5]
Ian Hickson; Robin Berjon; Steve Faulkner; Travis Leithead; Erika
Doyle Navara; Edward O'Connor; Silvia Pfeiffer. HTML5
<http://www.w3.org/TR/html5/>. 28 October 2014. W3C Recommendation.
URL: http://www.w3.org/TR/html5/
[RFC2119]
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels
<https://tools.ietf.org/html/rfc2119>. March 1997. Best Current
Practice. URL: https://tools.ietf.org/html/rfc2119
[WEBIDL]
Cameron McCormack. Web IDL <http://www.w3.org/TR/WebIDL/>. 19 April
2012. W3C Candidate Recommendation. URL: http://www.w3.org/TR/WebIDL/
C.2 Informative references
[SERVICE-WORKERS]
Alex Russell; Jungkee Song; Jake Archibald. Service Workers
<http://www.w3.org/TR/service-workers/>. 5 February 2015. W3C
Working Draft. URL: http://www.w3.org/TR/service-workers/
Received on Thursday, 12 March 2015 16:27:36 UTC