# Modules.Nfc
A cross-platform Near-Field-Communication (NFC) module for iOS and Android. Download the latest release via Github.
# Overview
This module provides access to Near Field Communication (NFC) functionality, allowing applications to read and write (Android-only) NFC tags. A "tag" may actually be another device that appears as a tag.
# NFC Resources
- Android
- iOS
# Requirements
Android
- Android 4.1 (API 16) and later
- An NFC capable device
iOS
- iOS 11 and later
- iPhone 7 / iPhone 7 Plus and later
# Getting Started
- View the Using Titanium Modules (opens new window) document for instructions on getting started with using this module in your application.
# Configure iOS: Capabilities and Provisioning Profiles
Required capabilities:
<key>com.apple.developer.nfc.readersession.formats</key> <array> <string>NDEF</string> </array>
Provisioning Profile entitled with the NFC Tag Reading capability
# Configure Android: Tag Dispatching and Intent Filters
The Android tag dispatch system (opens new window) is responsible for dispatching NFC messages to the appropriate application. In the situation where you are not using foreground dispatching, you will need to define intent-filters in the tiapp.xml file to specify which types of NFC messages the application wants to receive. By using intent-filters in the tiapp.xml file, the application will be automatically started if a matching NFC message is dispatched.
Add code similar to the following to your tiapp.xml file:
Replace occurrences of the activity name (
Tagviewer
) with your activity name.Add the NFC permissions to your Android configuration
Replace the NFC specific intent filters with filters appropriate for your application.
<android xmlns:android="http://schemas.android.com/apk/res/android"> <manifest> <!-- Required NFC permissions --> <uses-permission android:name="android.permission.NFC" /> <uses-feature android:name="android.hardware.nfc" android:required="true" /> <!-- NFC Intent filters --> <application> <activity android:name=".TagviewerActivity" android:label="TagViewer" android:theme="@style/Theme.Titanium" android:configChanges="keyboardHidden|orientation" android:exported="true"> <intent-filter> <action android:name="android.nfc.action.TECH_DISCOVERED"/> <category android:name="android.intent.category.DEFAULT"/> </intent-filter> <intent-filter> <action android:name="android.nfc.action.NDEF_DISCOVERED"/> <category android:name="android.intent.category.DEFAULT"/> <data android:mimeType="text/plain" /> </intent-filter> <intent-filter> <action android:name="android.nfc.action.TAG_DISCOVERED"/> <category android:name="android.intent.category.DEFAULT"/> </intent-filter> </activity> </application> </manifest> </android>
Note that if you are using foreground dispatching (opens new window) you do not need to define intent filters in the application's tiapp.xml file.
# Accessing the Module
Use
require
to access this module from JavaScript:var nfc = require('ti.nfc');
The
nfc
variable is a reference to the Module object.
# Creating an Adapter
The NFC adapter gives you access to the features of the NFC device. The NFC adapter proxy is always associated with the activity that was the current activity when it was created. Therefore, the NFC Adapter should be created after the activity has been opened. You can use the window
open
event to know when the activity has been opened.$.index.addEventListener('open', function(e) { nfcAdapter = nfc.createNfcAdapter({ onNdefDiscovered: handleDiscovery, onTagDiscovered: handleDiscovery, // Android-only onTechDiscovered: handleDiscovery // Android-only }); if (!nfcAdapter.isEnabled()) { Ti.API.error('NFC is not enabled on this device!'); return; } });
# Handling Intents (Android)
NFC Intents are dispatched to an activity by the Android tag dispatch system. When your activity receives a new intent, it must forward the intent to the
onNewIntent
method of the NFC adapter for processing.Ti.Android.currentActivity.addEventListener('newintent', function (e) { nfcAdapter.onNewIntent(e.intent); });
If your application is started as the result of an NFC intent, that intent will automatically be processed when the NFC module is loaded.
# Foreground Dispatch
The foreground dispatch system allows an activity to intercept an intent and claim priority over other activities that handle the same intent. When using foreground dispatching, you must process the
pause
andresume
events on the activity and enable or disable foreground dispatching.var currentActivity = Ti.Android.currentActivity; currentActivity.addEventListener('resume', function(e) { nfcAdapter.enableForegroundDispatch(dispatchFilter); }); currentActivity.addEventListener('pause', function(e) { nfcAdapter.disableForegroundDispatch(); });
# Example applications
Android example applications are located in the
example/android
folder of the module:TagBeam
demonstrates how to use Android Beam to send messages to another NFC capable device.TagForeground
demonstrates how to read NFC tags only when the application is in the foreground.TagViewer
demonstrates how to receive NFC tag intents even when the application is not running.TagWriter
demonstrates how to write to an NFC tag using the Ndef tag technology data format.
iOS example applications are located in the
example/ios
folder of the module:TagViewer
demonstrates how to receive NFC tags even when the application is running.
# Examples
# Creating NFC Adapter (iOS & Android)
This example demonstrates the proper technique for creating an NFC adapter. The NFC Adapter should be created after the window has been opened.
var nfc = require('ti.nfc');
var nfcAdapter = null;
$.index.addEventListener('open', function(e) {
// Must wait until the activity has been opened before setting up NFC
// Create the NFC adapter to be associated with this activity.
// There should only be ONE adapter created per activity.
nfcAdapter = nfc.createNfcAdapter({
onNdefDiscovered: handleDiscovery,
onTagDiscovered: handleDiscovery, // Android-only
onTechDiscovered: handleDiscovery // Android-only
});
// It's possible that the device does not support NFC. Check it here
// before we go any further. For iOS, right now this is decided
// internally by the system.
if (OS_ANDROID) {
if (!nfcAdapter.isEnabled()) {
alert('NFC is not enabled on this device');
return;
}
Ti.Android.currentActivity.addEventListener('newintent', function (e) {
nfcAdapter.onNewIntent(e.intent);
});
// iOS needs to be told to scan
} else if (OS_IOS) {
nfcAdapter.begin();
}
});
function handleDiscovery(e) {
alert(JSON.stringify(e, null, 2));
}
$.index.open();
# Properties
# apiName READONLY
The name of the API that this proxy corresponds to.
The value of this property is the fully qualified name of the API. For example, Titanium.UI.Button
returns Ti.UI.Button
.
# lifecycleContainer
The Window or TabGroup whose Activity lifecycle should be triggered on the proxy.
If this property is set to a Window or TabGroup, then the corresponding Activity lifecycle event callbacks will also be called on the proxy. Proxies that require the activity lifecycle will need this property set to the appropriate containing Window or TabGroup.
# Methods
# createMifareTagTechnology
Creates and returns an instance of Modules.Nfc.MifareTagTechnology.
Parameters
Name | Type | Description |
---|---|---|
parameters | Dictionary<Modules.Nfc.MifareTagTechnology> | Properties to set on a new object, including any defined by Modules.Nfc.MifareTagTechnology except those marked not-creation or read-only. |
Returns
# createNativeTagTechnology
Creates and returns an instance of Modules.Nfc.NativeTagTechnology.
Parameters
Name | Type | Description |
---|---|---|
parameters | Dictionary<Modules.Nfc.NativeTagTechnology> | Properties to set on a new object, including any defined by Modules.Nfc.NativeTagTechnology except those marked not-creation or read-only. |
Returns
# createNdefMessage
Creates and returns an instance of Modules.Nfc.NdefMessage.
Parameters
Name | Type | Description |
---|---|---|
parameters | Dictionary<Modules.Nfc.NdefMessage> | Properties to set on a new object, including any defined by Modules.Nfc.NdefMessage except those marked not-creation or read-only. |
Returns
# createNdefRecordApplication
Creates and returns an instance of Modules.Nfc.NdefRecordApplication.
Parameters
Name | Type | Description |
---|---|---|
parameters | Dictionary<Modules.Nfc.NdefRecordApplication> | Properties to set on a new object, including any defined by Modules.Nfc.NdefRecordApplication except those marked not-creation or read-only. |
Returns
# createNdefRecordEmpty
Creates and returns an instance of Modules.Nfc.NdefRecordEmpty.
Parameters
Name | Type | Description |
---|---|---|
parameters | Dictionary<Modules.Nfc.NdefRecordEmpty> | Properties to set on a new object, including any defined by Modules.Nfc.NdefRecordEmpty except those marked not-creation or read-only. |
Returns
# createNdefRecordExternal
Creates and returns an instance of Modules.Nfc.NdefRecordExternal.
Parameters
Name | Type | Description |
---|---|---|
parameters | Dictionary<Modules.Nfc.NdefRecordExternal> | Properties to set on a new object, including any defined by Modules.Nfc.NdefRecordExternal except those marked not-creation or read-only. |
Returns
# createNdefRecordMedia
Creates and returns an instance of Modules.Nfc.NdefRecordMedia.
Parameters
Name | Type | Description |
---|---|---|
parameters | Dictionary<Modules.Nfc.NdefRecordMedia> | Properties to set on a new object, including any defined by Modules.Nfc.NdefRecordMedia except those marked not-creation or read-only. |
Returns
# createNdefRecordSmartPoster
Creates and returns an instance of Modules.Nfc.NdefRecordSmartPoster.
Parameters
Name | Type | Description |
---|---|---|
parameters | Dictionary<Modules.Nfc.NdefRecordSmartPoster> | Properties to set on a new object, including any defined by Modules.Nfc.NdefRecordSmartPoster except those marked not-creation or read-only. |
Returns
# createNdefRecordText
Creates and returns an instance of Modules.Nfc.NdefRecordText.
Parameters
Name | Type | Description |
---|---|---|
parameters | Dictionary<Modules.Nfc.NdefRecordText> | Properties to set on a new object, including any defined by Modules.Nfc.NdefRecordText except those marked not-creation or read-only. |
Returns
# createNdefRecordUnknown
Creates and returns an instance of Modules.Nfc.NdefRecordUnknown.
Parameters
Name | Type | Description |
---|---|---|
parameters | Dictionary<Modules.Nfc.NdefRecordUnknown> | Properties to set on a new object, including any defined by Modules.Nfc.NdefRecordUnknown except those marked not-creation or read-only. |
Returns
# createNdefRecordUri
Creates and returns an instance of Modules.Nfc.NdefRecordUri.
Parameters
Name | Type | Description |
---|---|---|
parameters | Dictionary<Modules.Nfc.NdefRecordUri> | Properties to set on a new object, including any defined by Modules.Nfc.NdefRecordUri except those marked not-creation or read-only. |
Returns
# createNfcAdapter
Creates and returns an instance of Modules.Nfc.NfcAdapter.
Parameters
Name | Type | Description |
---|---|---|
parameters | Dictionary<Modules.Nfc.NfcAdapter> | Properties to set on a new object, including any defined by Modules.Nfc.NfcAdapter except those marked not-creation or read-only. |
Returns
# createNfcForegroundDispatchFilter
Creates and returns an instance of Modules.Nfc.NfcForegroundDispatchFilter.
Parameters
Name | Type | Description |
---|---|---|
parameters | Dictionary<Modules.Nfc.NfcForegroundDispatchFilter> | Properties to set on a new object, including any defined by Modules.Nfc.NfcForegroundDispatchFilter except those marked not-creation or read-only. |
Returns
# createTagTechnologyIsoDep
Creates and returns an instance of Modules.Nfc.TagTechnologyIsoDep.
Parameters
Name | Type | Description |
---|---|---|
parameters | Dictionary<Modules.Nfc.TagTechnologyIsoDep> | Properties to set on a new object, including any defined by Modules.Nfc.TagTechnologyIsoDep except those marked not-creation or read-only. |
Returns
# createTagTechnologyMifareClassic
Creates and returns an instance of Modules.Nfc.TagTechnologyMifareClassic.
Parameters
Name | Type | Description |
---|---|---|
parameters | Dictionary<Modules.Nfc.TagTechnologyMifareClassic> | Properties to set on a new object, including any defined by Modules.Nfc.TagTechnologyMifareClassic except those marked not-creation or read-only. |
Returns
# createTagTechnologyMifareUltralight
Creates and returns an instance of Modules.Nfc.TagTechnologyMifareUltralight.
Parameters
Name | Type | Description |
---|---|---|
parameters | Dictionary<Modules.Nfc.TagTechnologyMifareUltralight> | Properties to set on a new object, including any defined by Modules.Nfc.TagTechnologyMifareUltralight except those marked not-creation or read-only. |
Returns
# createTagTechnologyNdef
Creates and returns an instance of Modules.Nfc.TagTechnologyNdef.
Parameters
Name | Type | Description |
---|---|---|
parameters | Dictionary<Modules.Nfc.TagTechnologyNdef> | Properties to set on a new object, including any defined by Modules.Nfc.TagTechnologyNdef except those marked not-creation or read-only. |
Returns
# createTagTechnologyNdefFormatable
Creates and returns an instance of Modules.Nfc.TagTechnologyNdefFormatable.
Parameters
Name | Type | Description |
---|---|---|
parameters | Dictionary<Modules.Nfc.TagTechnologyNdefFormatable> | Properties to set on a new object, including any defined by Modules.Nfc.TagTechnologyNdefFormatable except those marked not-creation or read-only. |
Returns
# createTagTechnologyNfcA
Creates and returns an instance of Modules.Nfc.TagTechnologyNfcA.
Parameters
Name | Type | Description |
---|---|---|
parameters | Dictionary<Modules.Nfc.TagTechnologyNfcA> | Properties to set on a new object, including any defined by Modules.Nfc.TagTechnologyNfcA except those marked not-creation or read-only. |
Returns
# createTagTechnologyNfcB
Creates and returns an instance of Modules.Nfc.TagTechnologyNfcB.
Parameters
Name | Type | Description |
---|---|---|
parameters | Dictionary<Modules.Nfc.TagTechnologyNfcB> | Properties to set on a new object, including any defined by Modules.Nfc.TagTechnologyNfcB except those marked not-creation or read-only. |
Returns
# createTagTechnologyNfcF
Creates and returns an instance of Modules.Nfc.TagTechnologyNfcF.
Parameters
Name | Type | Description |
---|---|---|
parameters | Dictionary<Modules.Nfc.TagTechnologyNfcF> | Properties to set on a new object, including any defined by Modules.Nfc.TagTechnologyNfcF except those marked not-creation or read-only. |
Returns
# createTagTechnologyNfcV
Creates and returns an instance of Modules.Nfc.TagTechnologyNfcV.
Parameters
Name | Type | Description |
---|---|---|
parameters | Dictionary<Modules.Nfc.TagTechnologyNfcV> | Properties to set on a new object, including any defined by Modules.Nfc.TagTechnologyNfcV except those marked not-creation or read-only. |
Returns
# Constants
# ACTION_NDEF_DISCOVERED
Intent to start an activity when a tag with NDEF payload is discovered.
# ACTION_TAG_DISCOVERED
Intent to start an activity when a tag is discovered.
# ACTION_TECH_DISCOVERED
Intent to start an activity when a tag is discovered and activities are registered for the specific technologies on the tag.
# COMMAND_CONFIGURATION_ERROR_INVALID_PARAMETERS
The tag has been configured with invalid parameters.
# ENCODING_UTF16
Used with ndefRecord records.
Indicates UTF-16 text encoding.
# ERROR_SECURITY_VIOLATION
A security violation associated with the reader session has occurred.
# ERROR_UNSUPPORTED_FEATURE
The reader session does not support this feature.
# INVALIDATION_ERROR_FIRST_NDEF_TAG_READ
The first NDEF tag read by this session is invalid.
# INVALIDATION_ERROR_SESSION_TERMINATED_UNEXPECTEDLY
The reader session terminated unexpectedly.
# INVALIDATION_ERROR_SESSION_TIMEOUT
The reader session timed out.
# INVALIDATION_ERROR_SYSTEM_IS_BUSY
The reader session failed because the system is busy.
# INVALIDATION_ERROR_USER_CANCELED
The user canceled the reader session.
# MIFARE_BLOCK_SIZE
Used with TECH_MIFARE_CLASSIC tag technology. Size of a MIFARE CLassic block (in bytes).
# MIFARE_SIZE_1K
Used with TECH_MIFARE_CLASSIC tag technology. Tag contains 16 sectors, each with 4 blocks.
# MIFARE_SIZE_2K
Used with TECH_MIFARE_CLASSIC tag technology. Tag contains 32 sectors, each with 4 blocks.
# MIFARE_SIZE_4K
Used with TECH_MIFARE_CLASSIC tag technology. Tag contains 40 sectors.
# MIFARE_SIZE_MINI
Used with TECH_MIFARE_CLASSIC tag technology. Tag contains 5 sectors, each with 4 blocks.
# MIFARE_TAG_TYPE_CLASSIC
Used with TECH_MIFARE_CLASSIC tag technology. A MIFARE Classic tag.
# MIFARE_TAG_TYPE_PLUS
Used with TECH_MIFARE_CLASSIC tag technology. A MIFARE Plus tag.
# MIFARE_TAG_TYPE_PRO
Used with TECH_MIFARE_CLASSIC tag technology. A MIFARE Pro tag.
# MIFARE_TAG_TYPE_UNKNOWN
Used with TECH_MIFARE_CLASSIC tag technology. A MIFARE Classic compatible card of unknown type.
# MIFARE_ULTRALIGHT_PAGE_SIZE
Used with TECH_MIFARE_ULTRALIGHT tag technology. Size of a MIFARE Ultralight page (in bytes).
# MIFARE_ULTRALIGHT_TYPE_ULTRALIGHT
Used with TECH_MIFARE_ULTRALIGHT tag technology. A MIFARE Ultralight tag.
# MIFARE_ULTRALIGHT_TYPE_ULTRALIGHT_C
Used with TECH_MIFARE_ULTRALIGHT tag technology. A MIFARE Ultralight C tag.
# MIFARE_ULTRALIGHT_TYPE_UNKNOWN
Used with TECH_MIFARE_ULTRALIGHT tag technology. A MIFARE Ultralight compatible tag of unknown type.
# RECOMMENDED_ACTION_DO_ACTION
Used with NdefSmartPoster records (RTD_SMART_POSTER).
# RECOMMENDED_ACTION_OPEN_FOR_EDITING
Used with NdefSmartPoster records (RTD_SMART_POSTER).
# RECOMMENDED_ACTION_SAVE_FOR_LATER
Used with NdefSmartPoster records (RTD_SMART_POSTER).
# RECOMMENDED_ACTION_UNKNOWN
Used with NdefSmartPoster records (RTD_SMART_POSTER).
# RTD_ALTERNATIVE_CARRIER
Used with ndefRecord records.
RTD Alternative Carrier type. For use with TNF_WELL_KNOWN.
# RTD_HANDOVER_CARRIER
Used with ndefRecord records.
RTD Handover Carrier type. For use with TNF_WELL_KNOWN.
# RTD_HANDOVER_REQUEST
Used with ndefRecord records.
RTD Handover Request type. For use with TNF_WELL_KNOWN.
# RTD_HANDOVER_SELECT
Used with ndefRecord records.
RTD Handover Select type. For use with TNF_WELL_KNOWN.
# RTD_SMART_POSTER
Used with ndefRecord records.
RTD Smart Poster type. For use with TNF_WELL_KNOWN.
# RTD_TEXT
Used with ndefRecord records.
RTD Text type. For use with TNF_WELL_KNOWN.
# TAG_TYPE_MIFARE_CLASSIC
Used with TECH_NDEF tag technology. NDEF on MIFARE Classic.
# TAG_TYPE_NFC_FORUM_TYPE_1
Used with TECH_NDEF tag technology. NFC Forum Tag Type 1.
# TAG_TYPE_NFC_FORUM_TYPE_2
Used with TECH_NDEF tag technology. NFC Forum Tag Type 2.
# TAG_TYPE_NFC_FORUM_TYPE_3
Used with TECH_NDEF tag technology. NFC Forum Tag Type 3.
# TAG_TYPE_NFC_FORUM_TYPE_4
Used with TECH_NDEF tag technology. NFC Forum Tag Type 4.
# TECH_MIFARE_CLASSIC
Available tag technology used with getTechList and AdapterProxy.
# TECH_MIFARE_ULTRALIGHT
Available tag technology used with getTechList and AdapterProxy.
# TECH_NDEFFORMATABLE
Available tag technology used with getTechList and AdapterProxy.
# TNF_ABSOLUTE_URI
Used with ndefRecord records. Indicates the type field contains an absolute-URI BNF construct defined by RFC 3986.
# TNF_EXTERNAL_TYPE
Used with ndefRecord records. Indicates the type field contains an external type name.
# TNF_MIME_MEDIA
Used with ndefRecord records.
Indicates the type field contains a media-type BNF construct, defined by RFC 2046.
# TNF_UNCHANGED
Used with ndefRecord records.
Indicates the payload is an intermediate or final chunk of a chunked NDEF Record.
# TNF_UNKNOWN
Used with ndefRecord records.
Indicates the payload type is unknown.
# TNF_WELL_KNOWN
Used with ndefRecord records.
Indicates the type field contains a well-known RTD type name.
# TRANSCEIVE_ERROR_RETRY_EXCEEDED
Too many retries have occurred.
# TRANSCEIVE_ERROR_TAG_CONNECTION_LOST
Connection to the tag has been lost.
# TRANSCEIVE_ERROR_TAG_RESPONSE_ERROR
The tag has responded with an error.