| page.title=Versioning Your Applications | |
| @jd:body | |
| <div id="qv-wrapper"> | |
| <div id="qv"> | |
| <h2>Quickview</h2> | |
| <ul> | |
| <li>Your application <em>must</em> be versioned</a></li> | |
| <li>You set the version in the application's manifest file</li> | |
| <li>How you version your applications affects how users upgrade </li> | |
| <li>Determine your versioning strategy early in the development process, including considerations for future releases.</li> | |
| </ul> | |
| <h2>In this document</h2> | |
| <ol> | |
| <li><a href="#appversioning">Setting Application Version</a></li> | |
| <li><a href="#minsdkversion">Specifying Your Application's System API Requirements</a> | |
| </ol> | |
| <h2>See also</h2> | |
| <ol> | |
| <li><a href="{@docRoot}tools/publishing/preparing.html">Preparing to Publish Your Application</a></li> | |
| <li><a href="{@docRoot}distribute/tools/launch-checklist.html">Launch Checklist for Google Play</a></li> | |
| <li><a href="{@docRoot}guide/topics/manifest/manifest-intro.html">The AndroidManifest.xml File</a></li> | |
| </ol> | |
| </div> | |
| </div> | |
| <p>Versioning is a critical component of your application upgrade and maintenance | |
| strategy. Versioning is important because:</p> | |
| <ul> | |
| <li>Users need to have specific information about the application version that | |
| is installed on their devices and the upgrade versions available for | |
| installation. </li> | |
| <li>Other applications — including other applications that you publish as | |
| a suite — need to query the system for your application's version, to | |
| determine compatibility and identify dependencies.</li> | |
| <li>Services through which you will publish your application(s) may also need to | |
| query your application for its version, so that they can display the version to | |
| users. A publishing service may also need to check the application version to | |
| determine compatibility and establish upgrade/downgrade relationships.</li> | |
| </ul> | |
| <p>The Android system does not use app version information to enforce | |
| restrictions on upgrades, downgrades, or compatibility of third-party apps. Instead, you (the | |
| developer) are responsible for enforcing version restrictions within your application or by | |
| informing users of the version restrictions and limitations. The Android system does, however, | |
| enforce system version compatibility as expressed by the <code>minSdkVersion</code> attribute in the | |
| manifest. This attribute allows an application to specify the minimum system API with which it is | |
| compatible. For more information see <a href="#minsdkversion">Specifying Minimum System API | |
| Version</a>.</p> | |
| <h2 id="appversioning">Setting Application Version</h2> | |
| <p>To define the version information for your application, you set attributes in | |
| the application's manifest file. Two attributes are available, and you should | |
| always define values for both of them: </p> | |
| <ul> | |
| <li><code>android:versionCode</code> — An integer value that represents | |
| the version of the application code, relative to other versions. | |
| <p>The value is an integer so that other applications can programmatically | |
| evaluate it, for example to check an upgrade or downgrade relationship. You can | |
| set the value to any integer you want, however you should make sure that each | |
| successive release of your application uses a greater value. The system does not | |
| enforce this behavior, but increasing the value with successive releases is | |
| normative. </p> | |
| <p>Typically, you would release the first version of your application with | |
| versionCode set to 1, then monotonically increase the value with each release, | |
| regardless whether the release constitutes a major or minor release. This means | |
| that the <code>android:versionCode</code> value does not necessarily have a | |
| strong resemblance to the application release version that is visible to the | |
| user (see <code>android:versionName</code>, below). Applications and publishing | |
| services should not display this version value to users.</p> | |
| </li> | |
| <li><code>android:versionName</code> — A string value that represents the | |
| release version of the application code, as it should be shown to users. | |
| <p>The value is a string so that you can describe the application version as a | |
| <major>.<minor>.<point> string, or as any other type of | |
| absolute or relative version identifier. </p> | |
| <p>As with <code>android:versionCode</code>, the system does not use this value | |
| for any internal purpose, other than to enable applications to display it to | |
| users. Publishing services may also extract the <code>android:versionName</code> | |
| value for display to users.</p> | |
| </li> | |
| </ul> | |
| <p>You define both of these version attributes in the | |
| <code><manifest></code> element of the manifest file or the Gradle build file. See | |
| <a href="{@docRoot}tools/building/configuring-gradle.html">Configuring Gradle Builds</a>.</p> | |
| <p>Here's an example manifest that shows the <code>android:versionCode</code> | |
| and <code>android:versionName</code> attributes in the | |
| <code><manifest></code> element. </p> | |
| <pre> | |
| <?xml version="1.0" encoding="utf-8"?> | |
| <manifest xmlns:android="http://schemas.android.com/apk/res/android" | |
| package="com.example.package.name" | |
| android:versionCode="2" | |
| android:versionName="1.1"> | |
| <application android:icon="@drawable/icon" android:label="@string/app_name"> | |
| ... | |
| </application> | |
| </manifest> | |
| </pre> | |
| <p>In this example, note that <code>android:versionCode</code> value indicates | |
| that the current .apk contains the second release of the application code, which | |
| corresponds to a minor follow-on release, as shown by the | |
| <code>android:versionName</code> string. </p> | |
| <p>The Android framework provides an API to let applications query the system | |
| for version information about your application. To obtain version information, | |
| applications use the | |
| {@link android.content.pm.PackageManager#getPackageInfo(java.lang.String, int)} | |
| method of {@link android.content.pm.PackageManager PackageManager}. </p> | |
| <h2 id="minsdkversion">Specifying Your Application's System API Requirements</h2> | |
| <p>If your application requires a specific minimum version of the Android | |
| platform, or is designed only to support a certain range of Android platform | |
| versions, you can specify those version requirements as API Level identifiers | |
| in the application's manifest file. Doing so ensures that your | |
| application can only be installed on devices that | |
| are running a compatible version of the Android system. </p> | |
| <p>To specify API Level requirements, add a <code><uses-sdk></code> | |
| element in the application's manifest, with one or more of these attributes: </p> | |
| <ul> | |
| <li><code>android:minSdkVersion</code> — The minimum version | |
| of the Android platform on which the application will run, specified | |
| by the platform's API Level identifier. </li> | |
| <li><code>android:targetSdkVersion</code> — Specifies the API Level | |
| on which the application is designed to run. In some cases, this allows the | |
| application to use manifest elements or behaviors defined in the target | |
| API Level, rather than being restricted to using only those defined | |
| for the minimum API Level.</li> | |
| <li><code>android:maxSdkVersion</code> — The maximum version | |
| of the Android platform on which the application is designed to run, | |
| specified by the platform's API Level identifier. <strong>Important:</strong> Please read the <a | |
| href="{@docRoot}guide/topics/manifest/uses-sdk-element.html"><code><uses-sdk></code></a> | |
| documentation before using this attribute. </li> | |
| </ul> | |
| <p>When preparing to install your application, the system checks the value of this | |
| attribute and compares it to the system version. If the | |
| <code>android:minSdkVersion</code> value is greater than the system version, the | |
| system aborts the installation of the application. Similarly, the system | |
| installs your application only if its <code>android:maxSdkVersion</code> | |
| is compatible with the platform version.</p> | |
| <p>If you do not specify these attributes in your manifest, the system assumes | |
| that your application is compatible with all platform versions, with no | |
| maximum API Level. </p> | |
| <p>To specify a minimum platform version for your application, add a | |
| <code><uses-sdk></code> element as a child of | |
| <code><manifest></code>, then define the | |
| <code>android:minSdkVersion</code> as an attribute. </p> | |
| <p>For more information, see the <a | |
| href="{@docRoot}guide/topics/manifest/uses-sdk-element.html"><code><uses-sdk></code></a> | |
| manifest element documentation and the <a | |
| href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#ApiLevels">API Levels</a> document. For | |
| Gradle build settings, see | |
| <a href="{@docRoot}tools/building/configuring-gradle.html">Configuring Gradle Builds</a>.</p> |