| 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}guide/publishing/preparing.html">Preparing to Publish Your Application</a></li> |
| <li><a href="{@docRoot}guide/publishing/publishing.html#market">Publishing On 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. </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/appendix/api-levels.html">API Levels</a> document.</p> |