If you've been around buzztouch for a bit, or perhaps you've just started but have already tried to compile your app in Eclipse, you're aware of the requirements for using the Google APIs in your project. For buzztouch v1.4, the requirement is for Google API 4, and for buzztouch v1.5 and v2.0, the requirement is for Google API 8. Have you ever wondered what these requirements are for, and how they differ from Android APIs? I have, so I did some research. To start, let's look at what an API is. API stands for "Application Programming Interface," and that's basically a fancy way of saying a method for software components to talk to each other. Sometimes the software we want to talk to is in control of hardware on the device that it's running on, as is the case with smartphones. In our instance, buzztouch often wants to talk to various software programs in the Android operating system and have it do things or report information back. Android provides APIs so software like buzztouch can gets the tasks done it wants to do, and interact with the device the way it wants. Same thing for Google APIs...these APIs allow developers to interact with the various services Google provides developers. Both Android and Google publish the details of how to interact with these APIs, so developers can write code that asks the right questions and processes the answers correctly. People like David @ buzztouch know how to write code that uses these APIs, and that's what we have in buzztouch. I'm not going to go into anymore detail about this because it can get complicated very quickly. If you want to learn more, Google can point you in the right direction. So, now we know what APIs are, and we understand generally how they are used in our apps. But what's the deal with requiring specific versions? Can't we just use whichever ones we want? The answer to those questions is...sorta. When the folks at buzztouch were doing their programming of a particular version of buzztouch, they used the most current API available at the time. So, when they were working on v1.4, the most current version was Android 1.6 (Donut) / Google API 4. When it came time to work on v1.5, they chose Android 2.2 (Froyo) / Google API 8 to do their coding with. And for v2.0, I think they just ported the code over and kept with the same API requirements as v1.5 has. This means that the buzztouch code was written with those APIs as a reference, and the code has been optimized to deal with the features of those APIs. But technology never stops, and there have been many, many more versions of both Android and Google APIs. in fact, Android 4.1 (Jelly Bean) / Google API 16 was recently released. Prior to that, Android 4.0.3 (Ice Cream Sandwich) / Google API 15 was the most recent level. So, as you can see, it's changed quite a bit since the days when v1.5 was released and required Google API 8! So now the question becomes, can we compile our apps against these new APIs? The answer is YES, but with caveats! You are absolutely free to compile your app against whichever APIs you choose. You can compile your app against Ice Cream Sandwich, and it'll compile just fine. The potential problem becomes in the running of the app. One thing about code, both Android and Google, is that it's always changing (and hopefully getting better). So, when buzztouch developed their code against a particular set of APIs, it was solid at the time. But as APIs change, so does the code. Some code that buzztouch relies on may be deprecated, which means it's not being improved anymore in favor of newer code, but is still usable. Some code we rely on may simply no longer be supported, and that could potentially break your app. So, the lesson is that you can feel free to compile your app against any level of API greater than the ones specified by buzztouch, but you need to do your due diligence and make sure you've tested all your screens out to make sure they run as expected. Either that, or prepare for the barrage of emails you may get from your customers when things stop working. Getting close to wrapping this up, but I want to make sure everybody understands which component of a buzztouch app requires the Google APIs, and which components require the Android APIs. For Google APIs, the answer is short and simple: maps. If your app has maps in it, you need to compile with the Google APIs. If your app doesn't have any maps in them, and you've removed the Java files that reference maps, then you don't need to compile with the Google APIs, and can just use the Android APIs. I verified that with buzztouch. For Android APIs, the answer is even simpler: everything else requires the Android APIs. If you scan through your AndroidManifest.xml file, you'll see there a list of things that require Android APIs, and those that require Google APIs. Things like android.permission.INTERNET and android.hardware.telephony are all indicators of requiring Android APIs. Things like com.google.android.maps are indicators of features that require the Google APIs. If you look, that's literally the only thing that requires the Google APIs. Everything else requires Android APIs. One last thing before I summarize what we've hopefully learned here today. There are a number of Android and Google API versions out there, but not all are created equal. Some enjoy very, very limited use, while others are hugely popular on devices out in the wild. For a great breakdown of the percentages, check out this link: http://developer.android.com/about/dashboards/index.html There you'll see that Android 1.6 / Google API 4 only runs on about 0.6% of the devices. Android 2.2 / Google API 8 runs on about 19.1% of the devices. However, Android 2.3.3 (Gingerbread) / Google API 10 runs on a good 64.6% of the devices out there! So, if you REALLY want to see how your app performs on the most popular version, you should set up an Emulator running Android 2.3.3 / Google API 10 and see how things look. You may find some bugs, you may not. But at least you have a decent idea on if there are any issues or not. You don't have to compile with those same levels...you can use the suggested ones from buzztouch, but it's nice to see what a device running those levels might do to your app. One last thing here (for real!), and this point was brought up by @raveyd as something of interest, and a point I had considered including also. In your AndroidManifest.xml file, you have the capability of specifying the minimum API level that a device must be running in order to install your app. Check out this line from your file: <uses-sdk android:minSdkVersion="8"/> The <uses-sdk> syntax is actually a bit more powerful than what we see here. This is a list of possible options: <uses-sdk android:minSdkVersion="integer" android:targetSdkVersion="integer" android:maxSdkVersion="integer" /> Let's go over them one by one. The stuff in quotes if from the online documentation. * minSdkVersion: "An integer designating the minimum API Level required for the application to run. The Android system will prevent the user from installing the application if the system's API Level is lower than the value specified in this attribute. You should always declare this attribute." In our applications, the default requirement is Google API 8. If a user doesn't have at least that on their device, the app won't install. * targetSdkVersion: "An integer designating the API Level that the application targets. If not set, the default value equals that given to minSdkVersion. This attribute informs the system that you have tested against the target version and the system should not enable any compatibility behaviors to maintain your app's forward-compatibility with the target version. The application is still able to run on older versions (down to minSdkVersion)." buzztouch doesn't set this for us, so it defaults to minSdkVersion in our case. This means you've tested against this particular version, and the system should not enable features found on more recent versions. * maxSdkVersion: "An integer designating the maximum API Level on which the application is designed to run. Warning: Declaring this attribute is not recommended." This sets the maxium version of API that your app will run on. Let's say you set it to 8, and all is well. A while later your customer updates his device to a Google API 10. At that point, because the device API level exceeds the maxSdkVersion, the app will no longer validate on an update, and the system essentially makes it invisible to the user (basically removes it). Tread very carefully if you use this! A great description of all this can be found online here: http://developer.android.com/guide/topics/manifest/uses-sdk-element.html Take some time to read up on the attributes, and decide what makes the most sense for your app. You may have very good reasons for restricting your app to a particular API level! OK, let's sum up what we've hopefully learned here: * APIs are interfaces that let software talk to each other (and may involve hardware). * The API requirements for each version of buzztouch are based on what was available and focused on at the time of that version's development. * The Google API is only required if you have maps (or leave the map code) in your app. If you remove maps and all the code, you don't need the API. * The AndroidManifest is a great place to learn what requires which API. * Not all APIs are created equal, and some enjoy more popularity than others. * You can restrict or target particular API levels using your AndroidManifest file. * You can, and probably should, test on multiple APIs just to see how your app will respond. I hope this has helped anybody interested in what all this API stuff means. Hopefully I've gotten this all correct, but if I haven't, I welcome constructive feedback to help me get it straight. I know for myself, I will be testing my apps on various Android versions just to make sure the work as expected. It's a bit more of an effort on my part, but it'll hopefully address any potential customer issues in advance! Thanks! Mark

very helpful mark

Nice tutorial Mark! How its so comforting reading about android right now =( lol

Thanks, guys! Hope it helps you understand how it works a bit better!

Brilliant Mark, very clear. There should perhaps also be a mention of the minimum sdk level that's set in the manifest, especially when using 3rd party jars such as admob which require higher build levels than api 8. There's a lot of misunderstanding, with users thinking that these jars requiring higher build levels aren't compatible with BT, when they actually are.

Hi @raveyd, I actually thought about adding the bit about minimum API level in the manifest, but then decided against it thinking it was a bit out of scope. But I agree it's important, and since at least one person (you!) has mentioned it, I'll edit the tutorial to include it. Will get to that in a bit! Mark

Sorry Mark, more work!

Updated!

Thank you Mark - very helpful!

Glad it helped!