A working example of how to use this module can be found on Github at https://github.com/acktie/Acktie-Mobile-NFC- Example.

This module enables your application to take advantage of the devices NFC capabilites. The purpose is to provide a simplified interface with the Android apis and to access them from the Appcelerator framework. In order to be compatible with as many Android devices as possible, the module was developed for Android 2.3.3 and higher (Version 10). As a result, the newer Jelly Bean (version 16) API are not accessible however the feature to read, write and do P2P messages are available. If you are unfamiliar with NFC, we encourge you the read the documenation on the Android website.

• Android NFC Basics
• Android NFC Advanced

The module was created to take a broad view of NFC and allows you to implement a number of feature in your application. For example:

1. Launch your app when a certain NFC tag is read
2. Read all NFC tags once you are in your app
3. Write a number of different NFC messages See the app.js in the example directory for a working example. We used NFC tags purchased from tagstand for the module development. NOTE: We recommend downloading a NFC read/write application to assist you in your development. It is useful to ensure your tag has the correct type/data. We used NXP Tag writer. NOTE: This module was tested and developed using a Samsung Nexus S (4.0.4) and tested with an LG Optimus Elite (2.3.7). We could not find a good simulator so testing on a device is required.

To get started, review the [module install instructions](http://docs.appcelera tor.com/titanium/2.0/#!/guide/Using_Titanium_Modules) on the Appcelerator website. To access this module from JavaScript, you would do the following:

var nfc = require("com.acktie.mobile.android.nfc"); 

The nfc variable is a reference to the Module object.

The following are the features and Javascript functions you can call with the module.

This section will describe how to modify the AndroidModule.xml via the tiapp.xml to register your application to receive NFC intents. As a result, your application will be launched when your tag is read. The [Android document ation](http://developer.android.com/guide/topics/connectivity/nfc/nfc.html#dis patching) had a good flowchart explaining the NFC tag dispatch system. Read through this section to get an understanding of how it works. Below is an example of how to setup your application to be launched when your tag is read: Lets assume you want your application to be launched when a tag with the mime type of text/plain is read:

1. Use an application like NXP Tag Writer to write plain text data to a tag.
2. Copy and modify (the android:name and android:label with your app data) in example/tiapp.xml (See tiapp.xml in the example directory for detail).
3. Place the modified xml code in your app's tiapp.xml file.
4. Build and Launch on a device. With these steps done your application should be launched when your tag is read. If not, make sure the tag data is text/plain and your AndroidManifest.xml looks correct.

This method is used to initialize the module with user settings.

This property is used to set the mime type for the IntentFilter on incoming intents. Default is / (all mime types).

This method tests to determine if the current intent or passed intent was from an read NFC event. By default the method will check using all the NFC intent actions (ACTION_NDEF_DISCOVERED, ACTION_TECH_DISCOVERED, and ACTION_TAG_DISCOVERED).

If you want the method to only check for a specific intent use this property with one of the follow constants, ACTION_NDEF_DISCOVERED, ACTION_TECH_DISCOVERED, or ACTION_TAG_DISCOVERED.

Check to see if NFC is available and enabled on the device.

Check to see if the module is in write mode.

This method will check the current intent (in the Activity) or a passed in intent to determine if it has any Ndef Messages (NFC data).

The intent to check for the NDef Messages

This method will parse the Ndef messages in current intent (in the Activity) or a passed in intent.

This method will return the parsed Ndef Message (call parse() first).

This method will cancal any enableForegroundDispach call that were made. NOTE: Calls the disableForegroundDispatch method on the NfcAdapter class (See Android Javadocs for more details).

This method will cancal any enableForegroundNdefPush call that were made. NOTE: Calls the disableForegroundNdefPush method on the NfcAdapter class (See Android Javadocs for more details).

This method is used to listen for NFC events. If a tag is read then a PendingIntent is populated and sent to the application calling the newIntent listener. NOTE: Calls the enableForegroundDispatch method on the NfcAdapter class (See Android Javadocs for more details).

If you want the method to only check for a specific intent use this property with one of the follow constants, ACTION_NDEF_DISCOVERED or ACTION_TAG_DISCOVERED.

This method is used to Push a NdefMessage to a tag or another NFC device. NOTE: Calls the enableForegroundNdefPush method on the NfcAdapter class (See Android Javadocs for more details).

Use this option to pass in the Ndefmessge. This is the message that will be received by the tag or device.

This next section describes methods that are used to create NdefMessages. It uses the process described in the [Android Documentation](http://developer.and roid.com/guide/topics/connectivity/nfc/nfc.html#creating-records).

This method will create an NDefMessage of type TNF_WELL_KNOWN and RTD_TEXT. This is mime type of text/plain. Use the output to pass to writeToTag method or enableForegroundNdefPush.

The text string of the message.

The two letter language locale (See JavaDocs locale documenation for examples). Locale.getDefault() (Java code) is used by default.

Whether or not to encode the message using UTF16 encoding. Default is UTF8. Default is false.

The method create a NdefMessage contain a URI.

A URI string

The method create a NdefMessage contain an absolute URI.

An absolute URI string

This method will create a NdefMessage contain a mime type and message.

The mime type string of the message.

A message string

This method will enable the module for tag/P2P write mode.

This boolean is to indicate whether or not to disable the foreground dispatch/push. The default is false. It will disable any outstanding foreground dispatch/push.

This method will disable the tag write mode.

This method will write the passed NdefMessage to the detected tag (from the passed intent) and notify a callback with the results of the write operation.

The NdefMessage to write. This message would be the result of one of the create operations (see above).

This is the intent that was received with the detected tag attached.

The JS function that will be called when the write operation has completed.

The JS function will be passed a dictionary object that will contain the result of the write operation.

• result - A boolean on whether or not the write operation was successful.
• message - If a failure occured, this is the error message

Only 1 NFC device was available for the module development. As a result the P2P functionality was not tested. However, the only method used for the P2P is the enableForegroundNdefPush method (See NfcAdaptor for more info). We have exposed this method so you can use it in your application.

• 1.0: Initial release of NFC Module

Tony Nuzzi @ Acktie Twitter: @Acktie Email: [email protected]

Code licensed under Apache License v2.0, documentation under CC BY 3.0.

Attribution is welcome but not required.