1page.title=Versioning Your Applications 2@jd:body 3 4<div id="qv-wrapper"> 5<div id="qv"> 6 7<h2>Quickview</h2> 8 9<ul> 10<li>Your application <em>must</em> be versioned</a></li> 11<li>You set the version in the application's manifest file</li> 12<li>How you version your applications affects how users upgrade </li> 13<li>Determine your versioning strategy early in the development process, including considerations for future releases.</li> 14</ul> 15 16<h2>In this document</h2> 17 18<ol> 19<li><a href="#appversioning">Setting Application Version</a></li> 20<li><a href="#minsdkversion">Specifying Your Application's System API Requirements</a> 21</ol> 22 23 24<h2>See also</h2> 25 26<ol> 27<li><a href="{@docRoot}guide/publishing/preparing.html">Preparing to Publish Your Application</a></li> 28<li><a href="{@docRoot}guide/publishing/publishing.html#market">Publishing On Android Market</a></li> 29<li><a href="{@docRoot}guide/topics/manifest/manifest-intro.html">The AndroidManifest.xml File</a></li> 30</ol> 31 32</div> 33</div> 34 35<p>Versioning is a critical component of your application upgrade/maintenance 36strategy. </p> 37 38<ul> 39<li>Users need to have specific information about the application version that 40is installed on their devices and the upgrade versions available for 41installation. </li> 42<li>Other applications — including other applications that you publish as 43a suite — need to query the system for your application's version, to 44determine compatibility and identify dependencies.</li> 45<li>Services through which you will publish your application(s) may also need to 46query your application for its version, so that they can display the version to 47users. A publishing service may also need to check the application version to 48determine compatibility and establish upgrade/downgrade relationships.</li> 49</ul> 50 51<p>The Android system itself <em>does not ever</em> check the application version 52information for an application, such as to enforce restrictions on upgrades, 53compatibility, and so on. Instead, only users or applications themselves are 54responsible for enforcing any version restrictions for applications themselves. </p> 55 56<p>The Android system <em>does</em> check any system version compatibility expressed 57by an application in its manifest, in the <code>minSdkVersion</code> attribute. This 58allows an application to specify the minimum system API with which is compatible. 59For more information see <a href="#minsdkversion">Specifying Minimum System API Version</a>. 60 61<h2 id="appversioning">Setting Application Version</h2> 62<p>To define the version information for your application, you set attributes in 63the application's manifest file. Two attributes are available, and you should 64always define values for both of them: </p> 65 66<ul> 67<li><code>android:versionCode</code> — An integer value that represents 68the version of the application code, relative to other versions. 69 70<p>The value is an integer so that other applications can programmatically 71evaluate it, for example to check an upgrade or downgrade relationship. You can 72set the value to any integer you want, however you should make sure that each 73successive release of your application uses a greater value. The system does not 74enforce this behavior, but increasing the value with successive releases is 75normative. </p> 76 77<p>Typically, you would release the first version of your application with 78versionCode set to 1, then monotonically increase the value with each release, 79regardless whether the release constitutes a major or minor release. This means 80that the <code>android:versionCode</code> value does not necessarily have a 81strong resemblance to the application release version that is visible to the 82user (see <code>android:versionName</code>, below). Applications and publishing 83services should not display this version value to users.</p> 84</li> 85<li><code>android:versionName</code> — A string value that represents the 86release version of the application code, as it should be shown to users. 87<p>The value is a string so that you can describe the application version as a 88<major>.<minor>.<point> string, or as any other type of 89absolute or relative version identifier. </p> 90 91<p>As with <code>android:versionCode</code>, the system does not use this value 92for any internal purpose, other than to enable applications to display it to 93users. Publishing services may also extract the <code>android:versionName</code> 94value for display to users.</p> 95</li> 96</ul> 97 98<p>You define both of these version attributes in the 99<code><manifest></code> element of the manifest file. </p> 100 101<p>Here's an example manifest that shows the <code>android:versionCode</code> 102and <code>android:versionName</code> attributes in the 103<code><manifest></code> element. </p> 104 105<pre> 106<?xml version="1.0" encoding="utf-8"?> 107<manifest xmlns:android="http://schemas.android.com/apk/res/android" 108 package="com.example.package.name" 109 android:versionCode="2" 110 android:versionName="1.1"> 111 <application android:icon="@drawable/icon" android:label="@string/app_name"> 112 ... 113 </application> 114</manifest> 115</pre> 116 117<p>In this example, note that <code>android:versionCode</code> value indicates 118that the current .apk contains the second release of the application code, which 119corresponds to a minor follow-on release, as shown by the 120<code>android:versionName</code> string. </p> 121 122<p>The Android framework provides an API to let applications query the system 123for version information about your application. To obtain version information, 124applications use the 125{@link android.content.pm.PackageManager#getPackageInfo(java.lang.String, int)} 126method of {@link android.content.pm.PackageManager PackageManager}. </p> 127 128<h2 id="minsdkversion">Specifying Your Application's System API Requirements</h2> 129 130<p>If your application requires a specific minimum version of the Android 131platform, or is designed only to support a certain range of Android platform 132versions, you can specify those version requirements as API Level identifiers 133in the application's manifest file. Doing so ensures that your 134application can only be installed on devices that 135are running a compatible version of the Android system. </p> 136 137<p>To specify API Level requirements, add a <code><uses-sdk></code> 138element in the application's manifest, with one or more of these attributes: </p> 139 140<ul> 141<li><code>android:minSdkVersion</code> — The minimum version 142of the Android platform on which the application will run, specified 143by the platform's API Level identifier. </li> 144<li><code>android:targetSdkVersion</code> — Specifies the API Level 145on which the application is designed to run. In some cases, this allows the 146application to use manifest elements or behaviors defined in the target 147API Level, rather than being restricted to using only those defined 148for the minimum API Level.</li> 149<li><code>android:maxSdkVersion</code> — The maximum version 150of the Android platform on which the application is designed to run, 151specified by the platform's API Level identifier. <strong>Important:</strong> Please read the <a 152href="{@docRoot}guide/topics/manifest/uses-sdk-element.html"><code><uses-sdk></code></a> 153documentation before using this attribute. </li> 154</ul> 155 156<p>When preparing to install your application, the system checks the value of this 157attribute and compares it to the system version. If the 158<code>android:minSdkVersion</code> value is greater than the system version, the 159system aborts the installation of the application. Similarly, the system 160installs your application only if its <code>android:maxSdkVersion</code> 161is compatible with the platform version.</p> 162 163<p>If you do not specify these attributes in your manifest, the system assumes 164that your application is compatible with all platform versions, with no 165maximum API Level. </p> 166 167<p>To specify a minimum platform version for your application, add a 168<code><uses-sdk></code> element as a child of 169<code><manifest></code>, then define the 170<code>android:minSdkVersion</code> as an attribute. </p> 171 172<p>For more information, see the <a 173href="{@docRoot}guide/topics/manifest/uses-sdk-element.html"><code><uses-sdk></code></a> 174manifest element documentation and the <a 175href="{@docRoot}guide/appendix/api-levels.html">API Levels</a> document.</p> 176