Imagine walking a conference floor, having the ability to instantly and effortlessly upload any business card you receive into your Salesforce org as a full blown Contact record. You don't need to open an application on your smartphone and take a QR code picture. You don't need to take a picture of the card and type in the information later. You just tap the business card to your smartphone and it's instantly uploaded into Salesforce.com. With the Force.com Mobile SDK and a near field communications-enabled device, this scenario can be a reality. This article teaches you how to do it today.

Video Overview

To get things started and provide an overview of where we are headed, check out this YouTube video that demonstrates our example scenario.



Now let's get started building this type of app yourself.

Prerequisites

Before starting, you should be familiar with the content on the following pages:

You should also have a basic understanding of vCard data.

Source Code

If you just want to follow along and not get your hands dirty building this yourself, download the source code for my NFC vCard Cloud Loader app, based on Saleforce Mobile SDK.

Introduction to Near Field Communication (NFC)

NFC stands for Near Field Communication. It allows devices to exchange data wirelessly at very short ranges (less than a few centimeters). Devices that can transmit data via NFC are called "tags." Tags can come in varying physical shapes and sizes, such as round stickers, business cards, credit cards, or nametags. They also come in a variety of data sizes, holding as little as a few bytes to up to four Kilobytes or more. As you might expect, the data on tags can be encoded in a variety of formats. That being said, there is one format that is widely used called NDEF (NFC Data Exchange Format). Formatting a tag in NDEF format allows an easy exchange of the tag data with systems that leverage the format. For example, Android devices support the NDEF format and are the easiest format to get started with.

Additional Hardware Requirements

You need to ensure you have a mobile device that supports NFC if you want to execute this application in the wild. For this article, I used a Google Nexus S smartphone. You can get a list of Android NFC phones online by Googling for “NFC Smartphones.” You'll also need some NFC tags to work with. Again, you can Google for NFC tags and get a list of retailers who sell blank or NDEF-formatted tags. I suggest getting the tags NDEF formatted from the retailer as it makes it somewhat easier to encode your data. Also, ensure you review the size of data the NFC tag can hold. Depending on your needs, you might want a tag with more data capacity.

Note that there are some software NFC emulators available for downloading if you don’t have the hardware. I don’t cover the software emulators in this article, but if you’re interested, I’d suggest making a quick Google search to find the software.

Force.com and NFC Mobile Application Architecture

To scan NFC-tagged business cards, I created a Hybrid Android Application using the Force.com Mobile SDK and PhoneGap (AKA Cordova). One great thing about PhoneGap is its plugin architecture. The PhoneGap framework allows developers to create plugins that utilize hardware in a device and return data from those devices to mobile applications HTML via JavaScript. Since NFC is dependent on native API calls to the device, I used an open source NFC PhoneGap plugin created by Don Coleman at Chariot Solutions. You can get the NFC Plugin on his Github site.

Note: You need to use the previous version of the NFC Plugin which is compatible with PhoneGap 1.2 as that is the version the Force.com Mobile SDK is compatible with.

Installing the NFC PhoneGap Plugin

Installing a PhoneGap plugin is a fairly easy and straightforward process. There are only a few things you need to do.

  1. Download the .JAR (phonegap-nfc-android.jar) and JavaScript file (phonegap-nfc.js) for the plugin.
  2. Copy the .JAR file for the Plugin into your application's library folder and ensure the JAR file is on your application's classpath.
  3. Copy the JavaScript file (phonegap-nfc.js) into your application's JavaScript folder.
  4. Update your HTML files to include the plugins JavaScript file.
    1. <script type="text/javascript" src="[view-source:https://dl-web.dropbox.com/get/SalesforceMobileSDK-Android/hybrid/SampleApps/ContactExplorer/assets/www/phonegap-nfc-0.2.0.js phonegap-nfc-0.2.0.js] script>
  5. Update your PhoneGap plugin xml file (plugins.xml) to include the plugin class:
    1. <plugin name="NfcPlugin" value="com.chariotsolutions.nfc.plugin.NfcPlugin"/>
  6. Update your Android Manifest file to allow the application device permission to use NFC:
    1. <uses-permission android:name="android.permission.NFC" />
  7. Optional – Android has a special notification system for NFC tags. The NFC Tag Dispatcher runs in the background of Android and can be configured to automatically start an application once a device scans an NFC tag. This allows your application to instantly fire when an NFC tag is read. To do this, update your Android Manifest with the proper intent tags:
<intent-filter>
  		<action android:name="android.nfc.action.NDEF_DISCOVERED" />
  		<data android:mimeType="text/pg" />
  		<category android:name="android.intent.category.DEFAULT" />
</intent-filter>

That is everything you need to do to configure your workspace and application for NFC. Now, let’s take a look at the application code.

Invoking the NFC Plugin via JavaScript

NFC functionality is event-driven. As such, we need to have our application listen for the NFC tag scans fired from the Android Tag Dispatcher and then execute logic. The NFC PhoneGap Plugin handles the heavy lifting for us for processing the NFC tag read events. We just need to register listeners in our JavaScript to process the callbacks from the NFC Plugin. To do this, we register the NFC listeners for the plugin object inside the device-ready method of PhoneGap:

// When this function is called, PhoneGap has been initialized and is ready to roll 
    function onDeviceReady() {
        SFHybridApp.logToConsole("onDeviceReady: PhoneGap ready");
		//Call getAuthCredentials to get the initial session credentials
        SalesforceOAuthPlugin.getAuthCredentials(salesforceSessionRefreshed, ge-tAuthCredentialsError);

        //register to receive notifications when autoRefreshOnForeground refreshes the sfdc session
        docu-ment.addEventListener("salesforceSessionRefresh",salesforceSessionRefreshed,false);

        //enable buttons
        regLinkClickHandlers();

       //Use the NFC Plugin to configure the NFC Tag Reader Listener 
       nfc.addNdefListener(
		 onNfcRead,
                successNFCRegisterListener,
	   	 errorNFCRegisterListener
		);
		
		regLinkNFCClickHandlers();
        
    }

As you can see above, we specify the callback handler (onNfcRead) to process the tag data returned from the NFC tag. We also have two additional callback methods specified: successNFCRegisterListener and errorNFCRegisterListener. Those methods execute once the listener is successfully register in our JavaScript.

We can specify in our JavaScript how to handle the results of a NFC tag. The code below displays the NFC tag data on the screen when it’s scanned. We also parse the tag data, formatted in vCard format, and store it in a contact variable. This contact variable eventually passes to the Mobile SDK to be inserted into Salesforce.

function onNfcRead(nfcEvent) {
    console.log(JSON.stringify(nfcEvent.tag)); // Debug Output in Console
    clearScreen(); // Clear Previosly Display Tag Info
    var tag = nfcEvent.tag;
    var records = tag.ndefMessage || [],
    display = document.getElementById("tagContents"); //Tag Content HTML Div
    display.appendChild(
        document.createTextNode(
            "Scanned an NDEF tag with " + records.length + " record" + ((re-cords.length === 1) ? "": "s")
        )
    );
    
    // Display Tag Info
    var meta = document.createElement('dl');
    display.appendChild(meta);
        
    if (device.platform.match(/Android/i)) {
        if (tag.id) {
            showProperty(meta, "Id", nfc.bytesToHexString(tag.id));
        }
        var hcard = document.createElement("div");
    	hcard.innerHTML = vCard.initialize(nfc.bytesToString(tag.ndefMessage[0].payload)).to_html();
    	display.appendChild(hcard);
		var vCardVal = vCard.initialize(nfc.bytesToString(tag.ndefMessage[0].payload));
//parse the Tag formatted vCard data into a Javascript Object
		var names = vCardVal.fn.split(" ");//Take Fullname from vCard
		contact.firstName = names[0]; //Put in Firstname for SFDC
		contact.lastName = names[1]; //Put in LastName for SFDC
		for(type in vCardVal.email)
	      {
	        for(n in vCardVal.email['home'])
	        {
	          //Store email in contact variable for SFDC Upsert
                  contact.email = vCardVal.email['home'][n];
	          contact.vCard_Email__c = contact.email;

	        }
	      }
	      for(type in vCardVal.tel)
	      {
	        for(n in vCardVal.tel[type])
	        {
                  //Store Telephone Info in variable for SFDC Upsert
	          contact.phone = vCardVal.tel[type][n];
	        }
	      }	      
    	meta.appendChild(hcard);
    }


    navigator.notification.vibrate(100);
    
}


As you can see in the above code, the JavaScript processes the returned NDEF tag payload from the NFC plugin. We parse the tag information, formatted in vCard format, and append it to our DOM. The information then renders on the screen to the user. If you are unfamiliar with vCard formatted data, it is basically a way to electronically represent widely-used business card data. For more information about vCard, read this article.

Upserting the Information into Force.com with Mobile SDK

Now that we have successfully scanned the tag, we can do a variety of things with the data. In this sample application, we are going to upsert the contact information into the standard Contact object using the Mobile SDK. The method for upserting data is inside the forcetk.js file, which utilizes the Force.com REST API to process data. We use the contact variable we populated in our NFC processing code above as the input into Force.com. Finally, the user initiates the upload into Force.com by clicking the button on the page, although we can easily automate this on the read success method above to make this completely automatic.

$j('#insert_lead_from_nfc_tag').click(function(){
                                          SFHybridApp.logToConsole("Upsert vCard Contact to SFDC " + contact.vCard_Email__c + contact.lastName + contact.phone);
                                         forcetkCli-ent.upsert("Contact","Contact_Ext_ID__c",contact.contactextid,contact,onSuccessSfdcUpsertContact,onErrorSfdc);
                                         });

After following this use case through completely, if we navigate to the Contacts tab in Force.com and view the recently-added Contacts, we can see the newly-created contact from our NFC tag!

Wrap Up - The Internet of Things and the Future of NFC

As you can see from this simple application, using NFC tags and smartphones opens up a whole world of possibilities for The Internet of Things. For those unfamiliar with the concept, it boils down to real-world objects representing themselves automatically on the Internet. For example, the business card had an NFC tag attached to it, and via our application, automatically communicated its data to our application. This allowed us to easily represent that real-world object in our salesforce.com org. You might be getting the idea now.

You can tag almost anything and track that object in Salesforce. You can tag marketing kiosks to allow users to process leads at a conferencing event. You can setup tags in your business to allow customers to scan products and add them to their shopping lists, or even pay for them automatically via their smartphone, streamlining the whole checkout and purchase process. If you live in the city, like me, and take public transit, imagine replacing the transit card in your pocket with an application on your smartphone. One less thing to worry about losing!

Related Resources


About the Author

Cory Cowgill is a Senior Consultant at West Monroe Partners, a salesforce.com Silver Consulting Partner. As an active member of the Force.com community, he can be found answering questions on the developer boards, at developer meetups, or Twitter (@corycowgill). He also maintains a Force.com blog where he discusses his thoughts on the platform. He is a firm advocate for leveraging the Force.com platform to rapidly develop enterprise applications.