You’ve created your first NFC app, which acts upon data stored on tags. Wouldn’t it be nice if the phone automatically launches the app when you touch your NFC tag?
This guide explains how to achieve this using Qt Mobility APIs. You need some background knowledge about NDEF messages and records in general to be able to make most out of this guide. To take a deeper dive into the standards covered here, take a look at the specifications at the NFC Forum.
Record Type Names
Each NDEF record has a type name; some are standardized by the NFC Forum for compatibility (e.g., the Smart Poster [urn:nfc:wkt:Sp], URL [urn:nfc:wkt:U], etc.). Every NFC capable phone should be able to handle those well-known types.
You can also read these record types from within your application. However, you can’t register your app to be started when touching a tag that only contains a well-known record — it’s always the phone that handles those (but you can write a browser-plugin to react to specific URLs and use this to open your app, like the FourSquare application for Symbian & MeeGo is doing – read more about the FourSquare app at Jures blog post).
To autostart your app directly when touching a tag, you need to use your own, custom record type.
Your custom type name has to follow a standardized format as well — according to the NFC Forum External Type Name. Like the well-known type, it starts with "urn:nfc", but then continues with the namespace "ext". Afterwards, your type name must contain the domain name of your organization, then a colon, and then your own type name. A complete example:
Note: the first three parts of the type name ("urn:nfc:ext:") are actually encoded in just one byte on the tag. The rest of your name is stored in plain text; with the usually very limited size of the tags, make sure that the name you choose isn’t as long a whole novel.
In addition, you can store any kind of data (payload) for this record on the tag, and usually only your application will be able to understand the contents. For example, a custom record to check in to a social network may contain the ID and the name of the place in the payload.
Handling Custom Type Names
Your app can obviously read and understand your own record type, and it can also be started when the user touches a tag that contains your custom record. But what if the phone doesn’t have your app installed yet?
The solution is elegant: you simply store two records in the NDEF message on the tag. First your own, custom record; then a well-known URL or Smart Poster – for example a link to the Nokia Store, allowing users to download your app. See below for instructions on how to create such a tag.
What happens when you touch the tag is the following: if your app is already installed and registered for your custom record type, it will be started. Otherwise, your custom type will be unknown to the phone, and it’ll ignore your record and proceed and handle the next record — the well-known URL. The phone will take care of this one and send your potential future user to the Nokia Store to download the app.
Now that the basics are in place, let’s take a look at how to register your app to be stared. This is different in Symbian and MeeGo, as it is tightly integrated with the services of the OS. The process is described in detail here: http://doc.qt.nokia.com/qtmobility/qnearfieldmanager.html#automatically-launching-ndef-message-handlers
The ndefheadergen tool mentioned in the docs isn’t shipped with the Qt SDK, but it’s actually not required — it just auto-generates the same few files that you can easily take and adapt from the documentation (linked above) as well. If you’d like to get the tool nevertheless, download the Qt Mobility source code and compile the ndefheadergen project for your desktop OS.
On Symbian, you only need to adapt an XML registration file and ensure that it’s installed together with your project by adding the deployment into your .pro file. Just insert the name of your app, as well as the custom record type name you’ve selected for your application.
Note: the phone needs to be restarted after registering your app in the current Symbian version (see the report). A second small issue is that at the moment the registration doesn’t get fully removed when you uninstall the application again (bug report).
On MeeGo, your app needs to be registered as a service over the D-Bus. To achieve this, two files have to be deployed during installation: a bus configuration file as well as a service file. For the phone to find your app and its icon, the name of the .desktop file has to be %APPNAME%.desktop (and not %APPNAME%_harmattan.desktop, as is the default file name from Qt Creator). As the last step, you have to add a .postinst and a .prerm file to your debian package — these files contain scripts that are executed when the app is installed or removed from the phone and register your app over the D-Bus with the service.
Note: you need to have PR 1.1+ installed on your N9 for autostart to work; the PR 1.0 firmware didn’t handle NFC tags, and consequently also no custom autostarts.
In case your application doesn’t use the registerNdefMessageHandler() method of the QNearFieldManager already, you need to call this method on application startup as well, so that your app registers at runtime to handle the message.
Writing a Custom Record Type to an NFC Tag
If your app doesn’t support writing its own tags, you can use any of the more customizable tag writing apps to create your own custom tags. For example, use the Nfc Interactor to write a "Combination Tag", which consists of a custom record type name that you can define, plus a URL record. Or, use the "Custom Tag" function to only write your custom record type to the tag, without an additional standardized URL record.
NFC Autostart Example Application
If you’d like to see autostart on tag-touch in action, simply install the Nfc Corkboard application (version 1.4.0+). It works on MeeGo and Symbian (don’t forget to restart your Symbian phone after installing the app for the autostart feature to work!) and is started when touching a tag that contains a record with the type name: "urn:nfc:ext:nokia.com:nfccorkboard". The app also supports writing its own autostart tag — just swipe to the Wednesday corkboard, and press the red NFC flag of the yellow note "Corkboards Autostart"
You can also use this app as a reference to add autostart functionality to your own app.