1 page.title=NFC Basics 2 @jd:body 3 4 5 <div id="qv-wrapper"> 6 <div id="qv"> 7 <h2>In this document</h2> 8 <ol> 9 <li><a href="#tag-dispatch">The Tag Dispatch System</a> 10 <ol> 11 <li><a href="#ndef">How NFC tags are mapped to MIME types and URIs</a></li> 12 <li><a href="#dispatching">How NFC Tags are Dispatched to Applications</a></li> 13 </ol> 14 </li> 15 <li><a href="#manifest">Requesting NFC Access in the Android Manifest</a></li> 16 <li><a href="#filtering-intents">Filtering for Intents</a> 17 <ol> 18 <li><a href="#ndef-disc">ACTION_NDEF_DISCOVERED</a></li> 19 <li><a href="#tech-disc">ACTION_TECH_DISCOVERED</a></li> 20 <li><a href="#tag-disc">ACTION_TAG_DISCOVERED</a></li> 21 <li><a href="#obtain-info">Obtaining information from intents</a></li> 22 </ol> 23 </li> 24 <li><a href="#creating-records">Creating Common Types of NDEF Records</a> 25 <ol> 26 <li><a href="#abs-uri">TNF_ABSOLUTE_URI</a></li> 27 <li><a href="#mime">TNF_MIME_MEDIA</a></li> 28 <li><a href="#well-known-text">TNF_WELL_KNOWN with RTD_TEXT</a></li> 29 <li><a href="#well-known-uri">TNF_WELL_KNOWN with RTD_URI</a></li> 30 <li><a href="#ext-type">TNF_EXTERNAL_TYPE</a></li> 31 <li><a href="#aar">Android Application Records</a></li> 32 </ol> 33 </li> 34 <li><a href="#p2p">Beaming NDEF Messages to Other Devices</a></li> 35 </ol> 36 </div> 37 </div> 38 39 <p>This document describes the basic NFC tasks you perform in Android. It explains how to send and 40 receive NFC data in the form of NDEF messages and describes the Android framework APIs that support 41 these features. For more advanced topics, including a discussion of working with non-NDEF data, 42 see <a href="{@docRoot}guide/topics/connectivity/nfc/advanced-nfc.html">Advanced NFC</a>.</p> 43 44 45 <p>There are two major uses cases when working with NDEF data and Android:</p> 46 47 <ul> 48 <li>Reading NDEF data from an NFC tag</li> 49 <li>Beaming NDEF messages from one device to another with <a href="#p2p">Android 50 Beam™</a></li> 51 </ul> 52 53 54 <p>Reading NDEF data from an NFC tag is handled with the <a href="#tag-dispatch">tag dispatch 55 system</a>, which analyzes discovered NFC tags, appropriately categorizes the data, and starts 56 an application that is interested in the categorized data. An application that wants to handle the 57 scanned NFC tag can <a href="#filtering-intents">declare an intent filter</a> and 58 request to handle the data.</p> 59 60 <p>The Android Beam™ feature allows a device to push an NDEF message onto 61 another device by physically tapping the devices together. This interaction provides an easier way 62 to send data than other wireless technologies like Bluetooth, because with NFC, no manual device 63 discovery or pairing is required. The connection is automatically started when two devices come 64 into range. Android Beam is available through a set of NFC APIs, so any application can transmit 65 information between devices. For example, the Contacts, Browser, and YouTube applications use 66 Android Beam to share contacts, web pages, and videos with other devices. 67 </p> 68 69 70 <h2 id="tag-dispatch">The Tag Dispatch System</h2> 71 72 <p>Android-powered devices are usually looking for NFC tags when the screen 73 is unlocked, unless NFC is disabled in the device's Settings menu. 74 When an Android-powered device discovers an NFC tag, the desired behavior 75 is to have the most appropriate activity handle the intent without asking the user what application 76 to use. Because devices scan NFC tags at a very short range, it is likely that making users manually 77 select an activity would force them to move the device away from the tag and break the connection. 78 You should develop your activity to only handle the NFC tags that your activity cares about to 79 prevent the Activity Chooser from appearing.</p> 80 81 <p>To help you with this goal, Android provides a special tag dispatch system that analyzes scanned 82 NFC tags, parses them, and tries to locate applications that are interested in the scanned data. It 83 does this by:</p> 84 85 <ol> 86 <li>Parsing the NFC tag and figuring out the MIME type or a URI that identifies the data payload 87 in the tag.</li> 88 <li>Encapsulating the MIME type or URI and the payload into an intent. These first two 89 steps are described in <a href="#ndef">How NFC tags are mapped to MIME types and URIs</a>.</li> 90 <li>Starts an activity based on the intent. This is described in 91 <a href="#dispatching">How NFC Tags are Dispatched to Applications</a>.</li> 92 </ol> 93 94 <h3 id="ndef">How NFC tags are mapped to MIME types and URIs</h3> 95 <p>Before you begin writing your NFC applications, it is important to understand the different 96 types of NFC tags, how the tag dispatch system parses NFC tags, and the special work that the tag 97 dispatch system does when it detects an NDEF message. NFC tags come in a 98 wide array of technologies and can also have data written to them in many different ways. 99 Android has the most support for the NDEF standard, which is defined by the <a 100 href="http://www.nfc-forum.org/home">NFC Forum</a>. 101 </p> 102 103 <p>NDEF data is encapsulated inside a message ({@link android.nfc.NdefMessage}) that contains one 104 or more records ({@link android.nfc.NdefRecord}). Each NDEF record must be well-formed according to 105 the specification of the type of record that you want to create. Android 106 also supports other types of tags that do not contain NDEF data, which you can work with by using 107 the classes in the {@link android.nfc.tech} package. To learn more 108 about these technologies, see the <a href="{@docRoot}guide/topics/connectivity/nfc/advanced-nfc.html">Advanced 109 NFC</a> topic. Working with these other types of tags involves 110 writing your own protocol stack to communicate with the tags, so we recommend using NDEF when 111 possible for ease of development and maximum support for Android-powered devices. 112 </p> 113 114 <p class="note"><strong>Note:</strong> 115 To download complete NDEF specifications, go to the <a 116 href="http://www.nfc-forum.org/specs/spec_license">NFC Forum Specification Download</a> site and see 117 <a href="#creating-records">Creating common types of NDEF records</a> for examples of how to 118 construct NDEF records. </p> 119 120 <p>Now that you have some background in NFC tags, the following sections describe in more detail how 121 Android handles NDEF formatted tags. When an Android-powered device scans an NFC tag containing NDEF 122 formatted data, it parses the message and tries to figure out the data's MIME type or identifying 123 URI. To do this, the system reads the first {@link android.nfc.NdefRecord} inside the {@link 124 android.nfc.NdefMessage} to determine how to interpret the entire NDEF message (an NDEF message can 125 have multiple NDEF records). In a well-formed NDEF message, the first {@link android.nfc.NdefRecord} 126 contains the following fields: 127 <dl> 128 <dt><strong>3-bit TNF (Type Name Format)</strong></dt> 129 <dd>Indicates how to interpret the variable length type field. Valid values are described in 130 described in <a href="#table1">Table 1</a>.</dd> 131 132 <dt><strong>Variable length type</strong></dt> 133 <dd>Describes the type of the record. If using {@link android.nfc.NdefRecord#TNF_WELL_KNOWN}, use 134 this field to specify the Record Type Definition (RTD). Valid RTD values are described in <a 135 href="#table2">Table 2</a>.</dd> 136 137 <dt><strong>Variable length ID</strong></dt> 138 <dd>A unique identifier for the record. This field is not used often, but 139 if you need to uniquely identify a tag, you can create an ID for it.</dd> 140 141 <dt><strong>Variable length payload</strong></dt> 142 <dd>The actual data payload that you want to read or write. An NDEF 143 message can contain multiple NDEF records, so don't assume the full payload is in the first NDEF 144 record of the NDEF message.</dd> 145 146 </dl> 147 148 <p>The tag dispatch system uses the TNF and type fields to try to map a MIME type or URI to the 149 NDEF message. If successful, it encapsulates that information inside of a {@link 150 android.nfc.NfcAdapter#ACTION_NDEF_DISCOVERED} intent along with the actual payload. However, there 151 are cases when the tag dispatch system cannot determine the type of data based on the first NDEF 152 record. This happens when the NDEF data cannot be mapped to a MIME type or URI, or when the 153 NFC tag does not contain NDEF data to begin with. In such cases, a {@link 154 android.nfc.Tag} object that has information about the tag's technologies and the payload are 155 encapsulated inside of a {@link android.nfc.NfcAdapter#ACTION_TECH_DISCOVERED} intent instead.</p> 156 157 <p> 158 <a href="#table1">Table 1.</a> describes how the tag dispatch system maps TNF and type 159 fields to MIME types or URIs. It also describes which TNFs cannot be mapped to a MIME type or URI. 160 In these cases, the tag dispatch system falls back to 161 {@link android.nfc.NfcAdapter#ACTION_TECH_DISCOVERED}. 162 163 <p>For example, if the tag dispatch system encounters a record of type {@link 164 android.nfc.NdefRecord#TNF_ABSOLUTE_URI}, it maps the variable length type field of that record 165 into a URI. The tag dispatch system encapsulates that URI in the data field of an {@link 166 android.nfc.NfcAdapter#ACTION_NDEF_DISCOVERED} intent along with other information about the tag, 167 such as the payload. On the other hand, if it encounters a record of type {@link 168 android.nfc.NdefRecord#TNF_UNKNOWN}, it creates an intent that encapsulates the tag's technologies 169 instead.</p> 170 171 172 <p class="table-caption" id="table1"> 173 <strong>Table 1.</strong> Supported TNFs and their mappings</p> 174 <table id="mappings"> 175 <tr> 176 <th>Type Name Format (TNF)</th> 177 <th>Mapping</th> 178 </tr> 179 <tr> 180 <td>{@link android.nfc.NdefRecord#TNF_ABSOLUTE_URI}</td> 181 <td>URI based on the type field.</td> 182 </tr> 183 <td>{@link android.nfc.NdefRecord#TNF_EMPTY}</td> 184 <td>Falls back to {@link android.nfc.NfcAdapter#ACTION_TECH_DISCOVERED}.</td> 185 </tr> 186 <td>{@link android.nfc.NdefRecord#TNF_EXTERNAL_TYPE}</td> 187 <td>URI based on the URN in the type field. The URN is encoded into the NDEF type field in 188 a shortened form: <code><em><domain_name>:<service_name></em></code>. 189 Android maps this to a URI in the form: 190 <code>vnd.android.nfc://ext/<em><domain_name>:<service_name></em></code>.</td> 191 </tr> 192 <td>{@link android.nfc.NdefRecord#TNF_MIME_MEDIA}</td> 193 <td>MIME type based on the type field.</td> 194 </tr> 195 <td>{@link android.nfc.NdefRecord#TNF_UNCHANGED}</td> 196 <td>Invalid in the first record, so falls back to 197 {@link android.nfc.NfcAdapter#ACTION_TECH_DISCOVERED}.</td> 198 </tr> 199 <td>{@link android.nfc.NdefRecord#TNF_UNKNOWN}</td> 200 <td>Falls back to {@link android.nfc.NfcAdapter#ACTION_TECH_DISCOVERED}.</td> 201 </tr> 202 <td>{@link android.nfc.NdefRecord#TNF_WELL_KNOWN}</td> 203 <td>MIME type or URI depending on the Record Type Definition (RTD), which you set in the 204 type field. See <a href="#well_known">Table 2.</a> for more information on 205 available RTDs and their mappings.</td> 206 </tr> 207 </table> 208 209 <p class="table-caption" id="table2"> 210 <strong>Table 2.</strong> Supported RTDs for TNF_WELL_KNOWN and their 211 mappings</p> 212 <table id="well-known"> 213 <tr> 214 <th>Record Type Definition (RTD)</th> 215 <th>Mapping</th> 216 </tr> 217 <tr> 218 <td>{@link android.nfc.NdefRecord#RTD_ALTERNATIVE_CARRIER}</td> 219 <td>Falls back to {@link android.nfc.NfcAdapter#ACTION_TECH_DISCOVERED}.</td> 220 </tr> 221 <td>{@link android.nfc.NdefRecord#RTD_HANDOVER_CARRIER}</td> 222 <td>Falls back to {@link android.nfc.NfcAdapter#ACTION_TECH_DISCOVERED}.</td> 223 </tr> 224 <td>{@link android.nfc.NdefRecord#RTD_HANDOVER_REQUEST}</td> 225 <td>Falls back to {@link android.nfc.NfcAdapter#ACTION_TECH_DISCOVERED}.</td> 226 </tr> 227 <td>{@link android.nfc.NdefRecord#RTD_HANDOVER_SELECT}</td> 228 <td>Falls back to {@link android.nfc.NfcAdapter#ACTION_TECH_DISCOVERED}.</td> 229 </tr> 230 <td>{@link android.nfc.NdefRecord#RTD_SMART_POSTER}</td> 231 <td>URI based on parsing the payload.</td> 232 </tr> 233 <td>{@link android.nfc.NdefRecord#RTD_TEXT}</td> 234 <td>MIME type of <code>text/plain</code>.</td> 235 </tr> 236 <td>{@link android.nfc.NdefRecord#RTD_URI}</td> 237 <td>URI based on payload.</td> 238 </tr> 239 </table> 240 241 <h3 id="dispatching">How NFC Tags are Dispatched to Applications</h3> 242 243 <p>When the tag dispatch system is done creating an intent that encapsulates the NFC tag and its 244 identifying information, it sends the intent to an interested application that 245 filters for the intent. If more than one application can handle the intent, the Activity Chooser 246 is presented so the user can select the Activity. The tag dispatch system defines three intents, 247 which are listed in order of highest to lowest priority:</p> 248 249 <ol> 250 <li> 251 {@link android.nfc.NfcAdapter#ACTION_NDEF_DISCOVERED}: This intent is used to start an 252 Activity when a tag that contains an NDEF payload is scanned and is of a recognized type. This is 253 the highest priority intent, and the tag dispatch system tries to start an Activity with this 254 intent before any other intent, whenever possible. 255 </li> 256 257 <li>{@link android.nfc.NfcAdapter#ACTION_TECH_DISCOVERED}: If no activities register to 258 handle the {@link android.nfc.NfcAdapter#ACTION_NDEF_DISCOVERED} 259 intent, the tag dispatch system tries to start an application with this intent. This 260 intent is also directly started (without starting {@link 261 android.nfc.NfcAdapter#ACTION_NDEF_DISCOVERED} first) if the tag that is scanned 262 contains NDEF data that cannot be mapped to a MIME type or URI, or if the tag does not contain NDEF 263 data but is of a known tag technology. 264 </li> 265 266 <li>{@link android.nfc.NfcAdapter#ACTION_TAG_DISCOVERED}: This intent is started 267 if no activities handle the {@link 268 android.nfc.NfcAdapter#ACTION_NDEF_DISCOVERED} or {@link 269 android.nfc.NfcAdapter#ACTION_TECH_DISCOVERED} 270 intents.</li> 271 </ol> 272 273 <p>The basic way the tag dispatch system works is as follows:</p> 274 275 <ol> 276 <li>Try to start an Activity with the intent that was created by the tag dispatch system 277 when parsing the NFC tag (either 278 {@link android.nfc.NfcAdapter#ACTION_NDEF_DISCOVERED} or {@link 279 android.nfc.NfcAdapter#ACTION_TECH_DISCOVERED}).</li> 280 <li>If no activities filter for that intent, try to start an Activity with the next 281 lowest priority intent (either {@link android.nfc.NfcAdapter#ACTION_TECH_DISCOVERED} or {@link 282 android.nfc.NfcAdapter#ACTION_TAG_DISCOVERED}) until an application filters for the 283 intent or until the tag dispatch system tries all possible intents.</li> 284 <li>If no applications filter for any of the intents, do nothing.</li> 285 </ol> 286 287 <img src="{@docRoot}images/nfc_tag_dispatch.png" /> 288 289 <p class="figure"><strong>Figure 1. </strong> Tag Dispatch System</p> 290 291 292 <p>Whenever possible, work with NDEF messages and the {@link 293 android.nfc.NfcAdapter#ACTION_NDEF_DISCOVERED} intent, because it is the most specific out of 294 the three. This intent allows you to start your application at a more appropriate time than the 295 other two intents, giving the user a better experience.</p> 296 297 <h2 id="manifest">Requesting NFC Access in the Android Manifest</h2> 298 299 <p>Before you can access a device's NFC hardware and properly handle NFC intents, declare these 300 items in your <code>AndroidManifest.xml</code> file:</p> 301 302 <ul> 303 <li>The NFC <code><uses-permission></code> element to access the NFC hardware: 304 <pre> 305 <uses-permission android:name="android.permission.NFC" /> 306 </pre> 307 </li> 308 309 <li>The minimum SDK version that your application can support. API level 9 only supports 310 limited tag dispatch via {@link android.nfc.NfcAdapter#ACTION_TAG_DISCOVERED}, and only gives 311 access to NDEF messages via the {@link android.nfc.NfcAdapter#EXTRA_NDEF_MESSAGES} extra. No 312 other tag properties or I/O operations are accessible. API level 10 313 includes comprehensive reader/writer support as well as foreground NDEF pushing, and API level 314 14 provides an easier way to push NDEF messages to other devices with Android Beam and extra 315 convenience methods to create NDEF records. 316 <pre class="pretty-print"> 317 <uses-sdk android:minSdkVersion="10"/> 318 </pre> 319 </li> 320 321 <li>The <code>uses-feature</code> element so that your application shows up in Google 322 Play only for devices that have NFC hardware: 323 <pre> 324 <uses-feature android:name="android.hardware.nfc" android:required="true" /> 325 </pre> 326 <p>If your application uses NFC functionality, but that functionality is not crucial to your 327 application, you can omit the <code>uses-feature</code> element and check for NFC avalailbility at 328 runtime by checking to see if {@link android.nfc.NfcAdapter#getDefaultAdapter getDefaultAdapter()} 329 is <code>null</code>.</p> 330 </li> 331 </ul> 332 333 <h2 id="filtering-intents">Filtering for NFC Intents</h2> 334 335 <p>To start your application when an NFC tag that you want to handle is scanned, your application 336 can filter for one, two, or all three of the NFC intents in the Android manifest. However, you 337 usually want to filter for the {@link android.nfc.NfcAdapter#ACTION_NDEF_DISCOVERED} intent for the 338 most control of when your application starts. The {@link 339 android.nfc.NfcAdapter#ACTION_TECH_DISCOVERED} intent is a fallback for {@link 340 android.nfc.NfcAdapter#ACTION_NDEF_DISCOVERED} when no applications filter for 341 {@link android.nfc.NfcAdapter#ACTION_NDEF_DISCOVERED} or for when the payload is not 342 NDEF. Filtering for {@link android.nfc.NfcAdapter#ACTION_TAG_DISCOVERED} is usually too general of a 343 category to filter on. Many applications will filter for {@link 344 android.nfc.NfcAdapter#ACTION_NDEF_DISCOVERED} or {@link 345 android.nfc.NfcAdapter#ACTION_TECH_DISCOVERED} before {@link 346 android.nfc.NfcAdapter#ACTION_TAG_DISCOVERED}, so your application has a low probability of 347 starting. {@link android.nfc.NfcAdapter#ACTION_TAG_DISCOVERED} is only available as a last resort 348 for applications to filter for in the cases where no other applications are installed to handle the 349 {@link android.nfc.NfcAdapter#ACTION_NDEF_DISCOVERED} or {@link 350 android.nfc.NfcAdapter#ACTION_TECH_DISCOVERED}intent.</p> 351 352 <p>Because NFC tag deployments vary and are many times not under your control, this is not always 353 possible, which is why you can fallback to the other two intents when necessary. When you have 354 control over the types of tags and data written, it is recommended that you use NDEF to format your 355 tags. The following sections describe how to filter for each type of intent.</p> 356 357 358 <h3 id="ndef-disc">ACTION_NDEF_DISCOVERED</h3> 359 <p> 360 To filter for {@link android.nfc.NfcAdapter#ACTION_NDEF_DISCOVERED} intents, declare the 361 intent filter along with the type of data that you want to filter for. The 362 following example filters for {@link android.nfc.NfcAdapter#ACTION_NDEF_DISCOVERED} 363 intents with a MIME type of <code>text/plain</code>: 364 </p> 365 <pre> 366 <intent-filter> 367 <action android:name="android.nfc.action.NDEF_DISCOVERED"/> 368 <category android:name="android.intent.category.DEFAULT"/> 369 <data android:mimeType="text/plain" /> 370 </intent-filter> 371 </pre> 372 <p>The following example filters for a URI in the form of 373 <code>http://developer.android.com/index.html</code>. 374 <pre> 375 <intent-filter> 376 <action android:name="android.nfc.action.NDEF_DISCOVERED"/> 377 <category android:name="android.intent.category.DEFAULT"/> 378 <data android:scheme="http" 379 android:host="developer.android.com" 380 android:pathPrefix="/index.html" /> 381 </intent-filter> 382 </pre> 383 384 385 <h3 id="tech-disc">ACTION_TECH_DISCOVERED</h3> 386 387 <p>If your activity filters for the {@link android.nfc.NfcAdapter#ACTION_TECH_DISCOVERED} intent, 388 you must create an XML resource file that specifies the technologies that your activity supports 389 within a <code>tech-list</code> set. Your activity is 390 considered a match if a <code>tech-list</code> set is a subset of the technologies that are 391 supported by the tag, which you can obtain by calling {@link android.nfc.Tag#getTechList 392 getTechList()}.</p> 393 394 <p>For example, if the tag that is scanned supports MifareClassic, NdefFormatable, and NfcA, your 395 <code>tech-list</code> set must specify all three, two, or one of the technologies (and nothing 396 else) in order for your activity to be matched.</p> 397 398 <p>The following sample defines all of the technologies. You can remove the ones that you do not 399 need. Save this file (you can name it anything you wish) in the 400 <code><project-root>/res/xml</code> folder.</p> 401 <pre> 402 <resources xmlns:xliff="urn:oasis:names:tc:xliff:document:1.2"> 403 <tech-list> 404 <tech>android.nfc.tech.IsoDep</tech> 405 <tech>android.nfc.tech.NfcA</tech> 406 <tech>android.nfc.tech.NfcB</tech> 407 <tech>android.nfc.tech.NfcF</tech> 408 <tech>android.nfc.tech.NfcV</tech> 409 <tech>android.nfc.tech.Ndef</tech> 410 <tech>android.nfc.tech.NdefFormatable</tech> 411 <tech>android.nfc.tech.MifareClassic</tech> 412 <tech>android.nfc.tech.MifareUltralight</tech> 413 </tech-list> 414 </resources> 415 </pre> 416 417 <p>You can also specify multiple <code>tech-list</code> sets. Each of the <code>tech-list</code> 418 sets is considered independently, and your activity is considered a match if any single 419 <code>tech-list</code> set is a subset of the technologies that are returned by {@link 420 android.nfc.Tag#getTechList getTechList()}. This provides <code>AND</code> and <code>OR</code> 421 semantics for matching technologies. The following example matches tags that can support the 422 NfcA and Ndef technologies or can support the NfcB and Ndef technologies:</p> 423 <pre> 424 <resources xmlns:xliff="urn:oasis:names:tc:xliff:document:1.2"> 425 <tech-list> 426 <tech>android.nfc.tech.NfcA</tech> 427 <tech>android.nfc.tech.Ndef</tech> 428 </tech-list> 429 </resources> 430 431 <resources xmlns:xliff="urn:oasis:names:tc:xliff:document:1.2"> 432 <tech-list> 433 <tech>android.nfc.tech.NfcB</tech> 434 <tech>android.nfc.tech.Ndef</tech> 435 </tech-list> 436 </resources> 437 </pre> 438 439 <p>In your <code>AndroidManifest.xml</code> file, specify the resource file that you just created 440 in the <code><meta-data></code> element inside the <code><activity></code> 441 element like in the following example:</p> 442 <pre> 443 <activity> 444 ... 445 <intent-filter> 446 <action android:name="android.nfc.action.TECH_DISCOVERED"/> 447 </intent-filter> 448 449 <meta-data android:name="android.nfc.action.TECH_DISCOVERED" 450 android:resource="@xml/nfc_tech_filter" /> 451 ... 452 </activity> 453 </pre> 454 455 <p>For more information about working with tag technologies and the {@link 456 android.nfc.NfcAdapter#ACTION_TECH_DISCOVERED} intent, see <a 457 href="{@docRoot}guide/topics/connectivity/nfc/advanced-nfc.html#tag-tech">Working with Supported Tag 458 Technologies</a> in the Advanced NFC document.</p> 459 <h3 id="tag-disc">ACTION_TAG_DISCOVERED</h3> 460 <p>To filter for {@link android.nfc.NfcAdapter#ACTION_TAG_DISCOVERED} use the following intent 461 filter:</p> 462 463 464 <pre><intent-filter> 465 <action android:name="android.nfc.action.TAG_DISCOVERED"/> 466 </intent-filter> 467 </pre> 468 469 470 471 <h3 id="obtain-info">Obtaining information from intents</h3> 472 473 <p>If an activity starts because of an NFC intent, you can obtain information about the scanned NFC 474 tag from the intent. Intents can contain the following extras depending on the tag that was scanned: 475 476 <ul> 477 <li>{@link android.nfc.NfcAdapter#EXTRA_TAG} (required): A {@link android.nfc.Tag} object 478 representing the scanned tag.</li> 479 <li>{@link android.nfc.NfcAdapter#EXTRA_NDEF_MESSAGES} (optional): An array of NDEF messages 480 parsed from the tag. This extra is mandatory on {@link android.nfc.NfcAdapter#ACTION_NDEF_DISCOVERED 481 intents.</li> 482 <li>{@link android.nfc.NfcAdapter#EXTRA_ID} (optional): The low-level ID of the tag.</li></ul> 483 484 <p>To obtain these extras, check to see if your activity was launched with one of 485 the NFC intents to ensure that a tag was scanned, and then obtain the extras out of the 486 intent. The following example checks for the {@link android.nfc.NfcAdapter#ACTION_NDEF_DISCOVERED} 487 intent and gets the NDEF messages from an intent extra.</p> 488 489 <pre> 490 public void onResume() { 491 super.onResume(); 492 ... 493 if (NfcAdapter.ACTION_NDEF_DISCOVERED.equals(getIntent().getAction())) { 494 Parcelable[] rawMsgs = intent.getParcelableArrayExtra(NfcAdapter.EXTRA_NDEF_MESSAGES); 495 if (rawMsgs != null) { 496 msgs = new NdefMessage[rawMsgs.length]; 497 for (int i = 0; i < rawMsgs.length; i++) { 498 msgs[i] = (NdefMessage) rawMsgs[i]; 499 } 500 } 501 } 502 //process the msgs array 503 } 504 </pre> 505 506 <p>Alternatively, you can obtain a {@link android.nfc.Tag} object from the intent, which will 507 contain the payload and allow you to enumerate the tag's technologies:</p> 508 509 <pre>Tag tag = intent.getParcelableExtra(NfcAdapter.EXTRA_TAG);</pre> 510 511 512 <h2 id="creating-records">Creating Common Types of NDEF Records</h2> 513 <p>This section describes how to create common types of NDEF records to help you when writing to 514 NFC tags or sending data with Android Beam. It also describes how to create the corresponding 515 intent filter for the record. All of these NDEF record examples should be in the first NDEF 516 record of the NDEF message that you are writing to a tag or beaming.</p> 517 518 <h3 id="abs-uri">TNF_ABSOLUTE_URI</h3> 519 <p>Given the following {@link android.nfc.NdefRecord#TNF_ABSOLUTE_URI} NDEF record, which is 520 stored as the first record inside of an {@link android.nfc.NdefMessage}:</p> 521 522 <pre> 523 NdefRecord uriRecord = new NdefRecord( 524 NdefRecord.TNF_ABSOLUTE_URI , 525 "http://developer.android.com/index.html".getBytes(Charset.forName("US-ASCII")), 526 new byte[0], new byte[0]); 527 </pre> 528 529 <p>the intent filter would look like this:</p> 530 <pre> 531 <intent-filter> 532 <action android:name="android.nfc.action.NDEF_DISCOVERED" /> 533 <category android:name="android.intent.category.DEFAULT" /> 534 <data android:scheme="http" 535 android:host="developer.android.com" 536 android:pathPrefix="/index.html" /> 537 </intent-filter> 538 </pre> 539 540 541 <h3 id="mime">TNF_MIME_MEDIA</h3> 542 <p>Given the following {@link android.nfc.NdefRecord#TNF_MIME_MEDIA} NDEF record, which is stored as 543 the first record inside 544 of an {@link android.nfc.NdefMessage}:</p> 545 <pre> 546 NdefRecord mimeRecord = new NdefRecord( 547 NdefRecord.TNF_MIME_MEDIA , 548 "application/com.example.android.beam".getBytes(Charset.forName("US-ASCII")), 549 new byte[0], "Beam me up, Android!".getBytes(Charset.forName("US-ASCII"))); 550 </pre> 551 552 <p>the intent filter would look like this:</p> 553 <pre> 554 <intent-filter> 555 <action android:name="android.nfc.action.NDEF_DISCOVERED" /> 556 <category android:name="android.intent.category.DEFAULT" /> 557 <data android:mimeType="application/com.example.android.beam" /> 558 </intent-filter> 559 </pre> 560 561 562 <h3 id="well-known-text">TNF_WELL_KNOWN with RTD_TEXT</h3> 563 564 <p>Given the following {@link android.nfc.NdefRecord#TNF_WELL_KNOWN} NDEF record, which is stored as 565 the first record inside of an {@link android.nfc.NdefMessage}:</p> 566 <pre> 567 public NdefRecord createTextRecord(String payload, Locale locale, boolean encodeInUtf8) { 568 byte[] langBytes = locale.getLanguage().getBytes(Charset.forName("US-ASCII")); 569 Charset utfEncoding = encodeInUtf8 ? Charset.forName("UTF-8") : Charset.forName("UTF-16"); 570 byte[] textBytes = payload.getBytes(utfEncoding); 571 int utfBit = encodeInUtf8 ? 0 : (1 << 7); 572 char status = (char) (utfBit + langBytes.length); 573 byte[] data = new byte[1 + langBytes.length + textBytes.length]; 574 data[0] = (byte) status; 575 System.arraycopy(langBytes, 0, data, 1, langBytes.length); 576 System.arraycopy(textBytes, 0, data, 1 + langBytes.length, textBytes.length); 577 NdefRecord record = new NdefRecord(NdefRecord.TNF_WELL_KNOWN, 578 NdefRecord.RTD_TEXT, new byte[0], data); 579 return record; 580 } 581 </pre> 582 583 <p>the intent filter would look like this:</p> 584 <pre> 585 <intent-filter> 586 <action android:name="android.nfc.action.NDEF_DISCOVERED" /> 587 <category android:name="android.intent.category.DEFAULT" /> 588 <data android:mimeType="text/plain" /> 589 </intent-filter> 590 </pre> 591 592 593 <h3 id="well-known-uri">TNF_WELL_KNOWN with RTD_URI</h3> 594 595 <p>Given the following {@link android.nfc.NdefRecord#TNF_WELL_KNOWN} NDEF record, which is stored as 596 the first record inside of an {@link android.nfc.NdefMessage}:</p> 597 598 <pre> 599 byte[] uriField = "example.com".getBytes(Charset.forName("US-ASCII")); 600 byte[] payload = new byte[uriField.length + 1]; //add 1 for the URI Prefix 601 byte payload[0] = 0x01; //prefixes http://www. to the URI 602 System.arraycopy(uriField, 0, payload, 1, uriField.length); //appends URI to payload 603 NdefRecord rtdUriRecord = new NdefRecord( 604 NdefRecord.TNF_WELL_KNOWN, NdefRecord.RTD_URI, new byte[0], payload); 605 </pre> 606 607 <p>the intent filter would look like this:</p> 608 609 <pre> 610 <intent-filter> 611 <action android:name="android.nfc.action.NDEF_DISCOVERED" /> 612 <category android:name="android.intent.category.DEFAULT" /> 613 <data android:scheme="http" 614 android:host="example.com" 615 android:pathPrefix="" /> 616 </intent-filter> 617 </pre> 618 619 <h3 id="ext-type">TNF_EXTERNAL_TYPE</h3> 620 <p>Given the following {@link android.nfc.NdefRecord#TNF_EXTERNAL_TYPE} NDEF record, which is stored 621 as the first record inside of an {@link android.nfc.NdefMessage}:</p> 622 623 <pre> 624 byte[] payload; 625 ... 626 NdefRecord mimeRecord = new NdefRecord( 627 NdefRecord.TNF_EXTERNAL_TYPE, "example.com:externalType", new byte[0], payload); 628 </pre> 629 630 <p>the intent filter would look like this:</p> 631 <pre> 632 <intent-filter> 633 <action android:name="android.nfc.action.NDEF_DISCOVERED" /> 634 <category android:name="android.intent.category.DEFAULT" /> 635 <data android:scheme="vnd.android.nfc" 636 android:host="ext" 637 android:pathPrefix="/example.com:externalType"/> 638 </intent-filter> 639 </pre> 640 641 642 <p>Use TNF_EXTERNAL_TYPE for more generic NFC tag deployments to better support both 643 Android-powered and non-Android-powered devices.</p> 644 645 <p class="note"><strong>Note</strong>: URNs for {@link 646 android.nfc.NdefRecord#TNF_EXTERNAL_TYPE} have a canonical format of: 647 <code>urn:nfc:ext:example.com:externalType</code>, however the NFC Forum RTD specification 648 declares that the <code>urn:nfc:ext:</code> portion of the URN must be ommitted from the 649 NDEF record. So all you need to provide is the domain (<code>example.com</code> in the example) 650 and type (<code>externalType</code> in the example) separated by a colon. 651 When dispatching TNF_EXTERNAL_TYPE, Android converts the <code>urn:nfc:ext:example.com:externalType</code> URN to a 652 <code>vnd.android.nfc://ext/example.com:externalType</code> URI, which is what the intent filter in the example 653 declares.</p> 654 655 <h3 id="aar">Android Application Records</h3> 656 657 <p> 658 Introduced in Android 4.0 (API level 14), an Android Application Record (AAR) provides a stronger 659 certainty that your application is started when an NFC tag is scanned. An AAR has the package name 660 of an application embedded inside an NDEF record. You can add an AAR to any NDEF record of your NDEF message, 661 because Android searches the entire NDEF message for AARs. If it finds an AAR, it starts the application based 662 on the package name inside the AAR. If the application is not present on the device, 663 Google Play is launched to download the application.</p> 664 665 <p>AARs are useful if you want to prevent other applications from filtering for the same intent and 666 potentially handling specific tags that you have deployed. AARs are only supported at the 667 application level, because of the package name constraint, and not at the Activity level as with 668 intent filtering. If you want to handle an intent at the Activity level, <a 669 href="#filtering-intents">use intent filters</a>. 670 </p> 671 672 673 674 <p>If a tag contains an AAR, the tag dispatch system dispatches in the following manner:</p> 675 <ol> 676 <li>Try to start an Activity using an intent filter as normal. If the Activity that matches 677 the intent also matches the AAR, start the Activity.</li> 678 <li>If the Activity that filters for the intent does not match the 679 AAR, if multiple Activities can handle the intent, or if no Activity handles the intent, start the 680 application specified by the AAR.</li> 681 <li>If no application can start with the AAR, go to Google Play to download the 682 application based on the AAR.</li> 683 </ol> 684 685 </p> 686 687 <p class="note"><strong>Note:</strong> You can override AARs and the intent dispatch system with the <a 688 href="{@docRoot}guide/topics/connectivity/nfc/advanced-nfc.html#foreground-dispatch">foreground dispatch 689 system</a>, which allows a foreground activity to have priority when an NFC tag is discovered. 690 With this method, the activity must be in the foreground to 691 override AARs and the intent dispatch system.</p> 692 693 <p>If you still want to filter for scanned tags that do not contain an AAR, you can declare 694 intent filters as normal. This is useful if your application is interested in other tags 695 that do not contain an AAR. For example, maybe you want to guarantee that your application handles 696 proprietary tags that you deploy as well as general tags deployed by third parties. Keep in mind 697 that AARs are specific to Android 4.0 devices or later, so when deploying tags, you most likely want 698 to use a combination of AARs and MIME types/URIs to support the widest range of devices. In 699 addition, when you deploy NFC tags, think about how you want to write your NFC tags to enable 700 support for the most devices (Android-powered and other devices). You can do this by 701 defining a relatively unique MIME type or URI to make it easier for applications to distinguish. 702 </p> 703 704 <p>Android provides a simple API to create an AAR, 705 {@link android.nfc.NdefRecord#createApplicationRecord createApplicationRecord()}. All you need to 706 do is embed the AAR anywhere in your {@link android.nfc.NdefMessage}. You do not want 707 to use the first record of your {@link android.nfc.NdefMessage}, unless the AAR is the only 708 record in the {@link android.nfc.NdefMessage}. This is because the Android 709 system checks the first record of an {@link android.nfc.NdefMessage} to determine the MIME type or 710 URI of the tag, which is used to create an intent for applications to filter. The following code 711 shows you how to create an AAR:</p> 712 713 <pre> 714 NdefMessage msg = new NdefMessage( 715 new NdefRecord[] { 716 ..., 717 NdefRecord.createApplicationRecord("com.example.android.beam")} 718 </pre> 719 720 721 <h2 id="p2p">Beaming NDEF Messages to Other Devices</h2> 722 723 <p>Android Beam allows simple peer-to-peer data exchange between two Android-powered devices. The 724 application that wants to beam data to another device must be in the foreground and the device 725 receiving the data must not be locked. When the beaming device comes in close enough contact with a 726 receiving device, the beaming device displays the "Touch to Beam" UI. The user can then choose 727 whether or not to beam the message to the receiving device.</p> 728 729 <p class="note"><strong>Note:</strong> Foreground NDEF pushing was available at API level 10, 730 which provides similar functionality to Android Beam. These APIs have since been deprecated, but 731 are available to support older devices. See {@link android.nfc.NfcAdapter#enableForegroundNdefPush 732 enableForegroundNdefPush()} for more information.</p> 733 734 <p>You can enable Android Beam for your application by calling one of the two methods:</p> 735 <ul> 736 <li>{@link android.nfc.NfcAdapter#setNdefPushMessage setNdefPushMessage()}: Accepts an 737 {@link android.nfc.NdefMessage} to set as the message to beam. Automatically beams the message 738 when two devices are in close enough proximity.</li> 739 <li>{@link android.nfc.NfcAdapter#setNdefPushMessageCallback setNdefPushMessageCallback()}: 740 Accepts a callback that contains a 741 {@link android.nfc.NfcAdapter.CreateNdefMessageCallback#createNdefMessage createNdefMessage()} 742 which is called when a device is in range to beam data to. The callback lets you create 743 the NDEF message only when necessary.</li> 744 </ul> 745 746 <p>An activity can only push one NDEF message at a time, so {@link 747 android.nfc.NfcAdapter#setNdefPushMessageCallback setNdefPushMessageCallback()} takes precedence 748 over {@link android.nfc.NfcAdapter#setNdefPushMessage setNdefPushMessage()} if both are set. To use 749 Android Beam, the following general guidelines must be met: 750 </p> 751 752 <ul> 753 <li>The activity that is beaming the data must be in the foreground. Both devices must have 754 their screens unlocked.</li> 755 756 <li>You must encapsulate the data that you are beaming in an {@link android.nfc.NdefMessage} 757 object.</li> 758 759 <li>The NFC device that is receiving the beamed data must support the 760 <code>com.android.npp</code> NDEF push protocol or NFC Forum's SNEP (Simple NDEF Exchange 761 Protocol). The <code>com.android.npp</code> protocol is required for devices on API level 9 (Android 762 2.3) to API level 13 (Android 3.2). <code>com.android.npp</code> and SNEP are both required on 763 API level 14 (Android 4.0) and later.</li> 764 </li> 765 </ul> 766 767 <p class="note"><strong>Note:</strong> If your activity enables Android Beam and is 768 in the foreground, the standard intent dispatch system is disabled. However, if your activity also 769 enables <a href="{@docRoot}guide/topics/connectivity/nfc/advanced-nfc.html#foreground-dispatch">foreground 770 dispatching</a>, then it can still scan tags that match the intent filters set in the foreground 771 dispatching.</p> 772 773 <p>To enable Android Beam:</p> 774 775 <ol> 776 <li>Create an {@link android.nfc.NdefMessage} that contains the {@link android.nfc.NdefRecord}s 777 that you want to push onto the other device.</li> 778 779 <li>Call {@link 780 android.nfc.NfcAdapter#setNdefPushMessage setNdefPushMessage()} with a {@link 781 android.nfc.NdefMessage} or call {@link 782 android.nfc.NfcAdapter#setNdefPushMessageCallback setNdefPushMessageCallback} passing in a {@link 783 android.nfc.NfcAdapter.CreateNdefMessageCallback} object in the <code>onCreate()</code> method of 784 your activity. These methods require at least one activity that you want to enable with Android 785 Beam, along with an optional list of other activities to activate. 786 787 <p>In general, you normally use {@link 788 android.nfc.NfcAdapter#setNdefPushMessage setNdefPushMessage()} if your Activity only needs to 789 push the same NDEF message at all times, when two devices are in range to communicate. You use 790 {@link android.nfc.NfcAdapter#setNdefPushMessageCallback setNdefPushMessageCallback} when your 791 application cares about the current context of the application and wants to push an NDEF message 792 depending on what the user is doing in your application.</p> 793 </li> 794 </ol> 795 796 <p>The following sample shows how a simple activity calls {@link 797 android.nfc.NfcAdapter.CreateNdefMessageCallback} in the <code>onCreate()</code> method of an 798 activity (see <a href="{@docRoot}resources/samples/AndroidBeamDemo/index.html">AndroidBeamDemo</a> 799 for the complete sample). This example also has methods to help you create a MIME record:</p> 800 801 <pre id="code-example"> 802 package com.example.android.beam; 803 804 import android.app.Activity; 805 import android.content.Intent; 806 import android.nfc.NdefMessage; 807 import android.nfc.NdefRecord; 808 import android.nfc.NfcAdapter; 809 import android.nfc.NfcAdapter.CreateNdefMessageCallback; 810 import android.nfc.NfcEvent; 811 import android.os.Bundle; 812 import android.os.Parcelable; 813 import android.widget.TextView; 814 import android.widget.Toast; 815 import java.nio.charset.Charset; 816 817 818 public class Beam extends Activity implements CreateNdefMessageCallback { 819 NfcAdapter mNfcAdapter; 820 TextView textView; 821 822 @Override 823 public void onCreate(Bundle savedInstanceState) { 824 super.onCreate(savedInstanceState); 825 setContentView(R.layout.main); 826 TextView textView = (TextView) findViewById(R.id.textView); 827 // Check for available NFC Adapter 828 mNfcAdapter = NfcAdapter.getDefaultAdapter(this); 829 if (mNfcAdapter == null) { 830 Toast.makeText(this, "NFC is not available", Toast.LENGTH_LONG).show(); 831 finish(); 832 return; 833 } 834 // Register callback 835 mNfcAdapter.setNdefPushMessageCallback(this, this); 836 } 837 838 @Override 839 public NdefMessage createNdefMessage(NfcEvent event) { 840 String text = ("Beam me up, Android!\n\n" + 841 "Beam Time: " + System.currentTimeMillis()); 842 NdefMessage msg = new NdefMessage( 843 new NdefRecord[] { createMimeRecord( 844 "application/com.example.android.beam", text.getBytes()) 845 /** 846 * The Android Application Record (AAR) is commented out. When a device 847 * receives a push with an AAR in it, the application specified in the AAR 848 * is guaranteed to run. The AAR overrides the tag dispatch system. 849 * You can add it back in to guarantee that this 850 * activity starts when receiving a beamed message. For now, this code 851 * uses the tag dispatch system. 852 */ 853 //,NdefRecord.createApplicationRecord("com.example.android.beam") 854 }); 855 return msg; 856 } 857 858 @Override 859 public void onResume() { 860 super.onResume(); 861 // Check to see that the Activity started due to an Android Beam 862 if (NfcAdapter.ACTION_NDEF_DISCOVERED.equals(getIntent().getAction())) { 863 processIntent(getIntent()); 864 } 865 } 866 867 @Override 868 public void onNewIntent(Intent intent) { 869 // onResume gets called after this to handle the intent 870 setIntent(intent); 871 } 872 873 /** 874 * Parses the NDEF Message from the intent and prints to the TextView 875 */ 876 void processIntent(Intent intent) { 877 textView = (TextView) findViewById(R.id.textView); 878 Parcelable[] rawMsgs = intent.getParcelableArrayExtra( 879 NfcAdapter.EXTRA_NDEF_MESSAGES); 880 // only one message sent during the beam 881 NdefMessage msg = (NdefMessage) rawMsgs[0]; 882 // record 0 contains the MIME type, record 1 is the AAR, if present 883 textView.setText(new String(msg.getRecords()[0].getPayload())); 884 } 885 886 /** 887 * Creates a custom MIME type encapsulated in an NDEF record 888 */ 889 public NdefRecord createMimeRecord(String mimeType, byte[] payload) { 890 byte[] mimeBytes = mimeType.getBytes(Charset.forName("US-ASCII")); 891 NdefRecord mimeRecord = new NdefRecord( 892 NdefRecord.TNF_MIME_MEDIA, mimeBytes, new byte[0], payload); 893 return mimeRecord; 894 } 895 } 896 </pre> 897 898 <p>Note that this code comments out an AAR, which you can remove. If you enable the AAR, the 899 application specified in the AAR always receives the Android Beam message. If the application is not 900 present, Google Play launches to download the application. Therefore, the following intent 901 filter is not technically necessary for Android 4.0 devices or later if the AAR is used: 902 </p> 903 904 <pre> 905 <intent-filter> 906 <action android:name="android.nfc.action.NDEF_DISCOVERED"/> 907 <category android:name="android.intent.category.DEFAULT"/> 908 <data android:mimeType="application/com.example.android.beam"/> 909 </intent-filter> 910 </pre> 911 <p>With this intent filter, the <code>com.example.android.beam</code> application now can be started 912 when it scans an NFC tag or receives an Android Beam with an AAR of 913 type <code>com.example.android.beam</code>, or when an NDEF formatted message contains a MIME record 914 of type <code>application/com.example.android.beam</code>.</p> 915 916 <p>Even though AARs guarantee an application is started or downloaded, intent filters are 917 recommended, because they let you start an Activity of your choice in your 918 application instead of always starting the main Activity within the package specified by an AAR. 919 AARs do not have Activity level granularity. Also, because some Android-powered devices do not 920 support AARs, you should also embed identifying information in the first NDEF record of your NDEF 921 messages and filter for that as well, just in case. See <a href="#creating-records">Creating Common 922 Types of NDEF records</a> for more information on how to create records. 923 </p> 924