tobi/M7350
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

M7350v1_en_gpl

Browse Source
This commit is contained in:
T
2024-09-09 08:52:07 +00:00
commit f9cc65cfda
65988 changed files with 26357421 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

617
base/docs/html/guide/publishing/app-signing.jd Normal file
View File

@ -0,0 +1,617 @@
page.title=Signing Your Applications
@jd:body
<div id="qv-wrapper">
<div id="qv">
<h2>Quickview</h2>
<ul>
<li>All Android apps <em>must</em> be signed</a></li>
<li>You can sign with a self-signed key</li>
<li>How you sign your apps is critical &mdash; read this document carefully</li>
<li>Determine your signing strategy early in the development process</li>
</ul>
<h2>In this document</h2>
<ol>
<li><a href="#overview">Overview</a></li>
<li><a href="#strategies">Signing Strategies</a></li>
<li><a href="#setup">Basic Setup for Signing</a></li>
<li><a href="#debugmode">Signing in Debug Mode</a></li>
<li><a href="#releasemode">Signing for Public Release</a>
<ol>
<li><a href="#cert">Obtain a suitable private key</a></li>
<li><a href="#releasecompile">Compile the application in release mode</a></li>
<li><a href="#signapp">Sign your application with your private key</a></li>
<li><a href="#align">Align the final APK package</a></li>
<li><a href="#ExportWizard">Compile and sign with Eclipse ADT</a></li>
</ol>
</li>
<li><a href="#secure-key">Securing Your Private Key</a></li>
</ol>
<h2>See also</h2>
<ol>
<li><a href="{@docRoot}guide/publishing/versioning.html">Versioning Your Applications</a></li>
<li><a href="{@docRoot}guide/publishing/preparing.html">Preparing to Publish</a></li>
</ol>
</div>
</div>
<p>This document provides information about signing your Android applications prior to publishing them for mobile device users.</p>
<h2 id="overview">Overview</h2>
<p>The Android system requires that all installed applications be digitally
signed with a certificate whose private key is held by the application's
developer. The Android system uses the certificate as a means of identifying the author of
an application and establishing trust relationships between applications. The certificate is not
used to control which applications the user can install. The certificate
does not need to be signed by a certificate authority: it is perfectly
allowable, and typical, for Android applications to use self-signed
certificates.</p>
<p>The important points to understand about signing Android applications are:</p>
<ul>
<li>All applications <em>must</em> be signed. The system will not install an application
that is not signed.</li>
<li>You can use self-signed certificates to sign your applications. No certificate authority
is needed.</li>
<li>When you are ready to release your application for end-users, you must sign it with a suitable private
key. You can not publish an application that is signed with the debug key generated
by the SDK tools.
</li>
<li>The system tests a signer certificate's expiration date only at install time. If an
application's signer certificate expires after the application is installed, the application
will continue to function normally.</li>
<li>You can use standard tools &mdash; Keytool and Jarsigner &mdash; to generate keys and
sign your application .apk files.</li>
<li>Once you have signed the application, use the <code>zipalign</code> tool to optimize the final APK package.</li>
</ul>
<p>The Android system will not install or run an application that is not signed appropriately. This
applies wherever the Android system is run, whether on an actual device or on the emulator.
For this reason, you must set up signing for your application before you will be able to
run or debug it on an emulator or device.</p>
<p>The Android SDK tools assist you in signing your applications when debugging. Both the ADT Plugin
for Eclipse and the Ant build tool offer two signing modes &mdash; <em>debug mode</em>
and <em>release mode</em>.
<ul>
<li>While developing and testing, you can compile in debug mode.
In debug mode, the build tools use the Keytool utility, included in the JDK, to create
a keystore and key with a known alias and password. At each compilation, the tools then use
the debug key to sign the application .apk file. Because the password is known, the tools
don't need to prompt you for the keystore/key password each time you compile.</li>
<li>When your application is ready for release, you must compile in release mode
and then sign the .apk <span style="color:red">with your private key</span>.
There are two ways to do this:
<ul>
<li>Using Keytool and Jarsigner in the command-line. In this approach,
you first compile your application to an <em>unsigned</em> .apk. You must then sign
the .apk manually with your private key
using Jarsigner (or similar tool). If you do not have a suitable private key already,
you can run Keytool manually to generate your own keystore/key and then sign your
application with Jarsigner.</li>
<li>Using the ADT Export Wizard. If you are developing in Eclipse with the ADT plugin,
you can use the Export Wizard to compile the application, generate a private key
(if necessary), and sign the .apk, all in a single process using the Export Wizard.
</li>
</ul>
</li>
</ul>
<p>Once your application is signed, don't forget to run {@code zipalign} on the APK
for additional optimization.</p>
<h2 id="strategies">Signing Strategies</h2>
<p>Some aspects of application signing may affect how you approach the development
of your application, especially if you are planning to release multiple
applications. </p>
<p>In general, the recommended strategy for all developers is to sign
all of your applications with the same certificate, throughout the expected
lifespan of your applications. There are several reasons why you should do so: </p>
<ul>
<li>Application upgrade &ndash; As you release updates to your application, you
will want to continue to sign the updates with the same certificate or set of
certificates, if you want users to upgrade seamlessly to the new version. When
the system is installing an update to an application, it compares the
certificate(s) in the new version with those in the existing version. If the
certificates match exactly, including both the certificate data and order, then
the system allows the update. If you sign the new version without using matching
certificates, you will also need to assign a different package name to the
application &mdash; in this case, the user installs the new version as a
completely new application. </li>
<li>Application modularity &ndash; The Android system allows applications that
are signed by the same certificate to run in the same process, if the
applications so requests, so that the system treats them as a single application.
In this way you can deploy your application in modules, and users can update
each of the modules independently if needed.</li>
<li>Code/data sharing through permissions &ndash; The Android system provides
signature-based permissions enforcement, so that an application can expose
functionality to another application that is signed with a specified
certificate. By signing multiple applications with the same certificate and
using signature-based permissions checks, your applications can share code and
data in a secure manner. </li>
</ul>
<p>Another important consideration in determining your signing strategy is
how to set the validity period of the key that you will use to sign your
applications.</p>
<ul>
<li>If you plan to support upgrades for a single application, you should ensure
that your key has a validity period that exceeds the expected lifespan of
that application. A validity period of 25 years or more is recommended.
When your key's validity period expires, users will no longer be
able to seamlessly upgrade to new versions of your application.</li>
<li>If you will sign multiple distinct applications with the same key,
you should ensure that your key's validity period exceeds the expected
lifespan of <em>all versions of all of the applications</em>, including
dependent applications that may be added to the suite in the future. </li>
<li>If you plan to publish your application(s) on Android Market, the
key you use to sign the application(s) must have a validity period
ending after 22 October 2033. The Market server enforces this requirement
to ensure that users can seamlessly upgrade Market applications when
new versions are available. </li>
</ul>
<p>As you design your application, keep these points in mind and make sure to
use a <a href="#cert">suitable certificate</a> to sign your applications. </p>
<h2 id="setup">Basic Setup for Signing</h2>
<p>Before you begin, you should make sure that
Keytool is available to the SDK build
tools. In most cases, you can tell the SDK build tools how to find Keytool by setting
your <code>JAVA_HOME</code> environment variable to references a suitable JDK.
Alternatively, you can add the JDK version of Keytool to your <code>PATH</code> variable.</p>
<p>If you are developing on a version of Linux that originally came with GNU Compiler for
Java, make sure that the system is using the JDK version of Keytool, rather than the gcj
version. If Keytool is already in your <code>PATH</code>, it might be pointing to a symlink at
<code>/usr/bin/keytool</code>. In this case, check the symlink target to be sure it points
to the Keytool in the JDK.</p>
<p>If you will release your application to the public, you will also need to have
the Jarsigner tool available on your machine. Both Jarsigner and Keytool are included
in the JDK. </p>
<h2 id="debugmode">Signing in Debug Mode</h2>
<p>The Android build tools provide a debug signing mode that makes it easier for you
to develop and debug your application, while still meeting the Android system
requirement for signing your .apk.
When using debug mode to build your app, the SDK tools invoke Keytool to automatically create
a debug keystore and key. This debug key is then used to automatically sign the .apk, so
you do not need to sign the package with your own key.</p>
<p>The SDK tools create the debug keystore/key with predetermined names/passwords:</p>
<ul>
<li>Keystore name: "debug.keystore"</li>
<li>Keystore password: "android"</li>
<li>Key alias: "androiddebugkey"</li>
<li>Key password: "android"</li>
<li>CN: "CN=Android Debug,O=Android,C=US"</li>
</ul></p>
<p>If necessary, you can change the location/name of the debug keystore/key or
supply a custom debug keystore/key to use. However, any custom debug
keystore/key must use the same keystore/key names and passwords as the default
debug key (as described above). (To do so in Eclipse/ADT, go to
<strong>Windows</strong> &gt; <strong>Preferences</strong> &gt;
<strong>Android</strong> &gt; <strong>Build</strong>.) </p>
<p class="caution"><strong>Caution:</strong> You <em>cannot</em> release your application
to the public when signed with the debug certificate.</p>
<h3>Eclipse Users</h3>
<p>If you are developing in Eclipse/ADT (and have set up Keytool as described above in
<a href="#setup">Basic Setup for Signing</a>),
signing in debug mode is enabled by default. When you run or debug your
application, ADT signs the .apk with the debug certificate, runs {@code zipalign} on the
package, then installs it on
the selected emulator or connected device. No specific action on your part is needed,
provided ADT has access to Keytool.</p>
<h3>Ant Users</h3>
<p>If you are using Ant to build your .apk files, debug signing mode
is enabled by using the <code>debug</code> option with the <code>ant</code> command
(assuming that you are using a <code>build.xml</code> file generated by the
<code>android</code> tool). When you run <code>ant debug</code> to
compile your app, the build script generates a keystore/key and signs the .apk for you.
The script then also aligns the .apk with the <code>zipalign</code> tool.
No other action on your part is needed. Read
<a href="{@docRoot}guide/developing/other-ide.html#DebugMode">Developing In Other IDEs: Building
in debug mode</a> for more information.</p>
<h3 id="debugexpiry">Expiry of the Debug Certificate</h3>
<p>The self-signed certificate used to sign your application in debug mode (the default on
Eclipse/ADT and Ant builds) will have an expiration date of 365 days from its creation date.</p>
<p>When the certificate expires, you will get a build error. On Ant builds, the error
looks like this:</p>
<pre>debug:
[echo] Packaging bin/samples-debug.apk, and signing it with a debug key...
[exec] Debug Certificate expired on 8/4/08 3:43 PM</pre>
<p>In Eclipse/ADT, you will see a similar error in the Android console.</p>
<p>To fix this problem, simply delete the <code>debug.keystore</code> file.
The default storage location for AVDs is in <code>~/.android/</code> on OS X and Linux,
in <code>C:\Documents and Settings\<user>\.android\</code> on Windows XP, and in
<code>C:\Users\<user>\.android\</code> on Windows Vista.</p>
<p>The next time you build, the build tools will regenerate a new keystore and debug key.</p>
<p>Note that, if your development machine is using a non-Gregorian locale, the build
tools may erroneously generate an already-expired debug certificate, so that you get an
error when trying to compile your application. For workaround information, see the
troubleshooting topic <a href="{@docRoot}resources/faq/troubleshooting.html#signingcalendar">
I&nbsp;can't&nbsp;compile my app because the build tools generated an expired debug
certificate</a>. </p>
<h2 id="releasemode">Signing for Public Release</h2>
<p>When your application is ready for release to other users, you must:</p>
<ol>
<li><a href="#cert">Obtain a suitable private key</a></li>
<li><a href="#releasecompile">Compile the application in release mode</li>
<li><a href="#signapp">Sign your application with your private key</a></li>
<li><a href="#align">Align the final APK package</a></li>
</ol>
<p>If you are developing in Eclipse with the ADT plugin, you can use the Export Wizard
to perform the compile, sign, and align procedures. The Export Wizard even allows you to
generate a new keystore and private key in the process. So if you use Eclipse, you can
skip to <a href="#ExportWizard">Compile and sign with Eclipse ADT</a>.</p>
<h3 id="cert">1. Obtain a suitable private key</h3>
<p>In preparation for signing your application, you must first ensure that
you have a suitable private key with which to sign. A suitable private
key is one that:</p>
<ul>
<li>Is in your possession</li>
<li>Represents the personal, corporate, or organizational entity to be identified
with the application</li>
<li>Has a validity period that exceeds the expected lifespan of the application
or application suite. A validity period of more than 25 years is recommended.
<p>If you plan to publish your application(s) on Android Market, note that a
validity period ending after 22 October 2033 is a requirement. You can not upload an
application if it is signed with a key whose validity expires before that date.
</p></li>
<li>Is not the debug key generated by the Android SDK tools. </li>
</ul>
<p>The key may be self-signed. If you do not have a suitable key, you must
generate one using Keytool. Make sure that you have Keytool available, as described
in <a href="#setup">Basic Setup</a>.</p>
<p>To generate a self-signed key with Keytool, use the <code>keytool</code>
command and pass any of the options listed below (and any others, as
needed). </p>
<p class="warning"><strong>Warning:</strong> Keep your private key secure.
Before you run Keytool, make sure to read
<a href="#secure-key">Securing Your Private Key</a> for a discussion of how to keep
your key secure and why doing so is critically important to you and to users. In
particular, when you are generating your key, you should select strong passwords
for both the keystore and key.</p>
<table>
<tr>
<th>Keytool Option</th>
<th>Description</th>
</tr>
<tr>
<td><code>-genkey</code></td><td>Generate a key pair (public and private
keys)</td>
</tr>
<tr>
<td><code>-v</code></td><td>Enable verbose output.</td>
</tr>
<tr>
<td><code>-alias &lt;alias_name&gt;</code></td><td>An alias for the key. Only
the first 8 characters of the alias are used.</td>
</tr>
<tr>
<td><code>-keyalg &lt;alg&gt;</code></td><td>The encryption algorithm to use
when generating the key. Both DSA and RSA are supported.</td>
</tr>
<tr>
<td><code>-keysize &lt;size&gt;</code></td><td>The size of each generated key
(bits). If not supplied, Keytool uses a default key size of 1024 bits. In
general, we recommend using a key size of 2048 bits or higher. </td>
</tr>
<tr>
<td><code>-dname &lt;name&gt;</code></td><td><p>A Distinguished Name that describes
who created the key. The value is used as the issuer and subject fields in the
self-signed certificate. </p><p>Note that you do not need to specify this option
in the command line. If not supplied, Jarsigner prompts you to enter each
of the Distinguished Name fields (CN, OU, and so on).</p></td>
</tr>
<tr>
<td><code>-keypass &lt;password&gt;</code></td><td><p>The password for the
key.</p> <p>As a security precaution, do not include this option in your command
line. If not supplied, Keytool prompts you to enter the password. In this way,
your password is not stored in your shell history.</p></td>
</tr>
<tr>
<td><code>-validity &lt;valdays&gt;</code></td><td><p>The validity period for the
key, in days. </p><p><strong>Note:</strong> A value of 10000 or greater is recommended.</p></td>
</tr>
<tr>
<td><code>-keystore&nbsp;&lt;keystore-name&gt;.keystore</code></td><td>A name
for the keystore containing the private key.</td>
</tr>
<tr>
<td><code>-storepass &lt;password&gt;</code></td><td><p>A password for the
keystore.</p><p>As a security precaution, do not include this option in your
command line. If not supplied, Keytool prompts you to enter the password. In
this way, your password is not stored in your shell history.</p></td>
</tr>
</table>
<p>Here's an example of a Keytool command that generates a private key:</p>
<pre>$ keytool -genkey -v -keystore my-release-key.keystore
-alias alias_name -keyalg RSA -keysize 2048 -validity 10000</pre>
<p>Running the example command above, Keytool prompts you to provide
passwords for the keystore and key, and to provide the Distinguished
Name fields for your key. It then generates the keystore as a file called
<code>my-release-key.keystore</code>. The keystore and key are
protected by the passwords you entered. The keystore contains
a single key, valid for 10000 days. The alias is a name that you &mdash;
will use later, to refer to this keystore when signing your application. </p>
<p>For more information about Keytool, see the documentation at
<a
href="http://java.sun.com/j2se/1.5.0/docs/tooldocs/#security">
http://java.sun.com/j2se/1.5.0/docs/tooldocs/#security</a></p>
<h3 id="releasecompile">2. Compile the application in release mode</h3>
<p>In order to release your application to users, you must compile it in release mode.
In release mode, the compiled application is not signed by default and you will need
to sign it with your private key.</p>
<p class="caution"><strong>Caution:</strong>
You can not release your application unsigned, or signed with the debug key.</p>
<h4>With Eclipse</h4>
<p>To export an <em>unsigned</em> .apk from Eclipse, right-click the project in the Package
Explorer and select <strong>Android Tools</strong> > <strong>Export Unsigned Application
Package</strong>. Then specify the file location for the unsigned .apk.
(Alternatively, open your <code>AndroidManifest.xml</code> file in Eclipse, open
the <em>Overview</em> tab, and click <strong>Export an unsigned .apk</strong>.)</p>
<p>Note that you can combine the compiling and signing steps with the Export Wizard. See
<a href="#ExportWizard">Compiling and signing with Eclipse ADT</a>.</p>
<h4>With Ant</h4>
<p>If you are using Ant, you can enable release mode by using the <code>release</code> option
with the <code>ant</code> command. For example, if you are running Ant from the
directory containing your {@code build.xml} file, the command would look like this:</p>
<pre>ant release</pre>
<p>By default, the build script compiles the application .apk without signing it. The output file
in your project {@code bin/} will be <code><em>&lt;your_project_name></em>-unsigned.apk</code>.
Because the application .apk is still unsigned, you must manually sign it with your private
key and then align it using {@code zipalign}.</p>
<p>However, the Ant build script can also perform the signing
and aligning for you, if you have provided the path to your keystore and the name of
your key alias in the project's {@code build.properties} file. With this information provided,
the build script will prompt you for your keystore and alias password when you perform
<code>ant release</code>, it will sign the package and then align it. The final output
file in {@code bin/} will instead be
<code><em>&lt;your_project_name></em>-release.apk</code>. With these steps
automated for you, you're able to skip the manual procedures below (steps 3 and 4).
To learn how to specify your keystore and alias in the {@code build.properties} file,
see <a href="{@docRoot}guide/developing/other-ide.html#ReleaseMode">Developing In Other
IDEs: Building in release mode</a>.</p>
<h3 id="signapp">3. Sign your application with your private key</h3>
<p>When you have an application package that is ready to be signed, you can do sign it
using the Jarsigner tool. Make sure that you have Jarsigner available on your
machine, as described in <a href="#setup">Basic Setup</a>. Also, make sure that
the keystore containing your private key is available.</p>
<p>To sign your application, you run Jarsigner, referencing both the
application's .apk and the keystore containing the private key with which to
sign the .apk. The table below shows the options you could use. <p>
<table>
<tr>
<th>Jarsigner Option</th>
<th>Description</th>
</tr>
<tr>
<td><code>-keystore&nbsp;&lt;keystore-name&gt;.keystore</code></td><td>The name of
the keystore containing your private key.</td>
</tr>
<tr>
<td><code>-verbose</code></td><td>Enable verbose output.</td>
</tr>
<tr>
<td><code>-storepass &lt;password&gt;</code></td><td><p>The password for the
keystore. </p><p>As a security precaution, do not include this option
in your command line unless you are working at a secure computer.
If not supplied, Jarsigner prompts you to enter the password. In this
way, your password is not stored in your shell history.</p></td>
</tr>
<tr>
<td><code>-keypass &lt;password&gt;</code></td><td><p>The password for the private
key. </p><p>As a security precaution, do not include this option
in your command line unless you are working at a secure computer.
If not supplied, Jarsigner prompts you to enter the password. In this
way, your password is not stored in your shell history.</p></td>
</tr>
</table>
<p>Here's how you would use Jarsigner to sign an application package called
<code>my_application.apk</code>, using the example keystore created above.
</p>
<pre>$ jarsigner -verbose -keystore my-release-key.keystore
my_application.apk alias_name</pre>
<p>Running the example command above, Jarsigner prompts you to provide
passwords for the keystore and key. It then modifies the .apk
in-place, meaning the .apk is now signed. Note that you can sign an
.apk multiple times with different keys.</p>
<p>To verify that your .apk is signed, you can use a command like this:</p>
<pre>$ jarsigner -verify my_signed.apk</pre>
<p>If the .apk is signed properly, Jarsigner prints "jar verified".
If you want more details, you can try one of these commands:</p>
<pre>$ jarsigner -verify -verbose my_application.apk</pre>
<p>or</p>
<pre>$ jarsigner -verify -verbose -certs my_application.apk</pre>
<p>The command above, with the <code>-certs</code> option added, will show you the
"CN=" line that describes who created the key.</p>
<p class="note"><strong>Note:</strong> If you see "CN=Android Debug", this means the .apk was
signed with the debug key generated by the Android SDK. If you intend to release
your application, you must sign it with your private key instead of the debug
key.</p>
<p>For more information about Jarsigner, see the documentation at
<a href="http://java.sun.com/j2se/1.5.0/docs/tooldocs/#security">
http://java.sun.com/j2se/1.5.0/docs/tooldocs/#security</a></p>
<h3 id="align">4. Align the final APK package</h3>
<p>Once you have signed the .apk with your private key, run <code>zipalign</code> on the file.
This tool ensures that all uncompressed data starts with a particular byte alignment,
relative to the start of the file. Ensuring alignment at 4-byte boundaries provides
a performance optimization when installed on a device. When aligned, the Android
system is able to read files with {@code mmap()}, even if
they contain binary data with alignment restrictions, rather than copying all
of the data from the package. The benefit is a reduction in the amount of
RAM consumed by the running application.</p>
<p>The <code>zipalign</code> tool is provided with the Android SDK, inside the
<code>tools/</code> directory. To align your signed .apk, execute:</p>
<pre>zipalign -v 4 <em>your_project_name</em>-unaligned.apk <em>your_project_name</em>.apk</pre>
<p>The {@code -v} flag turns on verbose output (optional). {@code 4} is the
byte-alignment (don't use anything other than 4). The first file argument is
your signed .apk (the input) and the second file is the destination .apk file (the output).
If you're overriding an existing .apk, add the {@code -f} flag.</p>
<p class="caution"><strong>Caution:</strong> Your input .apk must be signed with your
private key <strong>before</strong> you optimize the package with {@code zipalign}.
If you sign it after using {@code zipalign}, it will undo the alignment.</p>
<p>For more information, read about the
<a href="{@docRoot}guide/developing/tools/zipalign.html">zipalign</a> tool.
<h3 id="ExportWizard">Compile and sign with Eclipse ADT</h3>
<p>If you are using Eclipse with the ADT plugin, you can use the Export Wizard to
export a <em>signed</em> .apk (and even create a new keystore,
if necessary). The Export Wizard performs all the interaction with
the Keytool and Jarsigner for you, which allows you to sign the package using a GUI
instead of performing the manual procedures to compile, sign,
and align, as discussed above. Once the wizard has compiled and signed your package,
it will also perfom package alignment with {@code zipalign}.
Because the Export Wizard uses both Keytool and Jarsigner, you should
ensure that they are accessible on your computer, as described above
in the <a href="#setup">Basic Setup for Signing</a>.</p>
<p>To create a signed and aligned .apk in Eclipse:</p>
<ol>
<li>Select the project in the Package
Explorer and select <strong>File > Export</strong>.</li>
<li>Open the Android folder, select Export Android Application,
and click <strong>Next</strong>.
<p>The Export Android Application wizard now starts, which will
guide you through the process of signing your application,
including steps for selecting the private key with which to sign the .apk
(or creating a new keystore and private key).</p>
<li>Complete the Export Wizard and your application will be compiled,
signed, aligned, and ready for distribution.</li>
</ol>
<h2 id="secure-key">Securing Your Private Key</h2>
<p>Maintaining the security of your private key is of critical importance, both
to you and to the user. If you allow someone to use your key, or if you leave
your keystore and passwords in an unsecured location such that a third-party
could find and use them, your authoring identity and the trust of the user
are compromised. </p>
<p>If a third party should manage to take your key without your knowledge or
permission, that person could sign and distribute applications that maliciously
replace your authentic applications or corrupt them. Such a person could also
sign and distribute applications under your identity that attack other
applications or the system itself, or corrupt or steal user data. </p>
<p>Your reputation as a developer entity depends on your securing your private
key properly, at all times, until the key is expired. Here are some tips for
keeping your key secure: </p>
<ul>
<li>Select strong passwords for the keystore and key.</li>
<li>When you generate your key with Keytool, <em>do not</em> supply the
<code>-storepass</code> and <code>-keypass</code> options at the command line.
If you do so, your passwords will be available in your shell history,
which any user on your computer could access.</li>
<li>Similarly, when signing your applications with Jarsigner,
<em>do not</em> supply the <code>-storepass</code> and <code>-keypass</code>
options at the command line. </li>
<li>Do not give or lend anyone your private key, and do not let unauthorized
persons know your keystore and key passwords.</li>
</ul>
<p>In general, if you follow common-sense precautions when generating, using,
and storing your key, it will remain secure. </p>

2375
base/docs/html/guide/publishing/licensing.jd Normal file
View File

File diff suppressed because it is too large Load Diff

256
base/docs/html/guide/publishing/preparing.jd Normal file
View File

@ -0,0 +1,256 @@
page.title=Preparing to Publish: A Checklist
@jd:body
<p>Publishing an application means testing it, packaging it appropriately, and
making it available to users of Android-powered mobile devices.</p>
<p>If you plan to publish your application for installation on
Android-powered devices, there are several things you need to do, to get
your application ready. This document highlights the significant
checkpoints for preparing your application for a successful release.
</p>
<p>If you will publish your application on Android Market, please also see <a
href="{@docRoot}guide/publishing/publishing.html#market">Publishing on Android Market</a>
for specific preparation requirements for your application. </p>
<p>For general information about the ways that you can publish an applications,
see the <a href="{@docRoot}guide/publishing/publishing.html">Publishing Your
Applications</a> document. </p>
<div class="special">
<p><a href="#releaseready">Before you consider your application ready for release</a>:</p>
<ol>
<li>Test your application extensively on an actual device </li>
<li>Consider adding an End User License Agreement in your application</li>
<li>Consider adding licensing support</li>
<li>Specify an icon and label in the application's manifest</li>
<li>Turn off logging and debugging and clean up data/files</li>
</ol>
<p><a href="#finalcompile">Before you do the final compile of your application</a>:</p>
<ol start="6">
<li>Version your application</li>
<li>Obtain a suitable cryptographic key</li>
<li>Register for a Maps API Key, if your application is using MapView elements</li>
</ol>
<p><a href="#compile">Compile your application</a></p>
<p><a href="#post-compile">After you compile your application</a>:</p>
<ol start="9">
<li>Sign your application</li>
<li>Test your compiled application</li>
</ol>
</div>
<h2 id="releaseready">Before you consider your application ready for release</h2>
<h3 id="test">1. Test your application extensively on an actual device</h3>
<p>It's important to test your application as extensively as possible, in as
many areas as possible. To help you do that, Android provides a variety of
testing classes and tools. You can use
{@link android.app.Instrumentation Instrumentation} to run JUnit and other
test cases, and you can use testing
tools such as the <a href="{@docRoot}guide/developing/tools/monkey.html">UI/Application
Exerciser Monkey</a>. </p>
<ul>
<li>To ensure that your application will run properly for users, you should make
every effort to obtain one or more physical mobile device(s) of the type on
which you expect the application to run. You should then test your application
on the actual device, under realistic network conditions. Testing your
application on a physical device is very important, because it enables you to
verify that your user interface elements are sized correctly (especially for
touch-screen UI) and that your application's performance and battery efficiency
are acceptable.</li>
<li>If you can not obtain a mobile device of the type you are targeting for your
application, you can use emulator options such as <code>-dpi</code>,
<code>-device</code>, <code>-scale</code>, <code>-netspeed</code>,
<code>-netdelay</code>, <code>-cpu-delay</code> and others to model the
emulator's screen, network performance, and other attributes to match the target
device to the greatest extent possible. You can then test your application's UI
and performance. However, we strongly recommend that you test your application
on an actual target device before publishing it. </li>
<li>If you are targeting the <a href="http://www.t-mobileg1.com/">T-Mobile
G1</a> device for your application, make sure that your UI handles screen
orientation changes. </li>
</ul>
<h3 id="eula">2. Consider adding an End User License Agreement in your
application</h3>
<p>To protect your person, organization, and intellectual property, you may want
to provide an End User License Agreement (EULA) with your application.
<h3>3. Consider adding support for Android Market Licensing</h3>
<p>If you are publishing a paid application through Android Market, consider
adding support for Android Market Licensing. Licensing lets you control access
to your application based on whether the current user has purchased it.
Using Android Market Licensing is optional.
<p>For complete information about Android Market Licensing Service and how to
use it in your application, see <a
href="{@docRoot}guide/publishing/licensing.html">Licensing Your
Applications</a>.</p>
<h3 id="iconlabel">4. Specify an icon and label in the application's manifest</h3>
<p>The icon and label that you specify in an application's manifest are
important because they are displayed to users as your application's icon and
name. They are displayed on the device's Home screen, as well as in Manage
Applications, My Downloads, and elsewhere. Additionally, publishing services may
display the icon and label to users. </p>
<p>To specify an icon and label, you define the attributes
<code>android:icon</code> and <code>android:label</code> in the
<code>&lt;application&gt;</code> element of the manifest. </p>
<p>As regards the design of your icon, you should try to make it match as much
as possible the style used by the built-in Android applications.</p>
<h3 id="logging">5. Turn off logging and debugging and clean up data/files</h3>
<p>For release, you should make sure that debug facilities are turned off and
that debug and other unnecessary data/files are removed from your application
project.</p>
<ul>
<li>Remove the <code>android:debuggable="true"</code> attribute from the
<code>&lt;application&gt;</code> element of the manifest.</li>
<li>Remove log files, backup files, and other unnecessary files from the
application project.</li>
<li>Check for private or proprietary data and remove it as necessary.</li>
<li>Deactivate any calls to {@link android.util.Log} methods in the source
code.</li>
</ul>
<h2 id="finalcompile">Before you do the final compile of your application</h2>
<h3 id="versionapp">6. Version your application</h3>
<p>Before you compile your application, you must make sure that you have defined
a version number for your application, specifying an appropriate value for both
the <code>android:versionCode</code> and <code>android:versionName</code>
attributes of the <code>&lt;manifest&gt;</code> element in the application's
manifest file. Carefully consider your version numbering plans in the context of
your overall application upgrade strategy. </p>
<p>If you have previously released a version of your application, you must make
sure to increment the version number of the current application. You must
increment both the <code>android:versionCode</code> and
<code>android:versionName</code> attributes of the <code>&lt;manifest&gt;</code>
element in the application's manifest file, using appropriate values. </p>
<p>For detailed information about how to define version information for your
application, see <a href="{@docRoot}guide/publishing/versioning.html">Versioning
Your Applications</a>.</p>
<h3 id="cryptokey">7. Obtain a suitable cryptographic key</h3>
<p>If you have read and followed all of the preparation steps up to this point,
your application is compiled and ready for signing. Inside the .apk, the
application is properly versioned, and you've cleaned out extra files and
private data, as described above. </p>
<p>Before you sign your application, you need to make sure that you have a
suitable private key. For complete information about how to obtain (or generate)
a private key, see <a href="{@docRoot}guide/publishing/app-signing.html#cert">
Obtaining a Suitable Private Key</a>.</p>
<p>Once you have obtained (or generated) a suitable private key, you will use it
to:</p>
<ul>
<li>Register for a Maps API Key (see below), if your application uses MapView
elements.</li>
<li>Sign your application for release, later in the preparation process</li>
</ul>
<h3 id="mapsApiKey">8. Register for a Maps API Key, if your application is using
MapView elements</h3>
<div class="sidebox-wrapper">
<div class="sidebox"><p>
For complete information about getting a Maps API Key, see <a
href="http://code.google.com/android/add-ons/google-apis/mapkey.html">
Obtaining a Maps API Key</a>.</p>
</div>
</div>
<p>If your application uses one or more Mapview elements, you will need to
register your application with the Google
Maps service and obtain a Maps API Key, before your MapView(s) will be able to
retrieve data from Google Maps. To do so, you supply an MD5 fingerprint of your
signer certificate to the Maps service. </p>
<p>During development, you can get a temporary Maps API Key by registering the
debug key generated by the SDK tools. However, before publishing your
application, you must register for a new Maps API Key that is based on your
private key. </p>
<p>If your application uses MapView elements, the important points to understand
are:</p>
<ol>
<li>You <em>must</em> obtain the Maps API Key before you compile your
application for release, because you must add the Key to a special attribute in
each MapView element &mdash; <code>android:apiKey</code> &mdash; in your
application's layout files. If you are instantiating MapView objects directly
from code, you must pass the Maps API Key as a parameter in the constructor.
</li>
<li>The Maps API Key referenced by your application's MapView elements must be
registered (in Google Maps) to the certificate used to sign the application.
This is particularly important when publishing your application &mdash; your
MapView elements must reference a Key that is registered to the release
certificate that you will use to sign your application. </li>
<li>If you previously got a temporary Maps API Key by registering the debug
certificate generated by the SDK tools, you <em>must</em> remember to obtain a
new Maps API Key by registering your release certificate. You must then remember
to change the MapView elements to reference the new Key, rather than the Key
associated with the debug certificate. If you do not do so, your MapView
elements will not have permission to download Maps data. </li>
<li>If you change the private key that you will use to sign your application,
you <em>must</em> remember to obtain a new Maps API Key from the Google Maps
service. If you do not get a new Maps API Key and apply it to all MapView
elements, any MapView elements referencing the old Key will not have permission
to download Maps data. </li>
</ol>
<h2 id="compile">Compile your application</h2>
<p>When you've prepared your application as described in the previous sections,
you can compile your application for release.</p>
<h2 id="post-compile">After you compile your application</h2>
<h3 id="signapp">9. Sign your application</h3>
<p>Sign your application using your private key and then
align it with the {@code zipalign} tool. Signing your application
correctly is critically important. Please see
<a href="{@docRoot}guide/publishing/app-signing.html">Signing Your
Applications</a> for complete information. </p>
<h3 id="testapp">10. Test your compiled and signed application</h3>
<p>Before you release your compiled application, you should thoroughly test it
on the target mobile device (and target network, if possible). In particular,
you should make sure that any MapView elements in your UI are receiving maps
data properly. If they are not, go back to <a href="#mapsApiKey">Register for a
Maps API Key</a> and correct the problem. You should also ensure that the
application works correctly with any server-side services and data that you are
providing or are relying on and that the application handles any authentication
requirements correctly. </p>
<p>After testing, you are now ready to publish your application to mobile device
users.</p>

306
base/docs/html/guide/publishing/publishing.jd Normal file
View File

@ -0,0 +1,306 @@
page.title=Publishing Your Applications
@jd:body
<div id="qv-wrapper">
<div id="qv">
<h2>Quickview</h2>
<ul>
<li>You can publish your application using a hosted service such as Android Market or through a web server.</li>
<li>Before you publish, make sure you have prepared your application properly.</li>
<li>Android Market makes it easy for users of Android-powered devices to see and download your application.</li>
</ul>
<h2>In this document</h2>
<ol>
<li><a href="#overview">Publishing on Android Market</a>
<ol>
<li><a href="#marketupgrade">Publishing Updates on Android Market</a></li>
<li><a href="#marketLicensing">Using Android Market Licensing Service</a></li>
<li><a href="#marketintent">Using Intents to Launch the Market Application</a></li>
</ol></li>
<!--
<li><span style="color:ccc">Publishing on Other Hosted Services</a></li>
<li><span style="color:ccc">Publishing through a Web Server</a></li>
-->
</ol>
<h2>See also</h2>
<ol>
<li><a href="{@docRoot}guide/publishing/licensing.html">Licensing Your Applications</a></li>
<li><a href="{@docRoot}guide/publishing/preparing.html">Preparing to Publish</a></li>
</ol>
<div id="qv-extra">
<img id="rule" src="{@docRoot}assets/images/grad-rule-qv.png">
<div id="qv-sub-rule">
<img src="{@docRoot}assets/images/icon_market.jpg" style="float:left;margin:0;padding:0;">
<p style="color:#669999;">Interested in publishing your app on Android Market?</p>
<a id="publish-link" href="http://market.android.com/publish">Go to Android Market &raquo;</a>
</div>
</div>
</div>
</div>
<p>Publishing an application means testing it, packaging it appropriately, and making
it available to users of Android-powered mobile devices for download or sideload.</p>
<p>If you've followed the steps outlined in
<a href="{@docRoot}guide/publishing/preparing.html">Preparing to
Publish Your Applications</a>, the result of the process is a compiled .apk that
is signed with your release private key. Inside the .apk, the application is
properly versioned and any MapView elements reference a Maps API Key that you
obtained by registering the MD5 fingerprint of the same certificate used to sign
the .apk. Your application is now ready for publishing. </p>
<p>The sections below provide information about publishing your Android
application to mobile device users.</p>
<h2 id="overview">Publishing on Android Market</h2>
<p>Android Market is a hosted service that makes it easy for users to find and
download Android applications to their Android-powered devices, and makes it
easy for developers to publish their applications to Android users.</p>
<p>To publish your application on Android Market, you first need to register
with the service using your Google account and agree to the terms of service.
Once you are registered, you can upload your application to the service whenever
you want, as many times as you want, and then publish it when you are ready.
Once published, users can see your application, download it, and rate it using
the Market application installed on their Android-powered devices. </p>
<p>To register as an Android Market developer and get started with publishing,
visit the Android Market: </p>
<p style="margin-left:3em;"><a
href="http://market.android.com/publish">http://market.android.com/publish</a>
</p>
<p>If you plan to publish your application on Android Market, you must make sure
that it meets the requirements listed below, which are enforced by the Market
server when you upload the application.</p>
<div class="special">
<p>Requirements enforced by the Android Market server:</p>
<ol>
<li>Your application must be signed with a cryptographic private key whose
validity period ends after <span style="color:red">22 October 2033</span>. </li>
<li>Your application must define both an <code>android:versionCode</code> and an
<code>android:versionName</code> attribute in the
<a
href="{@docRoot}guide/topics/manifest/manifest-element.html"><code>&lt;manifest&gt;</code></a>
element of its manifest. The server uses the <code>android:versionCode</code> as
the basis for identifying the application internally and handling updates, and
it displays the <code>android:versionName</code> to users as the application's
version.</li>
<li>Your application must define both an <code>android:icon</code> and an
<code>android:label</code> attribute in the <code>&lt;application&gt;</code>
element of its manifest.</li>
</ol>
</div>
<h3 id="marketupgrade">Publishing Updates on Android Market</h3>
<p>At any time after publishing an application on Android Market, you can upload
and publish an update to the same application package. When you publish an
update to an application, users who have already installed the
application will automatically receive a notification that an update is
available for the application. They can then choose to update the application
to the latest version.</p>
<p>Before uploading the updated application, be sure that you have incremented
the <code>android:versionCode</code> and <code>android:versionName</code>
attributes in the <a
href="{@docRoot}guide/topics/manifest/manifest-element.html"><code>&lt;manifest&gt;</code></a>
element of the manifest file. Also, the package name must be the same and the
.apk must be signed with the same private key. If the package name and signing
certificate do <em>not</em> match those of the existing version, Market will
consider it a new application and will not offer it to users as an update.</p>
<h3 id="marketLicensing">Using Android Market Licensing Service</h3>
<p>Android Market offers a licensing service that lets you enforce licensing
policies for paid applications that you publish through Android Market. With
Android Market Licensing, your applications can query Android Market at run time
to obtain their licensing status for the current user, then allow or disallow
further use as appropriate. Using the service, you can apply a flexible
licensing policy on an application-by-application basis &mdash; each
application can enforce its licensing status in the way most appropriate
for it. </p>
<p>Any application that you publish through Android Market can use the Android
Market Licensing Service. The service uses no dedicated framework APIs, you can
add licensing to any legacy application that uses a minimum API level of 3 or
higher.</p>
<p>For complete information about Android Market Licensing Service and how to
use it in your application, see <a
href="{@docRoot}guide/publishing/licensing.html">Licensing Your
Applications</a>.</p>
<h3 id="marketintent">Using Intents to Launch the Market Application on
a Device</h3>
<p>Android-powered devices include a preinstalled Market application that gives
users access to the Android Market site. From Market, users can
browse or search available applications, read ratings and reviews, and
download/install applications.</p>
<p>You can launch the Market application from another Android
application by sending an Intent to the system. You might want to do
this, for example, to help the user locate and download an update to an
installed application, or to let the user know about related
applications that are available for download. </p>
<p>To launch Market, you send an ACTION_VIEW Intent, passing a Market-handled
URI string as the Intent data. In most cases, your application would call
startActivity() to send the ACTION_VIEW Intent with the Market-handled URI.</p>
<p>The URI that you supply with the Intent lets the system route the intent
properly and also expresses the type of action that you want Market to perform
after launch. Currently, you can have Market take these actions:</p>
<ul>
<li>Initiate a search for applications on Android Market, based on the query
parameters that you provide, or </li>
<li>Load the Details page for a specific application on Android Market, based on
the application's package name.</li>
</ul>
<h4>Initiating a search</h4>
<p>Your application can initiate a search on Android Market for applications
that match the query parameters that you provide. To do so, your application
sends an ACTION_VIEW Intent that includes a URI and query parameters in this
format:</p>
<p style="margin-left:2em"><code>market://search?q=&lt;paramtype&gt;:&lt;value&gt;</code></p>
<div class="sidebox-wrapper" xstyle="margin-bottom:2em;margin-top:.5em;width:90%;">
<img id="rule" src="{@docRoot}assets/images/grad-rule-qv.png">
<div id="qv-sub-rule">
<img src="{@docRoot}assets/images/icon_market.jpg" style="float:left;margin:0;padding:0;">
<p style="color:#669999;">Searches on Android Market</p>
<p>When you initiate a search, Android Market returns results from matches in
the public metadata supplied by developers in their Android Market profiles or
application publishing information, but not from the developer's private account
or from the certificate used to sign the application. </p>
</div>
</div>
<p>Using this URI format, you can search for applications by:</p>
<ul>
<li>Package name</li>
<li>Developer name</li>
<li>String match across application name, developer name, and
description, or </li>
<li>Any combination of the above</li>
</ul>
<p>The table at the bottom of this page specifies the <code>paramtypes</code>
and <code>values</code> that correspond to each of these types of search. </p>
<p>When you send an intent to initiate a search for applications, Market sends
the search query to the server and displays the result. To the user, the
experience is something like this: </p>
<ol>
<li>The user presses a link or button in your application.</li>
<li>The Market application launches and takes control of the screen, displaying
a progress indicator labeled "Searching" until it receives the search
results.</li>
<li>Market receives the search results and displays them. Depending on the query
parameters, the search results may include a list of one or more applications.
</li>
<li>From the results page, the user can select an app to go to its Details page,
which offers information about the app and lets the user download/purchase the
app.</li>
</ol>
<h4>Loading an application's Details page</h4>
<p>In Android Market, every application has a Details page that provides an
overview of the application for users. For example, the page includes a short
description of the app and screen shots of it in use, if supplied by the
developer, as well as feedback from users and information about the developer.
The Details page also includes an "Install" button that lets the user trigger
the download/purchase of the application.</p>
<p>If you want to refer the user to a specific appplication, your application
can take the user directly to the application's Details page. To do so, your
application sends an ACTION_VIEW Intent that includes a URI and query parameter
in this format:</p>
<p style="margin-left:2em"><code>market://details?id=&lt;packagename&gt;</code></p>
<p>In this case, the <code>packagename</code> parameter is target application's
fully qualified package name, as declared in the <code>package</code> attribute
of the <code>manifest</code> element in the application's manifest file. For example:</p>
<p style="margin-left:2em"><code>market://details?id=com.example.android.jetboy</code></p>
<h4>Android Market URIs</h4>
<p>The table below provides a list of URIs and actions currently
supported by the Market application.</p>
<p>Note that these URIs work only when passed as Intent data &mdash; you
can't currently load the URIs in a web browser, either on a desktop machine or
on the device. </p>
<table>
<tr>
<th width="25%">For this Result</th>
<th>Pass this URI with the ACTION_VIEW Intent</th>
<th width="36%">Comments</th>
</tr>
<tr>
<td>Display the Details screen for a specific application, as identified
by the app's fully qualified package name.</td>
<td><code>http://market.android.com/details?id=&lt;packagename&gt;</code>
or<br>
<code>market://details?id=&lt;packagename&gt;</code></td>
<td>Note that the package name that you specify is <em>not</em> specific to any
version of an application. Therefore, Market always displays the Details page for the
latest version of the application.</td>
</tr>
<tr>
<td>Search for an application by its fully qualified Java package name and
display the result.</td>
<td><code>http://market.android.com/search?q=pname:&lt;package&gt;</code> or<br>
<code>market://search?q=pname:&lt;package&gt;</code></td>
<td>Searches only the Java package name of applications. Returns only exact
matches.</td>
</tr>
<tr>
<td>Search for applications by developer name and display the results.</td>
<td><code>http://market.android.com/search?q=pub:&lt;Developer&nbsp;Name&gt;</code>
or<br> <code>market://search?q=pub:&lt;Developer Name&gt;</code></td>
<td>Searches only the "Developer Name" fields of Market public profiles.
Returns exact matches only. </td>
</tr>
<tr>
<td>Search for applications by substring and display the results.</td>
<td><code>http://market.android.com/search?q=&lt;substring&gt;</code> or
<br><code>market://search?q=&lt;substring&gt;</code></td>
<td>Searches all public fields (application title, developer name, and
application description) for all applications. Returns exact and partial
matches.</td>
</tr>
<tr>
<td>Search using multiple query parameters and display the results.</td>
<td>Example:<p><code>http://market.android.com/search?q=world pname:com.android.hello pub:Android</code></p></td>
<td>Returns a list of applications meeting all the supplied parameters. </td>
</tr>
</table>

175
base/docs/html/guide/publishing/versioning.jd Normal file
View File

@ -0,0 +1,175 @@
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 Android Market</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/maintenance
strategy. </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 &mdash; including other applications that you publish as
a suite &mdash; 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 itself <em>does not ever</em> check the application version
information for an application, such as to enforce restrictions on upgrades,
compatibility, and so on. Instead, only users or applications themselves are
responsible for enforcing any version restrictions for applications themselves. </p>
<p>The Android system <em>does</em> check any system version compatibility expressed
by an application in its manifest, in the <code>minSdkVersion</code> attribute. This
allows an application to specify the minimum system API with which is compatible.
For more information see <a href="#minsdkversion">Specifying Minimum System API Version</a>.
<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> &mdash; 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> &mdash; 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
&lt;major&gt;.&lt;minor&gt;.&lt;point&gt; 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>&lt;manifest&gt;</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>&lt;manifest&gt;</code> element. </p>
<pre>
&lt;?xml version="1.0" encoding="utf-8"?&gt;
&lt;manifest xmlns:android="http://schemas.android.com/apk/res/android"
package="com.example.package.name"
android:versionCode="2"
android:versionName="1.1"&gt;
&lt;application android:icon="@drawable/icon" android:label="@string/app_name"&gt;
...
&lt;/application&gt;
&lt;/manifest&gt;
</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>&lt;uses-sdk&gt;</code>
element in the application's manifest, with one or more of these attributes: </p>
<ul>
<li><code>android:minSdkVersion</code> &mdash; 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> &mdash; 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> &mdash; 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>&lt;uses-sdk&gt;</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>&lt;uses-sdk&gt;</code> element as a child of
<code>&lt;manifest&gt;</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>&lt;uses-sdk&gt;</code></a>
manifest element documentation and the <a
href="{@docRoot}guide/appendix/api-levels.html">API Levels</a> document.</p>