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