Web NFC API Specification

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. (http://www.nfc-forum.org/specs/spec_list/). There are three groups of application scenarios for NFC:

• The first one is to hold a device close to a wireless tag to exchange some digital information or data.
• The second is to hold two devices close to each other in order to exchange some information or data between them.
• The third one is to make payments by holding mobile phones close to point of sales terminals instead of swiping smart cards.

Table of Contents

1. 1 Web NFC API
   1. 1.1 Interface Navigator
   2. 1.2 Interface NFCManager
   3. 1.3 Interface NFCAdapter
   4. 1.4 Interface NFCTag
   5. 1.5 Interface NFCPeer
   6. 1.6 Interface NDEFMessage
   7. 1.7 Interface NDEFRecord
   8. 1.8 Interface NDEFRecordText
   9. 1.9 Interface NDEFRecordURI
   10. 1.10 Interface NFCTagDetectCallback
   11. 1.11 Interface NFCPeerDetectCallback
   12. 1.12 Interface NDEFMessageReadCallback
2. References
3. Acknowledgements

1 Web NFC API

• Reading and writing NDEF messages on NFC Tags
• Sending and receiving NDEF messages on peer targets

1.1 Interface Navigator

partial interface Navigator {
  readonly attribute NFCManager nfc;
}

The nfc attribute must return the object through which the nfc functionality can be accessed.

1.2 Interface NFCManager

enum NDEFRecordTextEncoding { "UTF-8", "UTF-16" };
enum NFCTagType { "Type 1", "Type 2", "Type 3", "Type 4" };
enum HandoverType { "bluetooth", "wifi" };

[NoInterfaceObject]
interface NFCManager {
  NFCAdapter getDefaultAdapter();
};

The getDefaultAdapter method returns the default NFCAdapter on the device.

1.3 Interface NFCAdapter

[NoInterfaceObject]
interface NFCAdapter {
    readonly attribute boolean powered ;
    readonly attribute boolean polling ;
    void setPowered(boolean state,
        optional Function? successCallback,
        optional Function? errorCallback);
    void setPolling(boolean state,
        optional Function? successCallback,
        optional Function? errorCallback);
    void setTagListener(NFCTagDetectCallback detectCallback,
        optional Function? errorCallback,
        optional NFCTagType[]? tagFilter);
    void setPeerListener(NFCPeerDetectCallback detectCallback,
        optional Function? errorCallback);
    void unsetTagListener();
    void unsetPeerListener();
};

The powered property indicates that the adapter is powered.

The polling property indicates that the adapter is currently polling for NFC tags or peer devices.

The setPowered method turns the adapter on or off.

The setPolling method lets the adapter start / stop polling for NFC tags or peer devices.

The setTagListener method registers a listener to invoke on NFCTag detection. The detectCallback parameter is the NFCTagDetectCallback to be invoked when a NFCTag is detected or lost. The tagFilter parameter used to filter the NFCTagType.

The setPeerListener method registers a listener to invoke on NFCPeer device detection. The detectCallback parameter is the NFCPeerDetectCallback to be invoked when a NFCPeer device is detected or lost.

The unsetTagListener method unregisters the NFCTag listener.

The unsetPeerListener method unregisters the NFCPeer listener.

1.4 Interface NFCTag

[NoInterfaceObject]
interface NFCTag {
    readonly attribute NFCTagType type ;
    void readNDEF(NDEFMessageReadCallback readCallback,
        optional Function? errorCallback);
    void writeNDEF(NDEFMessage ndefMessage,
        optional Function? successCallback,
        optional Function? errorCallback);
};

The readNDEF method reads a NDEFMessage on a NFCTag. The readCallback parameter is the NDEFMessageReadCallback to be invoked with the NDEFMessage content.

The writeNDEF method writes a NDEFMessage to a NFCTag. The ndefMessage parameter is the NDEFMessage content to write.

1.5 Interface NFCPeer

[NoInterfaceObject]
interface NFCPeer {
    readonly attribute boolean isConnected ;
    void setReceiveNDEFListener(NDEFMessageReadCallback successCallback,
        optional Function? errorCallback);
    void unsetReceiveNDEFListener();
    void sendNDEF(NDEFMessage ndefMessage,
        optional Function? successCallback,
        optional Function? errorCallback);
    void startHandover(HandoverType type,
        optional Function? successCallback,
        optional Function? errorCallback);
};

The isConnected property indicates that the peer-to-peer target is connected.

The setReceiveNDEFListener method registers a listener to invoke when a NDEFMessage is received. The successCallback parameter is the NDEFMessageReadCallback to be invoked with the NDEFMessage content.

The unsetReceiveNDEFListener method unregisters the NDEFMessageReadCallback.

The sendNDEF method sends a NDEFMessage to a NFCPeer target. The ndefMessage parameter is the NDEFMessage content to send.

The startHandover method initiates pairing with the NFCPeer target. The type parameter is the HandoverType, "bluetooth" or "wifi".

1.6 Interface NDEFMessage

[Constructor(), Constructor(NDEFRecord[] ndefRecords)]
interface NDEFMessage {
    attribute NDEFRecord[] records ;
};

1.7 Interface NDEFRecord

interface NDEFRecord {
};

1.8 Interface NDEFRecordText

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

1.9 Interface NDEFRecordURI

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

1.10 Interface NFCTagDetectCallback

[Callback, NoInterfaceObject] interface NFCTagDetectCallback {
    void onattach(NFCTag nfcTag);
    void ondetach();
};

1.11 Interface NFCPeerDetectCallback

[Callback, NoInterfaceObject] interface NFCPeerDetectCallback {
    void onattach(NFCPeer nfcPeer);
    void ondetach();
};

1.12 Interface NDEFMessageReadCallback

[Callback, NoInterfaceObject] interface NDEFMessageReadCallback {
    void onsuccess(NDEFMessage ndefMessage);
};

References

Acknowledgements

This proposal is based on the Tizen NFC device API. We would like to thank Jaehyun Park and Taehee Lee of Samsung for their work on the API design.