Abstract

Near Field Communication (NFC) is an international standard (ISO/IEC 18092) that specifies 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/). There are three groups of application scenarios for NFC:

NFC enables wireless communication between two devices at close proximity, usually less than a few centimeters.

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 W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.

This document defines an API for access to the hardware subsystem for near field communications (NFC). It permits Web pages to read and write NFC tags, to send and receive messages between NFC devices, and to handover to WiFi or Bluetooth.

This document was published by the NFC working group as a First Public Working Draft. This document is intended to become a W3C Recommendation. 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 a First Public Working 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.

Table of Contents

1. Introduction

This section is non-normative.

The NFC API supports the following features:

Here are some possible use cases:

An example of use is provided below:

Example 1 
var hello = new NDEFRecordText("hello world", "en-US", "UTF-8");

navigator.nfc.ontagfound = function(e) {
    window.console.log('NFC Tag found!');
    var tag = e.tag;
    tag.writeNDEF(new NDEFMessage([hello]));
}

navigator.nfc.startPoll().catch(
  function(e) {
    window.console.error(e);
  });

2. 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, REQUIRED, SHOULD, SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL in this specification 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 that 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.

3. 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].

The Event interface and the Promise interface as well as the concept of a resolver are defined in [DOM4].

A NFC tag is a passive, unpowered NFC device. The NFC tag is powered by magnetic induction when an active NFC device is in close vicinity. A NFC tag contains a single NDEF message.

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

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

4. Extensions to Navigator object

The NFCManager interface is exposed on [HTML]'s Navigator object.

partial interface Navigator {
    readonly    attribute NFCManager nfc;
};

4.1 Attributes

nfc of type NFCManager, readonly
The object that exposes the default NFC manager on the device.

5. NFCManager Interface

The NFCManager interface defines access to NFC functionality and offers methods to control local NFC behavior like polling for targets.

[NoInterfaceObject]
interface NFCManager : EventTarget {
    readonly    attribute boolean      powered;
    readonly    attribute boolean      polling;
    Promise powerOn ();
    Promise powerOff ();
    Promise startPoll ();
    Promise stopPoll ();
                attribute EventHandler onpoweron;
                attribute EventHandler onpoweroff;
                attribute EventHandler onpollstart;
                attribute EventHandler onpollstop;
                attribute EventHandler ontagfound;
                attribute EventHandler ontaglost;
                attribute EventHandler onpeerfound;
                attribute EventHandler onpeerlost;
};

5.1 Attributes

onpeerfound of type EventHandler,
The peerfound event of type NFCPeerEvent MUST be fired whenever a new NFCPeer is detected by the NFC manager. The peer property of the event MUST contain the corresponding NFCPeer object.
onpeerlost of type EventHandler,
Event handler called when the peerlost event is dispatched.
onpollstart of type EventHandler,
Event handler called when the pollstart event is dispatched.
onpollstop of type EventHandler,
Event handler called when the pollstop event is dispatched.
onpoweroff of type EventHandler,
Event handler called when the poweroff event is dispatched.
onpoweron of type EventHandler,
Event handler called when the poweron event is dispatched.
ontagfound of type EventHandler,
The tagfound event of type NFCTagEvent MUST be fired whenever a new NFCTag is detected by the NFC manager. The tag property of the event MUST contain the corresponding NFCTag object.
ontaglost of type EventHandler,
Event handler called when the taglost event is dispatched.
polling of type boolean, readonly
Indicates that the NFC manager is polling.
powered of type boolean, readonly
Indicates that the NFC manager is powered.

5.2 Methods

powerOff
Turns NFC hardware power off. This method returns a new Promise to notify the caller that the NFC hardware power is turned off.
No parameters.
Return type: Promise
powerOn
Turns NFC hardware power on. This method returns a new Promise to notify the caller that the NFC hardware is now powered.
No parameters.
Return type: Promise
startPoll
Start polling for NFC tags or peer devices. This method returns a new Promise to notify the caller that the NFC hardware is now polling.
No parameters.
Return type: Promise
stopPoll
Stop polling for NFC tags or peer devices. This method returns a new Promise to notify the caller that the NFC hardware stopped polling.
No parameters.
Return type: Promise

5.3 Event handlers

The following are the event handlers (and their corresponding event handler types) that MUST be supported as attributes by the NFC object.

event handler event name event type short description
onpoweron poweron simple event fired when the powered state changes to true
onpoweroff poweroff simple event fired when the powered state changes to false
onpollstart pollstart simple event fired when the polling state changes to true
onpollstop pollstop simple event fired when the polling state changes to false
ontagfound tagfound NFCTagEvent with tag property set to the new NFCTag object. detect a new NFCTag
ontaglost taglost simple event fired when the NFCTag detected by the adaptor moves out of range.
onpeerfound peerfound NFCPeerEvent with peer property set to the new NFCPeer object. detect a new NFCPeer
onpeerlost peerlost simple event fired when the NFCPeer detected by the adaptor moves out of range.

6. NFCTagEvent Interface

interface NFCTagEvent : Event {
    readonly    attribute NFCTag tag;
};

6.1 Attributes

tag of type NFCTag, readonly
When getting, the user agent MUST return the NFCTag that triggered the event.

7. NFCPeerEvent Interface

interface NFCPeerEvent : Event {
    readonly    attribute NFCPeer peer;
};

7.1 Attributes

peer of type NFCPeer, readonly
When getting, the user agent MUST return the NFCPeer that triggered the event.

8. NDEFMessageEvent Interface

interface NDEFMessageEvent : Event {
    readonly    attribute NDEFMessage message;
};

8.1 Attributes

message of type NDEFMessage, readonly
When getting, the user agent MUST return the NDEFMessage that triggered the event.

9. NFCTag Interface

[NoInterfaceObject]
interface NFCTag {
    Promise readNDEF ();
    Promise writeNDEF (NDEFMessage message);
};

9.1 Methods

readNDEF
Read NDEF data from the NFC tag. This method returns a new Promise that will notify the caller with the result of the operation, which is a NDEFRecord.
No parameters.
Return type: Promise
writeNDEF
Write a NDEF message on the NFC tag. This method returns a new Promise to notify the caller about the operation success or failure.
Parameter Type Nullable Optional Description
message NDEFMessage ✘ ✘ The NDEF message to write on the NFC Tag
Return type: Promise

10. NFCPeer Interface

[NoInterfaceObject]
interface NFCPeer : EventTarget {
    Promise sendNDEF (NDEFMessage message);
    Promise startHandover (HandoverType handoverType);
                attribute EventHandler onmessageread;
};

10.1 Attributes

onmessageread of type EventHandler,
The messageread event of type NDEFMessageEvent MUST be fired whenever a new NDEFMessage is sent by the peer device. The message property of the event MUST contain the corresponding NDEFMessage object.

10.2 Methods

sendNDEF
Send a NDEF message to the NFC peer device. This method returns a new Promise to notify the caller about the operation success or failure.
Parameter Type Nullable Optional Description
message NDEFMessage ✘ ✘ The NDEF message to send to the NFC peer device.
Return type: Promise
startHandover
Initiates WiFi or Bluetooth pairing with the NFC peer-to-peer target. This method returns a new Promise to notify the caller about the operation success or failure.
Parameter Type Nullable Optional Description
handoverType HandoverType ✘ ✘ Select "wifi" or "bluetooth" pairing.
Return type: Promise

10.3 Event handlers

The following are the event handlers (and their corresponding event handler types) that MUST be supported as attributes by the NFCPeer object.

event handler event name event type short description
onmessageread messageread NDEFMessageEvent with message property set to the new NDEFMessage object. fired when a NDEFMessage is sent by the peer device.

11. NDEFMessage Interface

[
Constructor(byte［］bytes)
Constructor(NDEFRecord［］records)
]
interface NDEFMessage {
    readonly    attribute NDEFRecord[] records;
    Promise getBytes ();
};

11.1 Attributes

records of type array of NDEFRecord, readonly
MUST return an array of all NDEFRecord objects part of the NDEF message. Otherwise it MUST return an empty list.

11.2 Methods

getBytes
Get the binary representation of the NDEF message. This method returns a new Promise to notify the caller with the result of the operation, which is of type byte[] i.e. a Javascript Array of Number objects.
No parameters.
Return type: Promise

12. NDEFRecord Interface

[
Constructor(byte tnf, 
  optional DOMString type, 
  optional byte［］payload, 
  optional DOMString id)
]
interface NDEFRecord {
    readonly    attribute NDEFRecordType recordType;
    readonly    attribute byte           tnf;
    readonly    attribute DOMString?     type;
    readonly    attribute DOMString?     id;
    Promise getPayload ();
};

12.1 Attributes

id of type DOMString, readonly , nullable
An identifier for the record, in the form of a URI reference.
recordType of type NDEFRecordType, readonly
The record type, according to the sub-interface in implements.
tnf of type byte, readonly
The record's Type Name Format. Possible values are 0 (Empty), 1 (Well known), 2 (Media), 3 (URI), 4 (External), 5 (Unknown)
type of type DOMString, readonly , nullable
A string identifier describing the type of the payload.

12.2 Methods

getPayload
Extract the binary payload of the NDEF record. This method returns a new Promise to notify the caller with the result of the operation, which is of type byte[] i.e. a Javascript Array of Number objects.
No parameters.
Return type: Promise

13. NDEFRecordText Interface

[Constructor(DOMString text, 
             optional DOMString languageCode,
             optional DOMString encoding)]
interface NDEFRecordText : NDEFRecord {
    readonly    attribute DOMString text;
    readonly    attribute DOMString languageCode;
    readonly    attribute DOMString encoding;
};

13.1 Attributes

encoding of type DOMString, readonly
The encoding type MUST be either UTF-8 or UTF-16
languageCode of type DOMString, readonly
The language code string value, followed by IANA[RFC 3066] (ex: en-US, ko-KR).
text of type DOMString, readonly
The encoded text.

14. NDEFRecordURI Interface

[Constructor(DOMString uri)]
interface NDEFRecordURI : NDEFRecord {
    readonly    attribute DOMString uri;
};

14.1 Attributes

uri of type DOMString, readonly
The URI string that will be stored in the payload.

15. NDEFRecordMedia Interface

[Constructor(DOMString mimeType,
             byte［］payload)]
interface NDEFRecordMedia : NDEFRecord {
    readonly    attribute DOMString mimeType;
};

15.1 Attributes

mimeType of type DOMString, readonly
The MIME type of the payload, as defined in [RFC 2046].

16. NDEFRecordSmartPoster Interface

[Constructor(DOMString uri,
             optional NDEFRecordText［］titles,
             optional DOMString action,
             optional NDEFRecordMedia［］icons,
             optional unsigned long targetSize,
             optional DOMString targetMIME)]
interface NDEFRecordSmartPoster : NDEFRecord {
    readonly    attribute DOMString          uri;
    readonly    attribute NDEFRecordText[]?  titles;
    readonly    attribute SmartPosterAction? action;
    readonly    attribute NDEFRecordMedia[]? icons;
    readonly    attribute unsigned long?     targetSize;
    readonly    attribute DOMString?         targetMIME;
};

16.1 Attributes

action of type SmartPosterAction, readonly , nullable
The possible actions defined by the NFC forum Smart Poster Record Type.
icons of type array of NDEFRecordMedia, readonly , nullable
The Smart Poster Record can contain one or more icons, that can also be animated.
targetMIME of type DOMString, readonly , nullable
The MIME type of the URI target.
targetSize of type unsigned long, readonly , nullable
The size of the URI target in bytes.
titles of type array of NDEFRecordText, readonly , nullable
The title in different languages. There MUST NOT be more than one title record with the same language code string value.
uri of type DOMString, readonly
The URI field of the Smart Poster record, REQUIRED by the NFC forum specification.

17. Enumerations

The attribute recordType can have the following values:

enum NDEFRecordType {
    "text",
    "uri",
    "media",
    "smartPoster",
    "unknown"
};
Enumeration description
text Corresponding to NDEFRecordText.
uri Corresponding to NDEFRecordURI.
media Corresponding to NDEFRecordMedia.
smartPoster Corresponding to NDEFRecordSmartPoster.
unknown Corresponding to the base NDEFRecord interface.

The attribute action can have the following values:

enum SmartPosterAction {
    "do",
    "save",
    "open"
};
Enumeration description
do Do the action. For instance, send a SMS, dial a phone number, or open a URI.
save Store a SMS, bookmark a URI, save a phone number in the address book.
open Open for edition.

The attribute handoverType can have the following values:

enum HandoverType {
    "wifi",
    "bluetooth"
};
Enumeration description
wifi Initiate WiFi handover.
bluetooth Initiate bluetooth pairing.

18. Acknowledgements

The editors would like to thank Jaehyun Park and Taehee Lee of Samsung for their work on the initial API design. We would also like to thank the members of the W3C SysApps group for their help on the API specification process, and the members of the W3C NFC group for their feedback on this API.

A. References

A.1 Normative references

[DOM4]
Anne van Kesteren; Aryeh Gregor; Lachlan Hunt; Ms2ger. DOM4. 6 December 2012. W3C Working Draft. URL: http://www.w3.org/TR/dom/
[HTML]
Ian Hickson. HTML. Living Standard. URL: http://www.whatwg.org/specs/web-apps/current-work/
[HTML5]
Robin Berjon; Steve Faulkner; Travis Leithead; Erika Doyle Navara; Edward O'Connor; Silvia Pfeiffer. HTML5. 6 August 2013. W3C Candidate Recommendation. URL: http://www.w3.org/TR/html5/
[RFC2119]
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Internet RFC 2119. URL: http://www.ietf.org/rfc/rfc2119.txt
[WEBIDL]
Cameron McCormack. Web IDL. 19 April 2012. W3C Candidate Recommendation. URL: http://www.w3.org/TR/WebIDL/