Welcome to another Five Minute Tutorial. This one one take a bit longer than five minutes to read, but hopefully it's worth it. Today we're discussing the AndroidManifest.xml file. Every Android application that you create must have an AndroidManifest.xml file associated with it. Fortunately, buzztouch creates that file for you and provides it with your source code download, so you don't need to create one from scratch. There are some modifications you can, and perhaps should, make to it before you compile and publish your app. Plus, you should also understand the general nature of the file, as it's responsible for presenting "essential information about the application to the Android system, information the system must have before it can run any of the applications code." That's important stuff! The AndroidManifest.xml file is located in the root directory of your source download package. The file basically does the following: * It names the Java package for the application. * It describes the components of the application * It determines which processes will host application components * It declares which permissions the application must have in order to access protected parts of the API and interact with other applications * It also declares the permissions that others are required to have in order to interact with the application's components. * It lists the Instrumentation classes that provide profiling and other information as the application is running * It declares the minimum level of the Android API that the application requires * It lists the libraries that the application must be linked against A lot of this doesn't make much sense out of context, so let's go through an AndroidManifest.xml file from top to bottom. Feel free to crack yours open if you want to follow along. I'll use one from a test app I built called TwoOhTest. The first line of the file says this: <?xml version="1.0" encoding="utf-8"?> Not a lot to understand there. Just a declaration of the xml version being used, and that it's utf-8 encoding (a variable-length character encoding for Unicode). The next few lines of the file look like this: <manifest xmlns:android="http://schemas.android.com/apk/res/android" package="com.twoohtestbt" android:versionCode="1" android:versionName="1.0"> The first line defines the Android namespace that's being used. It should always be set to http://schemas.android.com/apk/res/android unless Google changes it. The second line identifies the package name for the app. This line is SUPER important, as the name defines your application's identity. According to Google, "to avoid conflicts with other developers, you should use Internet domain ownership as the basis for your package names (in reverse)." This is tied into other files in your package, so if you change it, make sure you make changes throughout your project. But, and pay attention now, here's the most important point to remember: Once you publish your application, you CANNOT change the package name. The package name defines your application's identity, so if you change it, then it is considered to be a different application and users of the previous version cannot update to the new version. And Google remembers all the package names that have been used, so you can't ever reuse one. So, choose wisely! The next two lines define the version of the app. The first line, versionCode, is the internal version of the app. It can be whatever you want, as long as it's an integer. And each time you publish an update to the app, you need to increment it. The next line, versionName, is the version that is displayed to the user. It can be whatever you want it to be. Now, there's one line in this section that isn't here, but that I think should be. It's called "android:installLocation", and the options are internalOnly (installs the app to the internal storage), auto (internal first, then external if internal is full), and preferExternal, which installs the app to the external storage (SD card, etc) if possible. Given the size of apps these days, and the general small size of internal storage, I personally recommend adding the following line to this section: android:installLocation="preferExternal" This will install the app to the external storage (assuming it's not full and that the system honors the request, which it's not bound to), and it won't fill up the internal storage. Lots of people won't install to internal storage, so this helps ensure you get the most people possible installing your app. There are a few more items you 'could' put in the section, but these are the most important. See the Google documentation for more options. Moving on in our AndroidManifest.xml file, we hit this line: <uses-sdk android:minSdkVersion="8"/> This is a pretty important line. This is the line that defines the Google API requirement we all know buzztouch apps to have. This attribute defines the minimum API Level required for the application to run. In this example, if a user attempts to install your application on a device running, say, API Level 6, they would not be able to. Similarly, if you set the value to, say, 17, which is associated with Jelly Bean, then only those people with devices running that API level would be able to install your app. Unless you have a reason to change it, leave this one alone. Having it set to 8 provides the ability for over 90% of Android users to be able to instal your app. Doing OK so far? Good! Continuing on in the file, we now hit a series of statements that look like this: <uses-permission android:name="android.permission.INTERNET" /> This section requests permissions that the application must be granted for it to work properly. So, an application that needs Internet connectivity in order to get or send data would need the above line. If an app needed to use the camera, it would have android.permission.CAMERA. Your file provides a default set of permission requests that covers quite a few app scenarios. But, this is also a potential problem. If your app doesn't need some of these permissions, it's very possible that a user will balk at installing an app that has "android.permission.ACCESS_FINE_LOCATION" set if there is no mapping or anything in the app! So...make sure you read through these permissions and delete the ones you don't need. It'll make you a more responsible app developer, and will help reduce security concerns some people will have. You can also add permissions if you need them! Moving on to the next section, you'll see statements like these: <uses-feature android:name="android.hardware.camera" android:required="false" /> The 'uses-feature' attribute is basically a statement of what hardware features are required for your app to operate. The first part lists what hardware feature is being referenced, and the second section, android:required, defines whether the application is dependent (as in cannot function, or is not designed to function without it) on the feature to operate (android:required="true"), or if the application prefers to use that feature to operate, but but is designed to function without it if necessary (android:required="false"). In my particular AndroidManifest.xml file, all of these values are set to false. That's probably a good thing because it allows the whole application to work even if a particular bit of hardware isn't available. An example would be a Call Us screen in an app, where android.hardware.telephony would be needed to make the call. Tablet devices don't have the ability to make a call. So, if you set the required value to true, and try to install it on a tablet, it won't, because that hardware feature isn't available. But, by putting it as false, it'll work, because it's not an absolute requirement. Phew! Lots of stuff there. About half way done...let's keep going! Next section is the 'application' section. I'm not going to spend a lot of time here....not much you want to mess with. In general, this element contains subelements that declare each of the application's components and has attributes that can affect all the components. You see declarations here for the icon, whether it's debuggable or not, and the app name for the label. In the case of buzztouch, these values are brought in from other layout files. Nothing you really need to change here. Next up is the 'activity' section. Google does a good job explaining this: "Declares an activity (an Activity subclass) that implements part of the application's visual user interface. All activities must be represented by <activity> elements in the manifest file. Any that are not declared there will not be seen by the system and will never be run." In buzztouch apps, "BT_activity_root" is the main activity that kicks off the app. Don't change this unless you know what you're doing! Within the 'activity' section you'll see some 'intent-filter' definitions. These specify the types of intents that an activity, service, or broadcast receiver can respond to. Google says "An intent filter declares the capabilities of its parent component — what an activity or service can do and what types of broadcasts a receiver can handle. It opens the component to receiving intents of the advertised type, while filtering out those that are not meaningful for the component." Lots of code jargon there, but essentially an intent is a 'message' that activates activities, services and broadcast receivers. These are three core components of an application. Google has tons of documentation on this if you want to learn more, but it's too advanced for this tutorial. Most of the rest of the file is a set of 'activity' declarations for the various types of screens that you'll find in your application. Here's an activity declaration for the Button Menu screen: <activity android:name=".BT_screen_menuButtons" android:label="@string/app_name" android:configChanges="keyboardHidden|orientation"></activity> In this, the activity is defined by the android:name attribute. It gets it's screen label from the android:label attribute, which pulls the app name from the strings.xml file. Various configuration changes that the activity will handle itself are listed in the android:configChanges attribute. There are numerous options available for configChanges, and there are tons of additional 'activity' attributes available. Check the documentation if you want to learn more. OK, final line to talk about, and it looks like this: <uses-library android:name="com.google.android.maps"/> The 'uses-library' attribute specifies a shared library that the application must be linked against. In this case, it's the Google Maps library, and it's only necessary if your app uses maps in it. If it doesn't, you can safely delete this line (or just comment it out...probably better). This line is also the reason that buzztouch apps are REQUIRED to be compiled using the Google APIs. If you remove this line (and a few other pieces of code), you can actually compile your app using the Android APIs instead of the Google ones. No real reason to do that, as the Google APIs are good as well. But it is an option. That wraps up our tour of your AndroidManifest.xml file! What we've talked about really only glosses over the true power and breadth of the file as a whole. There are TONS more attributes that can go into the file, and many other things you can configure in it. Full documentation for the file structure can be found here: http://developer.android.com/guide/topics/manifest/manifest-intro.html The intent of this tutorial was to give you an overview of this potentially mysterious file, and to help you understand a few items you can edit, or that you should not edit! Hopefully this has helped a bit in your understanding of Android application development!

Thanks Mark, Although I'm not (yet) an Android developer it's all very well and clear explained. Good job and will help a lot of people to understand this better. Best Regards, Danny

Excellent tutorial Mark! Would you know if writing to the manifest programmatically, sort of like how the screen activities are added, is in the pipeline with bt? As you say, the information contained in the manifest is essential, yet when creating a plugin, info (application info, intents etc) often needs to be manually added to the manifest. It seems sort of wrong to me for a user to install a plugin that should 'just work', but then need to follow a guide to manually add data. A bit off topic, sorry :)

Thank you @GoNorthWest! Great explanation! LA

Hi @raveyd, Thanks for the props! I haven't heard anything about writing to the manifest programmatically being added to the list of things for David to do! I'll check into it, and suggest it if it's not. It's certainly a good idea! Mark

Thanks Mark! Great Explanation! Much clearer! Cheers! -- Smug

Thanks Mark!

Thanks, everybody! Glad you're all finding it useful!

Thanks Mark. Super info.

Mark, you're my app development kindergarten teacher. I mean that in the most positive way of course. Thanks so much.

to analyse and validate XML you can use this tool. http://codebeautify.org/xmlviewer

A heads up on this If you are using Android Studio the version numbers are repeated in build.gradle as well as AndroidManifest.xml. e.g. defaultConfig { applicationId "com.my.packageId" minSdkVersion 15 targetSdkVersion 22 versionCode 2 <-- change this versionName "2.0" <-- change this }

Interesting. Thanks! Cheers! -- Smug

Good to know! Thanks! Mark