W3C Editor's Draft 29 December 2014
- This version:
- http://www.w3.org/2012/nfc/web-api/
- Latest published version:
- http://www.w3.org/TR/nfc/
- Latest editor's draft:
- http://www.w3.org/2012/nfc/web-api/
- Editors:
- Repository:
- We are on Github.
- File a bug.
- Commit history.
Copyright © 2014 W3C® (MIT, ERCIM, Keio, Beihang), All Rights Reserved. W3C liability, trademark and document use rules apply.
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/).
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:
Status of This Document
This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3Cpublications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.
Implementors need to be aware that this specification is considered unstable. Implementors who are not taking part in the discussions will find the specification changing out from under them in incompatible ways. Vendors interested in implementing this specification before it eventually reaches the Candidate Recommendation phase should subscribe to the repository on GitHub and take part in the discussions.
Significant changes to this document since last publication are documented in the Changes section.
This document was published by the NFC working group as an Editor's Draft. If you wish to make comments regarding this document, please send them to public-nfc@w3.org (subscribe, archives). All comments are welcome.
Publication as an Editor's Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.
This document was produced by a group operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.
This document is governed by the 1 August 2014 W3C Process Document.
Table of Contents
- 1. Conformance
- 2. Terminology
- 3. Introduction
- 4. Usage Examples
- 5. Security and Privacy Considerations
- 6. Data types and content
- 7. Extensions to the Navigator interface
- 8. The NFC interface
- 9. The NfcTagRegistration interface
- 10. The NfcPeerRegistration interface
- A. Changes
- B. Acknowledgements
- C. 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 may, must, must not, and should are to be interpreted as described in [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], as this specification uses that specification and terminology.
2. Terminology
The EventHandler
interface represents a callback used for event handlers as defined in [HTML5].
The concepts queue a task and fire a simple event are defined in [HTML5].
The terms event handler and event handler event types are defined in [HTML5].
Promise
, and JSON.parse
are defined in [ECMASCRIPT].
The algorithms utf-8 encode, and utf-8 decode are defined in [ENCODING].
EventInit, DOMException, AbortError, SyntaxError, NotSupportedError, NotFoundError, and SecurityError are defined in [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, 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 to access the Web NFC API.
DOMString
, ArrayBuffer
, BufferSource
and any
are defined in [WEBIDL].
An NFC tag is a passive, unpowered NFC device. The NFC tag is powered by magnetic induction when an active NFC device is in proximity range. A NFC tagcontains a single NDEF message.
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 records. NDEF stands for NFC Forum Data Exchange Format, a lightweight binary message format. NDEF messages can be stored on a 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 records, 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 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 includes record types text, URI, Smart Poster (containing a URI or other data and possible actions).
The term sufficient permission in this document means that a 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 is defined in [HTML5].
The term URL scope is introduced in this document for NFC operations as a sub-string match to the web app's document URL, which includes the domain of the calling web app. The URL scope is stored in the identifier field of an NDEF record.
3. Introduction
This section is non-normative.
There are three groups of application scenarios for NFC:
- Hold a device close to a passive wireless tag to read and write data.
- 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
- For payments by holding your phone close to a point-of-sales terminal, instead of swiping a payment card.
- For emulating tags, allowing use-cases like being able to open your hotel room using just your phone instead of using a NFC-enabled tag or smart 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.
In addition to data types standardized for NDEF records 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.
NFC is usually deeply integrated into device platforms (e.g. Android, Tizen, 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 handling and the API exposes only data and control events.
Handover scenarios are expected to be completely encapsulated by implementations. A later version of this API may expose initiating a handover over Bluetooth or WiFi, but in either case implementations and underlying platforms are assumed to handle handover records according to their capabilities.
Implementations may handle Smart Poster (see "Smart Poster RTD Specification", NFC Forum, 2006) record types, and may expose their data to web apps through this API.
4. Usage Examples
This section is non-normative.
This section shows how developers can make use of the various features of this specification.
navigator.nfc.requestTagRegistration({ scope: "/jumpyjack" }).then(
function(tagHandler) {
tagHandler.onmessage = function(ev) {
if (!self.isAwaitingSave && message.length > 0)
return self.showRestoreLevelDialog(ev.message[0].progress);
tagHandler.write({
progress: self.progress(),
player: self.player()
}, "/jumpyjack");
};
}, function(error) {
console.log("buggyjack");
}
});
5. Security and Privacy Considerations
User agents must not provide Web NFC API access to web apps without the expressed permission of the user. User agents must acquire consent for permission through a user interface for each call to the request*() methods, unless a prearranged trust relationship applies.
User agents may support prearranged trust relationships that do not require such per-request user interfaces.
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. Data types and content
6.1 Data types
This API exposes the following data types originating from NDEF messages.
typedef NfcMessageType = DOMString | URL | Blob | JSON;
The mapping from NDEF record types to supported NfcMessageType
is as follows:
NfcMessageType | NDEF record type |
---|---|
DOMString | NFC Forum Well Known Type (TNF=1) with type Text |
URL | |
JSON | Media-type as defined in RFC 2046 (TNF=2) with associated MIME type "application/webnfc+json" |
Blob |
|
6.2 The NfcMessageData interface
The content of the NDEF message is exposed by the following interface:
[NoInterfaceObject]
interface NfcMessageData {
readonly attribute DOMString contentType;
DOMString url ();
ArrayBuffer arrayBuffer ();
Blob blob ();
any json ();
DOMString text ();
};
NfcMessageData
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
representing any URL stored in the NDEF message or undefined
.
The arrayBuffer()
method, when invoked, must return an ArrayBuffer
whose contents are bytes.
The blob()
method, when invoked, must return a Blob
whose contents are bytes.
The json()
method, when invoked, must return the result of invoking the initial value of JSON.parse
with the result of running utf-8 decode on bytes as argument. Re-throw any exceptions thrown by JSON.parse
.
The text()
method, when invoked, must return the result of running utf-8 decode onbytes.
6.3 The NfcMessageEvent interface
In this specification, NDEF message content is delivered by an NfcMessageEvent
event.
interface NfcMessageEvent : Event {
readonly attribute DOMString scope;
readonly attribute NfcMessageData
[] message;
};
The scope
property represents the URL scope of the NDEF message.
The message
property represents the
content of the NDEF message.NfcMessageData
7. Extensions to the Navigator interface
The HTML specification defines a Navigator
interface [HTML] which this specification extends.
7.1 The nfc attribute
When getting the nfc attribute, the user agent must return the NFC
object, which provides NFC related functionality.
8. The NFC interface
interface NFC {
Promise<NfcTagRegistration
> requestTagRegistration (RegistrationOptions
? options);
Promise<NfcPeerRegistration
> requestPeerRegistration (RegistrationOptions
? options);
};
By using these methods, web apps can obtain control objects providing NFC functionality, separately for handling passive NFC tags and communication with active NFC peers, in a similar way to that of service worker extensions [SERVICE-WORKERS].
As web apps might not be interested in all peer and tag messages, the messages have an associated identifier represented as a URL scope, which enables filtering based on this scope, and also based on content types the web app can or wants to handle.
When writing or pushing messages to peers, the document base URL serves as the default scope, though another 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/).
Using a different scope can be useful in order to easily differentiate messages and use different registrations and event handlers per scope.
To describe which messages a registration should apply to, the following dictionary is used:
8.1 The RegistrationOptions dictionary
dictionary RegistrationOptions {
DOMString? scope;
DOMString[] contentTypes;
};
The scope property denotes the URL scope for which all messages must belong to for the given registration. If the value is null
or undefined
, then implementations should use the web app's document base URL.
The contentTypes property denotes the list of MIME types, that the registrations wants to handle.
var registrationOptions = {
scope: "http://www.w3.org",
contentTypes: ["application/manifest+json", "application/json", "text/json"]
}
var registrationOptions = {
scope: "https://01.org/registration",
contentTypes: ["application/json"]
}
8.2 The within-scope algorithm
Preconditions: a registration object (either
or NfcTagRegistration
) exists with an associated regOptions of type NfcPeerRegistration
, which contains registeredScope URL scope.RegistrationOptions
Input: url, a URL to be checked for being within scope.
Output: true
or false
When filtering NDEF messages associated with url, based on URL scope, run the following steps atomically.
- If registeredScope defined in regOptions is
undefined
, then let scope be the calling web app's document base URL. - Otherwise let scope be registeredScope.
- If url is a substring of scope, return
true
, otherwise returnfalse
.
8.3 The requestTagRegistration() method
The requestTagRegistration()
method provides a control object for handling NFC functionality related to NFC tags. When this method is invoked, the user agentmust run the following steps:
- Let promise be a new
Promise
object. - Return promise and continue the following steps asynchronously.
- If there are no sufficient permissions to use this method, then reject promise with a new
DOMException
object whose name property is set to"SecurityError"
, and terminate these steps. - If there is no support for NFC tag handling functionality in hardware, software, or due to physical incompatibility, then reject promise with a new
DOMException
object whose name property is set to"NotSupportedError"
, and terminate these steps. - Parse the argument filter. If it is invalid in the given platform, then reject promise with a new
DOMException
object whose name property is set to"SyntaxError"
, and terminate these steps. - Make a request to the underlying platform to initialize NFC functionality. If the request fails, then reject promise with a new
DOMException
object whosename property is set to"NotSupportedError"
, and terminate these steps. - If the request is successful, then resolve promise with a
object with filtering for incoming data types described by the filterparameter, i.e. fireNfcTagRegistration
message
events only for messages within-scope and accepted content types. - Whenever the user agent detects an NFC tag which matches the filter associated with an
object, queue a task to fire aNfcTagRegistration
"message"
event at the object.
8.4 The requestPeerRegistration() method
The requestPeerRegistration()
method provides a control object for handling NFC functionality related to NFC peers. When this method is invoked, the user agent must run the following steps:
- Let promise be a new
Promise
object. - Return promise and continue the following steps asynchronously.
- If there are no sufficient permissions to use this method, then reject promise with a new
DOMException
object whose name property is set to"SecurityError"
, and terminate these steps. - If there is no support for NFC tag handling functionality in the device, then reject promise with a new
DOMException
object whose name property is set to"NotSupportedError"
, and terminate these steps. - Parse the argument filter. If it is invalid in the given platform, then reject promise with a new
DOMException
object whose name property is set to"SyntaxError"
, and terminate these steps. - Make a request to the underlying platform to initialize NFC functionality. If the request fails, then reject promise with a new
DOMException
object whosename property is set to"NotSupportedError"
, and terminate these steps. - If the request is successful, then resolve promise with a
object with filtering for incoming data types described by the filterparameter, i.e. fireNfcPeerRegistration
message
events only for messages within-scope and accepted content types. - Whenever the user agent detects an NFC tag which matches to the filter associated with a
object, queue a task to fire anNfcTagRegistration
"message"
event at the object.
9. The NfcTagRegistration interface
[NoInterfaceObject]
interface NfcTagRegistration : EventHandler {
Promise write (NfcMessageType message, DOMString scope);
attribute EventHandler onmessage;
};
The following are the event handlers implemented by the
interface.NfcTagRegistration
event handler | event name | event type |
---|---|---|
onmessage |
message |
|
9.1 The message event
The message
event is used for notifying the registration objects about messages dispatched to the web app via NFC.
9.2 The write() method
The write()
method is used for writing an NFC tag, if possible. When this method is invoked, the user agent must run the following steps:
- Let promise be a new
Promise
object. - Return promise and continue the following steps asynchronously.
- If there are no sufficient permissions to use this method, then reject promise with a new
DOMException
object whose name property is set to"SecurityError"
, and terminate these steps. - If there is no support for the functionality of writing an NFC tag in proximity range, then reject promise with a new
DOMException
object whose nameproperty is set to"NotSupportedError"
, and terminate these steps. - Parse the argument message. If it is invalid on the given platform, then reject promise with a new
DOMException
object whose name property is set to"SyntaxError"
, and terminate these steps. If valid, create an appropriate NDEF message, i.e. a list of NDEF records to be written to the NFC tag, denoted by output. - Parse the argument scope. If it is invalid in the given platform, then reject promise with a new
DOMException
object whose name property is set to"SyntaxError"
, and terminate these steps. If the value isundefined
, then attribute to scope theDOMString
describing the document base URL. - Make a request to the underlying platform to write output to the NFC tag in proximity range. If the request fails, then reject promise with a new
DOMException
object whose name property is set to"NotSupportedError"
, and terminate these steps. - If the request is successful, then resolve promise.
10. The NfcPeerRegistration interface
[NoInterfaceObject]
interface NfcPeerRegistration : EventHandler {
Promise setPushMessage (NfcMessageType message, DOMString scope);
attribute EventHandler onmessagepushed;
attribute EventHandler onmessage;
};
The following are the event handlers implemented by the
interface.NfcTagRegistration
event handler | event name | event type |
---|---|---|
onmessage |
message |
|
onmessagepushed |
messagepushed |
|
10.1 the message event
The message
event is used for notifying the registration objects about messages dispatched to the web app via NFC.
10.2 the messagepushed event
As messages are not automatically pushed to peers when they detect each other, but most often requires some kind of user interaction, a messagepushed
event exists which will be called when a message has been successfully pushed to the other peer.
10.3 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 must run the following steps:
- Let promise be a new
Promise
object. - Return promise and continue the following steps asynchronously.
- If there are no sufficient permissions to use this method, then reject promise with a new
DOMException
object whose name property is set to"SecurityError"
, and terminate these steps. - If there is no support for the functionality of sending data to an NFC peer in proximity range, then reject promise with a new
DOMException
object whosename property is set to"NotSupportedError"
, and terminate these steps. - Parse the argument message. If it is invalid on the given platform, then reject promise with a new
DOMException
object whose name property is set to"SyntaxError"
, and terminate these steps. If valid, create an appropriate NDEF message, i.e. a list of NDEF records to be written to the NFC tag, denoted by output. - Parse the message parameter. If it is invalid or incompatible in the given platform, then reject promise with a new
DOMException
object whose nameproperty is set to"SyntaxError"
, and terminate these steps. - Let output be a newly composed NDEF message which matches best the content of message. Set the
id
field of the NDEF records to scope. - Make a request to the underlying platform to write output to NFC peers in proximity range. If the request fails, then reject promise with a new
DOMException
object whose name property is set to"NotSupportedError"
, and terminate these steps. - 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. You can also view the recently closed bugs.
- 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 and Salvatore Iovene 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. 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. Draft. URL: http://people.mozilla.org/~jorendorff/es6-draft.html
- [ENCODING]
- Anne van Kesteren; Joshua Bell; Addison Phillips. Encoding. 16 September 2014. W3C Candidate Recommendation. URL: http://www.w3.org/TR/encoding/
- [FILEAPI]
- Arun Ranganathan; Jonas Sicking. File API. 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. 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. March 1997. Best Current Practice. URL: https://tools.ietf.org/html/rfc2119
- [WEBIDL]
- Cameron McCormack. Web IDL. 19 April 2012. W3C Candidate Recommendation. URL: http://www.w3.org/TR/WebIDL/
C.2 Informative references
- [SERVICE-WORKERS]
- Alex Russell; Jungkee Song. Service Workers. 18 November 2014. W3C Working Draft. URL: http://www.w3.org/TR/service-workers/