Android/frameworks_base
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs cherrypick from hc-mr2: Change-Id: Id8dd0a0baa2fcc88bcfc8171e2be5882d0f06479

Browse Source 
Doc update: publishing topics
Also fixes bug 5279672

Change-Id: Ifb06f7f56ee372a9680a63bdb659f495698fe794
This commit is contained in:
Bill Gruber
2011-09-08 15:41:22 -07:00
committed by Scott Main
parent 5653985830
commit 6c60e9a3ba
12 changed files with 800 additions and 470 deletions
Download Patch File Download Diff File Expand all files Collapse all files

106
docs/html/guide/developing/index.jd
View File

@@ -11,58 +11,55 @@ page.title=Introduction
will sometimes have to call command line tools manually, but you will have access to the same will sometimes have to call command line tools manually, but you will have access to the same
number of features that you would have in Eclipse.</p> number of features that you would have in Eclipse.</p>
<p class="note"><strong>Note:</strong> Before you begin developing Android applications, make <div class="figure" style="width:461px">
sure you have gone through all of the steps outlined in <a <img src="{@docRoot}images/developing/developing_overview.png"
href="{@docRoot}sdk/installing.html">Installing the SDK</a>.</p> alt="Development process for Android applications"
height="738" />
<p class="img-caption">
<strong>Figure 1.</strong> The development process for Android applications.
</p>
</div>
<p>The basic steps for developing applications with or without Eclipse are the same:</p> <p>The basic steps for developing applications (with or without Eclipse) are shown in figure 1. The
development steps encompass four development phases, which include:</p>
<ol> <ul>
<li><strong>Setup</strong>
<li>Set up Android Virtual Devices or hardware devices. <p>During this phase you install and set up your development environment. You also create
Android Virtual Devices (AVDs) and connect hardware devices on which you can install your
<p>You need to create Android Virtual Devices (AVD) or connect hardware devices on which applications.</p>
you will install your applications.</p> <p>See <a href="{@docRoot}guide/developing/devices/index.html">Managing Virtual Devices</a>
<p>See <a href="{@docRoot}guide/developing/devices/index.html">Managing Virtual Devices</a>
and <a href="{@docRoot}guide/developing/device.html">Using Hardware Devices</a> for more and <a href="{@docRoot}guide/developing/device.html">Using Hardware Devices</a> for more
information. information.
</li> </li>
<li><strong>Development</strong>
<p>During this phase you set up and develop your Android project, which contains all of the
source code and resource files for your application. For more informations, see
<a href="{@docRoot}guide/developing/projects/index.html">Create an Android project</a>.</p>
</li>
<li><strong>Debugging and Testing</strong>
<p>During this phase you build your project into a debuggable <code>.apk</code> package that you
can install and run on the emulator or an Android-powered device. If you are using Eclipse,
builds are generated each time you project is saved. If you're using another IDE,
you can build your project using Ant and install it on a device using
<a href="{@docRoot}guide/developing/tools/adb.html">adb</a>. For more information, see
<a href="{@docRoot}guide/developing/building/index.html">Build and run your application</a>.</p>
<p>Next, you debug your application using a JDWP-compliant debugger along with the debugging
and logging tools that are provided with the Android SDK. Eclipse already comes packaged with
a compatible debugger. For more information see,
<a href="{@docRoot}guide/developing/debugging/index.html">Debug your application with the
SDK debugging and logging tools</a>.</p>
<p>Last, you test your application using various Android SDK testing tools. For more
information, see <a href="{@docRoot}guide/developing/testing/index.html">Test your application
with the Testing and Instrumentation framework</a>.</p>
</li>
<li><strong>Publishing</strong>
<p>During this phase you configure and build your application for release and distribute your
application to users. For more information, see
<a href="{@docRoot}guide/publishing/publishing_overview.html">Publishing Overview</a>.</p>
</li>
</ul>
<li>
<a href="{@docRoot}guide/developing/projects/index.html">Create an Android project</a>.
<p>An Android project contains all source code and resource files for your application. It is
built into an <code>.apk</code> package that you can install on Android devices.</p>
</li>
<li>
<a href="{@docRoot}guide/developing/building/index.html">Build and run your
application</a>.
<p>If you are using Eclipse, builds are generated each time you save changes and you can install
your application on a device by clicking <strong>Run</strong>. If you're using another IDE, you can build your
project using Ant and install it on a device using <code>adb</code>.</p>
</li>
<li>
<a href="{@docRoot}guide/developing/debugging/index.html">Debug your application with the
SDK debugging and logging tools</a>.
<p>Debugging your application involves using a JDWP-compliant debugger along with the
debugging and logging tools that are provided with the Android SDK. Eclipse already
comes packaged with a compatible debugger.</p>
</li>
<li>
<a href="{@docRoot}guide/developing/testing/index.html">Test your application with the
Testing and Instrumentation framework</a>.
<p>The Android SDK provides a testing and instrumnetation framework to help you set up and
run tests within an emulator or device.</p>
</li>
</ol>
<h2 id="EssentialTools">Essential command line tools</h2> <h2 id="EssentialTools">Essential command line tools</h2>
<p>When developing in IDEs or editors other than Eclipse, be familiar with <p>When developing in IDEs or editors other than Eclipse, be familiar with
@@ -101,7 +98,7 @@ information.
<dd>To sign your .apk file with a private key generated by Keytool. Jarsigner is part of the <dd>To sign your .apk file with a private key generated by Keytool. Jarsigner is part of the
JDK.</dd> JDK.</dd>
</dl> </dl>
<p>If you are using Eclipse and ADT, tools such as <code>adb</code> and <code>android</code> <p>If you are using Eclipse and ADT, tools such as <code>adb</code> and <code>android</code>
are automatically called by Eclipse and ADT so you don't have to manually invoke these tools. are automatically called by Eclipse and ADT so you don't have to manually invoke these tools.
You need to be familiar with <code>adb</code>, however, because certain functions are not You need to be familiar with <code>adb</code>, however, because certain functions are not
@@ -109,19 +106,20 @@ accessible from
Eclipse, such as the <code>adb</code> shell commands. You might also need to call Keytool and Eclipse, such as the <code>adb</code> shell commands. You might also need to call Keytool and
Jarsigner to Jarsigner to
sign your applications, but you can set up Eclipse to do this automatically as well.</p> sign your applications, but you can set up Eclipse to do this automatically as well.</p>
<p>For more information on the tools provided with the Android SDK, see the <p>For more information on the tools provided with the Android SDK, see the
<a href="{@docRoot}guide/developing/tools/index.html">Tools</a> section of the documentation.</p> <a href="{@docRoot}guide/developing/tools/index.html">Tools</a> section of the documentation.</p>
<h2 id="ThirdParty">Other Third-Party Development Tools</h2> <h2 id="ThirdParty">Other Third-Party Development Tools</h2>
<p> <p>
The tools described in this section are not developed by the Android SDK team. The Android Dev Guide The tools described in this section are not developed by the Android SDK team. The Android Dev Guide
does not provide documentation for these tools. Please refer to the linked documents in each does not provide documentation for these tools. Please refer to the linked documents in each
section for documentation. section for documentation.
</p> </p>
<h3 id="IntelliJ">Developing in IntelliJ IDEA</h3> <h3 id="IntelliJ">Developing in IntelliJ IDEA</h3>
<div style="float: right"> <div style="float: right">
<img alt="The IntelliJ graphical user interface" height="500px" src="{@docRoot}images/developing/intellijidea_android_ide.png"/> <img alt="The IntelliJ graphical user interface" height="500px"
src="{@docRoot}images/developing/intellijidea_android_ide.png"/>
</div> </div>
<p> <p>
IntelliJ IDEA is a powerful Java IDE from JetBrains that provides IntelliJ IDEA is a powerful Java IDE from JetBrains that provides
@@ -148,5 +146,5 @@ Jarsigner to
<li> <li>
<a href="http://wiki.jetbrains.net/intellij/Android">IntelliJ IDEA Android Tutorials</a> <a href="http://wiki.jetbrains.net/intellij/Android">IntelliJ IDEA Android Tutorials</a>
</li> </li>
</ul> </ul>

52
docs/html/guide/guide_toc.cs
View File

@@ -406,6 +406,9 @@
<span class="en">Android Market Topics</span> <span class="en">Android Market Topics</span>
</h2> </h2>
<ul> <ul>
<li><a href="<?cs var:toroot ?>guide/publishing/publishing.html">
<span class="en">Publishing on Android Market</span>
</a></li>
<li><a href="<?cs var:toroot ?>guide/publishing/licensing.html"> <li><a href="<?cs var:toroot ?>guide/publishing/licensing.html">
<span class="en">Application Licensing</span></a> <span class="en">Application Licensing</span></a>
</li> </li>
@@ -649,28 +652,11 @@
<span class="zh-TW" style="display:none">發佈</span> <span class="zh-TW" style="display:none">發佈</span>
</h2> </h2>
<ul> <ul>
<li><a href="<?cs var:toroot ?>guide/publishing/app-signing.html"> <li><a href="<?cs var:toroot ?>guide/publishing/publishing_overview.html">
<span class="en">Signing Your Applications</span> <span class="en">Publishing Overview</span>
<span class="de" style="display:none">Signieren Ihrer Anwendungen</span> </a><span class="new">new!</span></li>
<span class="es" style="display:none">Firma de aplicaciones</span>
<span class="fr" style="display:none">Attribution de votre signature <br />à vos applications</span>
<span class="it" style="display:none">Firma delle applicazioni</span>
<span class="ja" style="display:none">アプリケーションへの署名</span>
<span class="zh-CN" style="display:none">应用程序签名</span>
<span class="zh-TW" style="display:none">簽署應用程式</span>
</a></li>
<li><a href="<?cs var:toroot ?>guide/publishing/versioning.html">
<span class="en">Versioning Your Applications</span>
<span class="de" style="display:none">Versionsverwaltung für Ihre <br />Anwendungen</span>
<span class="es" style="display:none">Versiones de las aplicaciones</span>
<span class="fr" style="display:none">Attribution d'une version à vos applications</span>
<span class="it" style="display:none">Controllo versioni delle applicazioni</span>
<span class="ja" style="display:none">アプリケーションのバージョニング</span>
<span class="zh-CN" style="display:none">应用程序版本控制</span>
<span class="zh-TW" style="display:none">應用程式版本設定</span>
</a></li>
<li><a href="<?cs var:toroot ?>guide/publishing/preparing.html"> <li><a href="<?cs var:toroot ?>guide/publishing/preparing.html">
<span class="en">Preparing to Publish</span> <span class="en">Preparing for Release</span>
<span class="de" style="display:none">Vorbereitung auf die Veröffentlichung</span> <span class="de" style="display:none">Vorbereitung auf die Veröffentlichung</span>
<span class="es" style="display:none">Publicación de aplicaciones</span> <span class="es" style="display:none">Publicación de aplicaciones</span>
<span class="fr" style="display:none">Préparation à la publication</span> <span class="fr" style="display:none">Préparation à la publication</span>
@@ -678,9 +664,29 @@
<span class="ja" style="display:none">公開の準備</span> <span class="ja" style="display:none">公開の準備</span>
<span class="zh-CN" style="display:none">准备发布</span> <span class="zh-CN" style="display:none">准备发布</span>
<span class="zh-TW" style="display:none">準備發佈</span> <span class="zh-TW" style="display:none">準備發佈</span>
</a><span class="new">updated</span></li>
<li><a href="<?cs var:toroot ?>guide/publishing/app-signing.html">
<span class="en">Signing Your Applications</span>
<span class="de" style="display:none">Signieren Ihrer Anwendungen</span>
<span class="es" style="display:none">Firma de aplicaciones</span>
<span class="fr" style="display:none">Attribution de votre signature <br />à vos
applications</span>
<span class="it" style="display:none">Firma delle applicazioni</span>
<span class="ja" style="display:none">アプリケーションへの署名</span>
<span class="zh-CN" style="display:none">应用程序签名</span>
<span class="zh-TW" style="display:none">簽署應用程式</span>
</a></li> </a></li>
<li><a href="<?cs var:toroot ?>guide/publishing/publishing.html"> <li><a href="<?cs var:toroot ?>guide/publishing/versioning.html">
<span class="en">Publishing on Android Market</span> <span class="en">Versioning Your Applications</span>
<span class="de" style="display:none">Versionsverwaltung für Ihre <br
/>Anwendungen</span>
<span class="es" style="display:none">Versiones de las aplicaciones</span>
<span class="fr" style="display:none">Attribution d'une version à vos
applications</span>
<span class="it" style="display:none">Controllo versioni delle applicazioni</span>
<span class="ja" style="display:none">アプリケーションのバージョニング</span>
<span class="zh-CN" style="display:none">应用程序版本控制</span>
<span class="zh-TW" style="display:none">應用程式版本設定</span>
</a></li> </a></li>
</ul> </ul>
</li> </li>

287
docs/html/guide/publishing/app-signing.jd
View File

@@ -7,7 +7,7 @@ page.title=Signing Your Applications
<h2>Quickview</h2> <h2>Quickview</h2>
<ul> <ul>
<li>All Android apps <em>must</em> be signed</a></li> <li>All Android apps <em>must</em> be signed</li>
<li>You can sign with a self-signed key</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>How you sign your apps is critical &mdash; read this document carefully</li>
<li>Determine your signing strategy early in the development process</li> <li>Determine your signing strategy early in the development process</li>
@@ -16,11 +16,11 @@ page.title=Signing Your Applications
<h2>In this document</h2> <h2>In this document</h2>
<ol> <ol>
<li><a href="#overview">Overview</a></li> <li><a href="#signing">Signing Process</a></li>
<li><a href="#strategies">Signing Strategies</a></li> <li><a href="#strategies">Signing Strategies</a></li>
<li><a href="#setup">Basic Setup for Signing</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="#debugmode">Signing in Debug Mode</a></li>
<li><a href="#releasemode">Signing for Public Release</a> <li><a href="#releasemode">Signing Release Mode</a>
<ol> <ol>
<li><a href="#cert">Obtain a suitable private key</a></li> <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="#releasecompile">Compile the application in release mode</a></li>
@@ -43,74 +43,67 @@ page.title=Signing Your Applications
</div> </div>
</div> </div>
<p>This document provides information about signing your Android applications prior to publishing them for mobile device users.</p> <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
<h2 id="overview">Overview</h2> 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
<p>The Android system requires that all installed applications be digitally user can install. The certificate does not need to be signed by a certificate authority: it is
signed with a certificate whose private key is held by the application's perfectly allowable, and typical, for Android applications to use self-signed certificates.</p>
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> <p>The important points to understand about signing Android applications are:</p>
<ul> <ul>
<li>All applications <em>must</em> be signed. The system will not install an application <li>All applications <em>must</em> be signed. The system will not install an application
that is not signed.</li> on an emulator or a device if it is not signed.</li>
<li>You can use self-signed certificates to sign your applications. No certificate authority <li>To test and debug your application, the build tools sign your application with a special debug
is needed.</li> key that is created by the Android SDK build tools.</li>
<li>When you are ready to release your application for end-users, you must sign it with a suitable private <li>When you are ready to release your application for end-users, you must sign it with a suitable
key. You can not publish an application that is signed with the debug key generated private key. You cannot publish an application that is signed with the debug key generated
by the SDK tools. by the SDK tools.</li>
</li> <li>You can use self-signed certificates to sign your applications. No certificate authority is
<li>The system tests a signer certificate's expiration date only at install time. If an needed.</li>
application's signer certificate expires after the application is installed, the application <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> will continue to function normally.</li>
<li>You can use standard tools &mdash; Keytool and Jarsigner &mdash; to generate keys and <li>You can use standard tools &mdash; Keytool and Jarsigner &mdash; to generate keys and
sign your application .apk files.</li> 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> <li>After you sign your application for release, we recommend that you use the
<code>zipalign</code> tool to optimize the final APK package.</li>
</ul> </ul>
<p>The Android system will not install or run an application that is not signed appropriately. This <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. 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 For this reason, you must <a href="#setup">set up signing</a> for your application before you can
run or debug it on an emulator or device.</p> run it 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 <h2 id="signing">Signing Process</h3>
for Eclipse and the Ant build tool offer two signing modes &mdash; <em>debug mode</em>
and <em>release mode</em>.
<ul> <p>The Android build process signs your application differently depending on which build mode you
<li>While developing and testing, you can compile in debug mode. use to build your application. There are two build modes: <em>debug mode</em> and <em>release
In debug mode, the build tools use the Keytool utility, included in the JDK, to create mode</em>. You use debug mode when you are developing and testing your application. You use
a keystore and key with a known alias and password. At each compilation, the tools then use release mode when you want to build a release version of your application that you can
the debug key to sign the application .apk file. Because the password is known, the tools distribute directly to users or publish on an application marketplace such as Android Market.</p>
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 <p>When you build in <em>debug mode</em> the Android SDK build tools use the Keytool utility
and then sign the .apk <span style="color:red">with your private key</span>. (included in the JDK) to create a debug key. Because the SDK build tools created the debug key,
There are two ways to do this: they know the debug key's alias and password. Each time you compile your application in debug mode,
<ul> the build tools use the debug key along with the Jarsigner utility (also included in the JDK) to
<li>Using Keytool and Jarsigner in the command-line. In this approach, sign your application's <code>.apk</code> file. Because the alias and password are known to the SDK
you first compile your application to an <em>unsigned</em> .apk. You must then sign build tools, the tools don't need to prompt you for the debug key's alias and password each time
the .apk manually with your private key you compile.</p>
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 <p>When you build in <em>release mode</em> you use your own private key to sign your application. If
for additional optimization.</p> you don't have a private key, you can use the Keytool utility to create one for you. When you
compile your application in release mode, the build tools use your private key along with the
Jarsigner utility to sign your application's <code>.apk</code> file. Because the certificate and
private key you use are your own, you will have to provide the password for the keystore and key
alias.</p>
<p>The debug signing process happens automatically when you run or debug your application using
Eclipse with the ADT plugin. Debug signing also happens automatically when you use the Ant build
script with the <code>debug</code> option. You can automate the release signing process by using the
Eclipse Export Wizard or by modifying the Ant build script and building with the
<code>release</code> option.</p>
<h2 id="strategies">Signing Strategies</h2> <h2 id="strategies">Signing Strategies</h2>
@@ -149,24 +142,24 @@ data in a secure manner. </li>
</ul> </ul>
<p>Another important consideration in determining your signing strategy is <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 how to set the validity period of the key that you will use to sign your
applications.</p> applications.</p>
<ul> <ul>
<li>If you plan to support upgrades for a single application, you should ensure <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 your key has a validity period that exceeds the expected lifespan of
that application. A validity period of 25 years or more is recommended. that application. A validity period of 25 years or more is recommended.
When your key's validity period expires, users will no longer be When your key's validity period expires, users will no longer be
able to seamlessly upgrade to new versions of your application.</li> able to seamlessly upgrade to new versions of your application.</li>
<li>If you will sign multiple distinct applications with the same key, <li>If you will sign multiple distinct applications with the same key,
you should ensure that your key's validity period exceeds the expected you should ensure that your key's validity period exceeds the expected
lifespan of <em>all versions of all of the applications</em>, including 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> 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 <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 key you use to sign the application(s) must have a validity period
ending after 22 October 2033. The Market server enforces this requirement ending after 22 October 2033. The Market server enforces this requirement
to ensure that users can seamlessly upgrade Market applications when to ensure that users can seamlessly upgrade Market applications when
new versions are available. </li> new versions are available. </li>
@@ -177,25 +170,21 @@ use a <a href="#cert">suitable certificate</a> to sign your applications. </p>
<h2 id="setup">Basic Setup for Signing</h2> <h2 id="setup">Basic Setup for Signing</h2>
<p>Before you begin, you should make sure that <p>Before you begin, make sure that the Keytool utility and Jarsigner utility are available to
Keytool is available to the SDK build the SDK build tools. Both of these tools are available in the JDK. In most cases, you can tell
tools. In most cases, you can tell the SDK build tools how to find Keytool by setting the SDK build tools how to find these utilities by setting your <code>JAVA_HOME</code> environment
your <code>JAVA_HOME</code> environment variable to references a suitable JDK. variable so it references a suitable JDK. Alternatively, you can add the JDK version of Keytool and
Alternatively, you can add the JDK version of Keytool to your <code>PATH</code> variable.</p> Jarsigner to your <code>PATH</code> variable.</p>
<p>If you are developing on a version of Linux that originally came with GNU Compiler for <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 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 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 <code>/usr/bin/keytool</code>. In this case, check the symlink target to be sure it points
to the Keytool in the JDK.</p> 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> <h2 id="debugmode">Signing in Debug Mode</h2>
<p>The Android build tools provide a debug signing mode that makes it easier for you <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 to develop and debug your application, while still meeting the Android system
requirement for signing your .apk. requirement for signing your .apk.
When using debug mode to build your app, the SDK tools invoke Keytool to automatically create When using debug mode to build your app, the SDK tools invoke Keytool to automatically create
@@ -209,7 +198,7 @@ you do not need to sign the package with your own key.</p>
<li>Key alias: "androiddebugkey"</li> <li>Key alias: "androiddebugkey"</li>
<li>Key password: "android"</li> <li>Key password: "android"</li>
<li>CN: "CN=Android Debug,O=Android,C=US"</li> <li>CN: "CN=Android Debug,O=Android,C=US"</li>
</ul></p> </ul>
<p>If necessary, you can change the location/name of the debug keystore/key or <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 supply a custom debug keystore/key to use. However, any custom debug
@@ -218,38 +207,38 @@ debug key (as described above). (To do so in Eclipse/ADT, go to
<strong>Windows</strong> &gt; <strong>Preferences</strong> &gt; <strong>Windows</strong> &gt; <strong>Preferences</strong> &gt;
<strong>Android</strong> &gt; <strong>Build</strong>.) </p> <strong>Android</strong> &gt; <strong>Build</strong>.) </p>
<p class="caution"><strong>Caution:</strong> You <em>cannot</em> release your application <p class="caution"><strong>Caution:</strong> You <em>cannot</em> release your application
to the public when signed with the debug certificate.</p> to the public when signed with the debug certificate.</p>
<h3>Eclipse Users</h3> <h3>Eclipse Users</h3>
<p>If you are developing in Eclipse/ADT (and have set up Keytool as described above in <p>If you are developing in Eclipse/ADT (and have set up Keytool and Jarsigner as described above in
<a href="#setup">Basic Setup for Signing</a>), <a href="#setup">Basic Setup for Signing</a>),
signing in debug mode is enabled by default. When you run or debug your 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 application, ADT signs the .apk with the debug certificate, runs {@code zipalign} on the
package, then installs it on package, then installs it on
the selected emulator or connected device. No specific action on your part is needed, the selected emulator or connected device. No specific action on your part is needed,
provided ADT has access to Keytool.</p> provided ADT has access to Keytool.</p>
<h3>Ant Users</h3> <h3>Ant Users</h3>
<p>If you are using Ant to build your .apk files, debug signing mode <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 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 (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 <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. 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. The script then also aligns the .apk with the <code>zipalign</code> tool.
No other action on your part is needed. Read No other action on your part is needed. Read
<a href="{@docRoot}guide/developing/building/building-cmdline.html#DebugMode">Building and Running Apps <a href="{@docRoot}guide/developing/building/building-cmdline.html#DebugMode">Building and Running Apps
on the Command Line</a> for more information.</p> on the Command Line</a> for more information.</p>
<h3 id="debugexpiry">Expiry of the Debug Certificate</h3> <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 <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> 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 <p>When the certificate expires, you will get a build error. On Ant builds, the error
looks like this:</p> looks like this:</p>
<pre>debug: <pre>debug:
@@ -258,59 +247,59 @@ looks like this:</p>
<p>In Eclipse/ADT, you will see a similar error in the Android console.</p> <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. <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, The default storage location for AVDs is in <code>~/.android/</code> on OS X and Linux,
in <code>C:\Documents and Settings\&lt;user>\.android\</code> on Windows XP, and in in <code>C:\Documents and Settings\&lt;user>\.android\</code> on Windows XP, and in
<code>C:\Users\&lt;user>\.android\</code> on Windows Vista and Windows 7.</p> <code>C:\Users\&lt;user>\.android\</code> on Windows Vista and Windows 7.</p>
<p>The next time you build, the build tools will regenerate a new keystore and debug key.</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 <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 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 error when trying to compile your application. For workaround information, see the
troubleshooting topic <a href="{@docRoot}resources/faq/troubleshooting.html#signingcalendar"> 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 I&nbsp;can't&nbsp;compile my app because the build tools generated an expired debug
certificate</a>. </p> certificate</a>. </p>
<h2 id="releasemode">Signing for Public Release</h2> <h2 id="releasemode">Signing in Release Mode</h2>
<p>When your application is ready for release to other users, you must:</p> <p>When your application is ready for release to other users, you must:</p>
<ol> <ol>
<li><a href="#cert">Obtain a suitable private key</a></li> <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="#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="#signapp">Sign your application with your private key</a></li>
<li><a href="#align">Align the final APK package</a></li> <li><a href="#align">Align the final APK package</a></li>
</ol> </ol>
<p>If you are developing in Eclipse with the ADT plugin, you can use the Export Wizard <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 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 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> skip to <a href="#ExportWizard">Compile and sign with Eclipse ADT</a>.</p>
<h3 id="cert">1. Obtain a suitable private key</h3> <h3 id="cert">1. Obtain a suitable private key</h3>
<p>In preparation for signing your application, you must first ensure that <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 you have a suitable private key with which to sign. A suitable private
key is one that:</p> key is one that:</p>
<ul> <ul>
<li>Is in your possession</li> <li>Is in your possession</li>
<li>Represents the personal, corporate, or organizational entity to be identified <li>Represents the personal, corporate, or organizational entity to be identified
with the application</li> with the application</li>
<li>Has a validity period that exceeds the expected lifespan of the application <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. 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 <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 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. application if it is signed with a key whose validity expires before that date.
</p></li> </p></li>
<li>Is not the debug key generated by the Android SDK tools. </li> <li>Is not the debug key generated by the Android SDK tools. </li>
</ul> </ul>
<p>The key may be self-signed. If you do not have a suitable key, you must <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 generate one using Keytool. Make sure that you have Keytool available, as described
in <a href="#setup">Basic Setup</a>.</p> in <a href="#setup">Basic Setup</a>.</p>
@@ -318,8 +307,8 @@ in <a href="#setup">Basic Setup</a>.</p>
command and pass any of the options listed below (and any others, as command and pass any of the options listed below (and any others, as
needed). </p> needed). </p>
<p class="warning"><strong>Warning:</strong> Keep your private key secure. <p class="warning"><strong>Warning:</strong> Keep your private key secure.
Before you run Keytool, make sure to read Before you run Keytool, make sure to read
<a href="#secure-key">Securing Your Private Key</a> for a discussion of how to keep <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 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 particular, when you are generating your key, you should select strong passwords
@@ -342,7 +331,7 @@ keys)</td>
the first 8 characters of the alias are used.</td> the first 8 characters of the alias are used.</td>
</tr> </tr>
<tr> <tr>
<td><code>-keyalg &lt;alg&gt;</code></td><td>The encryption algorithm to use <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> when generating the key. Both DSA and RSA are supported.</td>
</tr> </tr>
<tr> <tr>
@@ -354,7 +343,7 @@ general, we recommend using a key size of 2048 bits or higher. </td>
<td><code>-dname &lt;name&gt;</code></td><td><p>A Distinguished Name that describes <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 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 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 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> of the Distinguished Name fields (CN, OU, and so on).</p></td>
</tr> </tr>
<tr> <tr>
@@ -381,14 +370,14 @@ this way, your password is not stored in your shell history.</p></td>
<p>Here's an example of a Keytool command that generates a private key:</p> <p>Here's an example of a Keytool command that generates a private key:</p>
<pre>$ keytool -genkey -v -keystore my-release-key.keystore <pre>$ keytool -genkey -v -keystore my-release-key.keystore
-alias alias_name -keyalg RSA -keysize 2048 -validity 10000</pre> -alias alias_name -keyalg RSA -keysize 2048 -validity 10000</pre>
<p>Running the example command above, Keytool prompts you to provide <p>Running the example command above, Keytool prompts you to provide
passwords for the keystore and key, and to provide the Distinguished 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 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 <code>my-release-key.keystore</code>. The keystore and key are
protected by the passwords you entered. The keystore contains protected by the passwords you entered. The keystore contains
a single key, valid for 10000 days. The alias is a name that you &mdash; 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> will use later, to refer to this keystore when signing your application. </p>
@@ -401,7 +390,7 @@ http://java.sun.com/j2se/1.5.0/docs/tooldocs/#security</a></p>
<h3 id="releasecompile">2. Compile the application in release mode</h3> <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. <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 In release mode, the compiled application is not signed by default and you will need
to sign it with your private key.</p> to sign it with your private key.</p>
@@ -410,19 +399,19 @@ You can not release your application unsigned, or signed with the debug key.</p>
<h4>With Eclipse</h4> <h4>With Eclipse</h4>
<p>To export an <em>unsigned</em> .apk from Eclipse, right-click the project in the Package <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 Explorer and select <strong>Android Tools</strong> > <strong>Export Unsigned Application
Package</strong>. Then specify the file location for the unsigned .apk. Package</strong>. Then specify the file location for the unsigned .apk.
(Alternatively, open your <code>AndroidManifest.xml</code> file in Eclipse, open (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> 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 <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> <a href="#ExportWizard">Compiling and signing with Eclipse ADT</a>.</p>
<h4>With Ant</h4> <h4>With Ant</h4>
<p>If you are using Ant, you can enable release mode by using the <code>release</code> option <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 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> directory containing your {@code build.xml} file, the command would look like this:</p>
<pre>ant release</pre> <pre>ant release</pre>
@@ -437,7 +426,7 @@ and aligning for you, if you have provided the path to your keystore and the nam
your key alias in the project's {@code ant.properties} file. With this information provided, your key alias in the project's {@code ant.properties} file. With this information provided,
the build script will prompt you for your keystore and alias password when you perform 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 <code>ant release</code>, it will sign the package and then align it. The final output
file in {@code bin/} will instead be file in {@code bin/} will instead be
<code><em>&lt;your_project_name></em>-release.apk</code>. With these steps <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). 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 ant.properties} file, To learn how to specify your keystore and alias in the {@code ant.properties} file,
@@ -455,7 +444,7 @@ the keystore containing your private key is available.</p>
<p>To sign your application, you run Jarsigner, referencing both the <p>To sign your application, you run Jarsigner, referencing both the
application's .apk and the keystore containing the private key with which to 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> sign the .apk. The table below shows the options you could use. </p>
<table> <table>
<tr> <tr>
@@ -471,37 +460,37 @@ the keystore containing your private key.</td>
</tr> </tr>
<tr> <tr>
<td><code>-storepass &lt;password&gt;</code></td><td><p>The password for the <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 keystore. </p><p>As a security precaution, do not include this option
in your command line unless you are working at a secure computer. in your command line unless you are working at a secure computer.
If not supplied, Jarsigner prompts you to enter the password. In this If not supplied, Jarsigner prompts you to enter the password. In this
way, your password is not stored in your shell history.</p></td> way, your password is not stored in your shell history.</p></td>
</tr> </tr>
<tr> <tr>
<td><code>-keypass &lt;password&gt;</code></td><td><p>The password for the private <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 key. </p><p>As a security precaution, do not include this option
in your command line unless you are working at a secure computer. in your command line unless you are working at a secure computer.
If not supplied, Jarsigner prompts you to enter the password. In this If not supplied, Jarsigner prompts you to enter the password. In this
way, your password is not stored in your shell history.</p></td> way, your password is not stored in your shell history.</p></td>
</tr> </tr>
</table> </table>
<p>Here's how you would use Jarsigner to sign an application package called <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. <code>my_application.apk</code>, using the example keystore created above.
</p> </p>
<pre>$ jarsigner -verbose -keystore my-release-key.keystore <pre>$ jarsigner -verbose -keystore my-release-key.keystore
my_application.apk alias_name</pre> my_application.apk alias_name</pre>
<p>Running the example command above, Jarsigner prompts you to provide <p>Running the example command above, Jarsigner prompts you to provide
passwords for the keystore and key. It then modifies the .apk 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 in-place, meaning the .apk is now signed. Note that you can sign an
.apk multiple times with different keys.</p> .apk multiple times with different keys.</p>
<p>To verify that your .apk is signed, you can use a command like this:</p> <p>To verify that your .apk is signed, you can use a command like this:</p>
<pre>$ jarsigner -verify my_signed.apk</pre> <pre>$ jarsigner -verify my_signed.apk</pre>
<p>If the .apk is signed properly, Jarsigner prints "jar verified". <p>If the .apk is signed properly, Jarsigner prints "jar verified".
If you want more details, you can try one of these commands:</p> If you want more details, you can try one of these commands:</p>
<pre>$ jarsigner -verify -verbose my_application.apk</pre> <pre>$ jarsigner -verify -verbose my_application.apk</pre>
@@ -510,7 +499,7 @@ If you want more details, you can try one of these commands:</p>
<pre>$ jarsigner -verify -verbose -certs my_application.apk</pre> <pre>$ jarsigner -verify -verbose -certs my_application.apk</pre>
<p>The command above, with the <code>-certs</code> option added, will show you the <p>The command above, with the <code>-certs</code> option added, will show you the
"CN=" line that describes who created the key.</p> "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 <p class="note"><strong>Note:</strong> If you see "CN=Android Debug", this means the .apk was
@@ -534,21 +523,21 @@ 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 of the data from the package. The benefit is a reduction in the amount of
RAM consumed by the running application.</p> RAM consumed by the running application.</p>
<p>The <code>zipalign</code> tool is provided with the Android SDK, inside the <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> <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> <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 <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 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). 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> 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 <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}. 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> If you sign it after using {@code zipalign}, it will undo the alignment.</p>
<p>For more information, read about the <p>For more information, read about the
<a href="{@docRoot}guide/developing/tools/zipalign.html">zipalign</a> tool. <a href="{@docRoot}guide/developing/tools/zipalign.html">zipalign</a> tool.
@@ -568,15 +557,15 @@ in the <a href="#setup">Basic Setup for Signing</a>.</p>
<p>To create a signed and aligned .apk in Eclipse:</p> <p>To create a signed and aligned .apk in Eclipse:</p>
<ol> <ol>
<li>Select the project in the Package <li>Select the project in the Package
Explorer and select <strong>File > Export</strong>.</li> Explorer and select <strong>File > Export</strong>.</li>
<li>Open the Android folder, select Export Android Application, <li>Open the Android folder, select Export Android Application,
and click <strong>Next</strong>. and click <strong>Next</strong>.
<p>The Export Android Application wizard now starts, which will <p>The Export Android Application wizard now starts, which will
guide you through the process of signing your application, guide you through the process of signing your application,
including steps for selecting the private key with which to sign the .apk including steps for selecting the private key with which to sign the .apk
(or creating a new keystore and private key).</p> (or creating a new keystore and private key).</p>
<li>Complete the Export Wizard and your application will be compiled, <li>Complete the Export Wizard and your application will be compiled,
signed, aligned, and ready for distribution.</li> signed, aligned, and ready for distribution.</li>
</ol> </ol>
@@ -590,10 +579,10 @@ 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 could find and use them, your authoring identity and the trust of the user
are compromised. </p> are compromised. </p>
<p>If a third party should manage to take your key without your knowledge or <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 permission, that person could sign and distribute applications that maliciously
replace your authentic applications or corrupt them. Such a person could also replace your authentic applications or corrupt them. Such a person could also
sign and distribute applications under your identity that attack other sign and distribute applications under your identity that attack other
applications or the system itself, or corrupt or steal user data. </p> 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 <p>Your reputation as a developer entity depends on your securing your private
@@ -602,12 +591,12 @@ keeping your key secure: </p>
<ul> <ul>
<li>Select strong passwords for the keystore and key.</li> <li>Select strong passwords for the keystore and key.</li>
<li>When you generate your key with Keytool, <em>do not</em> supply the <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. <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, If you do so, your passwords will be available in your shell history,
which any user on your computer could access.</li> which any user on your computer could access.</li>
<li>Similarly, when signing your applications with Jarsigner, <li>Similarly, when signing your applications with Jarsigner,
<em>do not</em> supply the <code>-storepass</code> and <code>-keypass</code> <em>do not</em> supply the <code>-storepass</code> and <code>-keypass</code>
options at the command line. </li> options at the command line. </li>
<li>Do not give or lend anyone your private key, and do not let unauthorized <li>Do not give or lend anyone your private key, and do not let unauthorized
persons know your keystore and key passwords.</li> persons know your keystore and key passwords.</li>

550
docs/html/guide/publishing/preparing.jd
View File

@@ -1,253 +1,355 @@
page.title=Preparing to Publish: A Checklist page.title=Preparing for Release
@jd:body @jd:body
<p>Publishing an application means testing it, packaging it appropriately, and <div id="qv-wrapper">
making it available to users of Android-powered mobile devices.</p> <div id="qv">
<h2>Quickview</h2>
<ul>
<li>Learn which resources you'll need to release your app.</li>
<li>Find out how to configure and build your app for release.</li>
<li>Learn best practices for releasing your app.</li>
</ul>
<h2>In this document</h2>
<ol>
<li><a href="#publishing-intro">Introduction</a></li>
<li><a href="#publishing-gather">Gathering Materials and Resources</a></li>
<li><a href="#publishing-configure">Configuring Your Application</a></li>
<li><a href="#publishing-build">Building Your Application</a></li>
<li><a href="#publishing-resources">Preparing External Servers and Resources</a></li>
<li><a href="#publishing-test">Testing Your Application for Release</a></li>
</ol>
<h2>See also</h2>
<ol>
<li><a href="{@docRoot}guide/publishing/publishing_overview.html">Publishing Overview</a></li>
<li><a href="{@docRoot}guide/publishing/app-signing.html">Signing Your Applications</a></li>
<li><a href="{@docRoot}guide/publishing/publishing.html">Publishing on Android Market</a></li>
</ol>
</div>
</div>
<p>If you plan to publish your application for installation on <p>Before you distribute your Android application to users you need to prepare it for release. The
Android-powered devices, there are several things you need to do, to get preparation process is a required <a href="{@docRoot}guide/developing/index.html">development
your application ready. This document highlights the significant task</a> for all Android applications and is the first step in the publishing process (see figure
checkpoints for preparing your application for a successful release. 1).</p>
<p>When you prepare your application for release, you configure, build, and test a release
version of your application. The configuration tasks are straightforward, involving basic code
cleanup and code modification tasks that help optimize your application. The build process is
similar to the debug build process and can be done using JDK and Android SDK tools. The testing
tasks serve as a final check, ensuring that your application performs as expected under real-world
conditions. When you are finished preparing your application for release you have a signed
<code>.apk</code> file, which you can distribute directly to users or distribute through an
application marketplace such as Android Market.</p>
<p>This document summarizes the main tasks you need to perform to prepare your application for
release. The tasks that are described in this document apply to all Android applications regardless
how they are released or distributed to users. If you are releasing your application through Android
Market, you should also read <a href="{@docRoot}guide/publishing/publishing.html">Publishing on
Android Market</a> to be sure your release-ready application satisfies all Android Market
requirements.</p>
<p class="note"><strong>Note:</strong> As a best practice, your application should meet all of your
release criteria for functionality, performance, and stability before you perform the tasks outlined
in this document.</p>
<img src="{@docRoot}images/publishing/publishing_overview_prep.png"
alt="Shows how the preparation process fits into the development process"
height="190"
id="figure1" />
<p class="img-caption">
<strong>Figure 1.</strong> Preparing for release is a required <a
href="{@docRoot}guide/developing/index.html">development
task</a> and is the first step in the publishing process.
</p> </p>
<p>If you will publish your application on Android Market, please also see <a <h2 id="publishing-intro">Introduction</h2>
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, <p>To release your application to users you need to create a release-ready package that users can
see the <a href="{@docRoot}guide/publishing/publishing.html">Publishing Your install and run on their Android-powered devices. The release-ready package contains the same
Applications</a> document. </p> components as the debug <code>.apk</code> file &mdash; compiled source code, resources, manifest
file, and so on &mdash; and it is built using the same build tools. However, unlike the debug
<code>.apk</code> file, the release-ready <code>.apk</code> file is signed with your own certificate
and it is optimized with the zipalign tool.</p>
<div class="special"> <div class="figure" style="width:331px">
<img src="{@docRoot}images/publishing/publishing_preparing.png"
<p><a href="#releaseready">Before you consider your application ready for release</a>:</p> alt="Shows the five tasks you perform to prepare your app for release"
height="450" />
<ol> <p class="img-caption">
<li>Test your application extensively on an actual device </li> <strong>Figure 2.</strong> You perform five main tasks to prepare your application for
<li>Consider adding an End User License Agreement in your application</li> release.
<li>Consider adding licensing support</li> </p>
<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> </div>
<h2 id="releaseready">Before you consider your application ready for release</h2> <p>The signing and optimization tasks are usually seamless if you are building your application with
Eclipse and the ADT plugin or with the Ant build script (included with the Android SDK). For
example, you can use the Eclipse Export Wizard to compile, sign, and optimize your application all
at once. You can also configure the Ant build script to do the same when you build from the command
line.</p>
<h3 id="test">1. Test your application extensively on an actual device</h3> <p>To prepare your application for release you typically perform five main tasks (see figure 2).
Each main task may include one or more smaller tasks depending on how you are releasing your
application. For example, if you are releasing your application through Android Market you may want
to add special filtering rules to your manifest while you are configuring your application for
release. Similarly, to meet Android Market publishing guidelines you may have to prepare screenshots
and create promotional text while you are gathering materials for release.</p>
<p>It's important to test your application as extensively as possible, in as <p>You usually perform the tasks listed in figure 2 after you have throroughly debugged and tested
many areas as possible. To help you do that, Android provides a variety of your application. The Android SDK contains several tools to help you test and debug your Android
testing classes and tools. You can use applications. For more information, see the <a
{@link android.app.Instrumentation Instrumentation} to run JUnit and other href="{@docRoot}guide/developing/debugging/index.html">Debugging</a> and <a
test cases, and you can use testing href="{@docRoot}guide/developing/testing/index.html">Testing</a> sections in the Dev Guide.</p>
tools such as the <a href="{@docRoot}guide/developing/tools/monkey.html">UI/Application
Exerciser Monkey</a>. </p> <h2 id="publishing-gather">Gathering Materials and Resources</h2>
<p>To begin preparing your application for release you need to gather several supporting items. At a
minimum this includes cryptographic keys for signing your application and an application icon. You
might also want to include an end-user license agreement.</p>
<h4 id="publishing-keys">Cryptographic keys</h4>
<p>The Android system requires that each installed application be digitally signed with a
certificate that is owned by the application's developer (that is, a certificate for which the
developer holds the private key). The Android system uses the certificate as a means of identifying
the author of an application and establishing trust relationships between applications. The
certificate that you use for signing does not need to be signed by a certificate authority; the
Android system allows you to sign your applications with a self-signed certificate. To learn about
certificate requirements, see <a href="{@docRoot}guide/publishing/app-signing.html#cert">Obtain a
suitable private key</a>.</p>
<p>You may also have to obtain other release keys if your application accesses a service or uses a
third-party library that requires you to use a key that is based on your private key. For example,
if your application uses the <a
href="http://code.google.com/android/add-ons/google-apis/reference/com/google/android/maps/ MapView.
html">MapView</a> class, which is part of the <a
href="http://code.google.com/android/add-ons/google-apis/maps-overview.html">Google Maps external
library</a>, you will need to register your application with the Google Maps service and obtain
a Maps API key. For 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>
<h4>Application Icon</h4>
<p>Be sure you have an application icon and that it meets the recommended <a
href="{@docRoot}guide/practices/ui_guidelines/icon_design_launcher.html">icon guidelines</a>. Your
application's icon helps users identify your application on a device's Home
screen and in the Launcher window. It also appears in Manage Applications, My Downloads, and
elsewhere. In addition, publishing services such as Android Market display your icon to users.</p>
<p class="note"><strong>Note:</strong> If you are releasing your application on Android Market, you
need to create a high resolution
version of your icon. See <a
href="https://www.google.com/support/androidmarket/developer/bin/answer.py?answer=1078870">Graphic
Assets for your Application</a> for more information.</p>
<h4>End-user License Agreement</h4>
<p>Consider preparing an End User License Agreement (EULA) for your application. A EULA can help
protect your person, organization, and intellectual property, and we recommend that you provide one
with your application.</p>
<h4>Miscellaneous Materials</h4>
<p>You might also have to prepare promotional and marketing materials to publicize your application.
For example, if you are releasing your application on Android Market you will need to prepare some
promotional text and you will need to create screenshots of your application. For more
information, see
<a href="https://www.google.com/support/androidmarket/developer/bin/answer.py?answer=1078870">
Graphic Assets for your Application</a></p>
<h2 id="publishing-configure">Configuring Your Application for Release</h2>
<p>After you gather all of your supporting materials you can start configuring your application
for release. This section provides a summary of the configuration changes we recommend that you make
to your source code, resource files, and application manifest prior to releasing your application.
Although most of the configuration changes listed in this section are optional, they are
considered good coding practices and we encourage you to implement them. In some cases,
you may have already made these configuration changes as part of your development process.</p>
<h4>Choose a good package name</h4>
<p>Make sure you choose a package name that is suitable over the life of your application. You
cannot change the package name after you distribute your application to users. You can set the
package name in application's manifest file. For more information, see the <a
href="{@docRoot}guide/topics/manifest/manifest-element.html#package">package</a> attribute
documentation.</p>
<h4>Turn off logging and debugging</h4>
<p>Make sure you deactivate logging and disable the debugging option before you build your
application for release. You can deactivate logging by removing calls to
{@link android.util.Log} methods in your source files. You can disable debugging by removing the
<code>android:debuggable</code> attribute from the <code>&lt;application&gt;</code> tag in your
manifest file, or by setting the <code>android:debuggable</code> attribute to
<code>false</code> in your manifest file. Also, remove any log files or static test files that
were created in your project.</p>
<p>Also, you should remove all {@link android.os.Debug} tracing calls that you
added to your code, such as {@link android.os.Debug#startMethodTracing()} and
{@link android.os.Debug#stopMethodTracing()} method calls.</p>
<h4>Clean up your project directories</h4>
<p>Clean up your project and make sure it conforms to the directory structure described in <a
href="{@docRoot}guide/developing/projects/index.html#ApplicationProjects">Android Projects</a>.
Leaving stray or orphaned files in your project can prevent your application from compiling and
cause your application to behave unpredictably. At a minimum you should do the following cleanup
tasks:</p>
<ul> <ul>
<li>To ensure that your application will run properly for users, you should make <li>Review the contents of your <code>jni/</code>, <code>lib/</code>, and <code>src/</code>
every effort to obtain one or more physical mobile device(s) of the type on directories. The <code>jni/</code> directory should contain only source files associated with the
which you expect the application to run. You should then test your application <a href="{@docRoot}sdk/ndk/index.html">Android NDK</a>, such as
on the actual device, under realistic network conditions. Testing your <code>.c</code>, <code>.cpp</code>, <code>.h</code>, and <code>.mk</code> files. The
application on a physical device is very important, because it enables you to <code>lib/</code> directory should contain only third-party library files or private library
verify that your user interface elements are sized correctly (especially for files, including prebuilt shared and static libraries (for example, <code>.so</code> files). The
touch-screen UI) and that your application's performance and battery efficiency <code>src/</code> directory should contain only the source files for your application
are acceptable.</li> (<code>.java</code> and <code>.aidl</code> files). The <code>src/</code> directory should not
contain any <code>.jar</code> files.</li>
<li>If you can not obtain a mobile device of the type you are targeting for your <li>Check your project for private or proprietary data files that your application does not use
application, you can use emulator options such as <code>-dpi</code>, and remove them. For example, look in your project's <code>res/</code> directory for old
<code>-device</code>, <code>-scale</code>, <code>-netspeed</code>, drawable files, layout files, and values files that you are no longer using and delete them.</li>
<code>-netdelay</code>, <code>-cpu-delay</code> and others to model the <li>Check your <code>lib/</code> directory for test libraries and remove them if they are no
emulator's screen, network performance, and other attributes to match the target longer being used by your application.</li>
device to the greatest extent possible. You can then test your application's UI <li>Review the contents of your <code>assets/</code> directory and your <code>res/raw/</code>
and performance. However, we strongly recommend that you test your application directory for raw asset files and static files that you need to update or remove prior to
on an actual target device before publishing it. </li> release.</li>
</ul> </ul>
<h3 id="eula">2. Consider adding an End User License Agreement in your <h4>Review and update your manifest settings</h4>
application</h3>
<p>To protect your person, organization, and intellectual property, you may want <p>Verify that the following manifest items are set correctly:</p>
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> <ul>
<li>Register for a Maps API Key (see below), if your application uses MapView <li><a href="{@docRoot}guide/topics/manifest/uses-permission-element.html">
elements.</li> &lt;uses-permission&gt;</a> element
<li>Sign your application for release, later in the preparation process</li> <p>You should specify only those permissions that are relevant and required for your application.</p>
</li>
<li><code>android:icon</code> and <code>android:label</code> attributes
<p>You must specify values for these attributes, which are located in the
<a href="{@docRoot}guide/topics/manifest/application-element.html">&lt;application&gt;</a>
element.</p>
</li>
<li><code>android:versionCode</code> and <code>android:versionName</code> attributes.
<p>We recommend that you specify values for these attributes, which are located in the
<a href="{@docRoot}guide/topics/manifest/manifest-element.html">&lt;manifest&gt;</a>
element. For more information see
<a href="{@docRoot}guide/publishing/versioning.html">Versioning your Application</a>.</p>
</li>
</ul> </ul>
<h3 id="mapsApiKey">8. Register for a Maps API Key, if your application is using <p>There are several additional manifest elements that you can set if you are releasing your
MapView elements</h3> application on Android Market. For example, the <code>android:minSdkVersion</code> and
<code>android:targetSdkVersion</code> attributes, which are located in the <a
href="{@docRoot}guide/topics/manifest/uses-sdk-element.html"> &lt;uses-sdk&gt;</a> element. For more
information about these and other Android Market settings, see <a
href="{@docRoot}/guide//appendix/market-filters.html">Market Filters</a>.</p>
<div class="sidebox-wrapper"> <h4>Address compatibility issues</h4>
<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 <p>Android provides several tools and techniques to make your application compatible with a wide
register your application with the Google range of devices. To make your application available to the largest number of users, consider
Maps service and obtain a Maps API Key, before your MapView(s) will be able to doing the following:</p>
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 <ul>
debug key generated by the SDK tools. However, before publishing your <li><strong>Add support for multiple screen configurations</strong>
application, you must register for a new Maps API Key that is based on your <p>Make sure you meet the
private key. </p> <a href="{@docRoot}guide/practices/screens_support.html#screen-independence">
best practices for supporting multiple screens</a>. By supporting multiple screen configurations
you can create an application that functions properly and looks good on any of the screen sizes
supported by Android.</p>
</li>
<li><strong>Optimize your application for Android 3.0 devices.</strong>
<p>If your application is designed for devices older than Android 3.0, make it compatible
with Android 3.0 devices by following the guidelines and best practices described in
<a href="{@docRoot}guide/practices/optimizing-for-3.0.html">Optimizing Apps for Android 3.0
</a>.</p>
</li>
<li><strong>Consider using the Support Library</strong>
<p>If your application is designed for devices running Android 3.x, make your application
compatible with older versions of Android by adding the
<a href="{@docRoot}sdk/compatibility-library.html">Support Library</a> to your
application project. The Support Library provides static support libraries that you can add to
your Android application, which enables you to use APIs that are either not available on
older platform versions or use utility APIs that are not part of the framework APIs.</p>
</li>
</ul>
<p>If your application uses MapView elements, the important points to understand <h4>Update URLs for servers and services</h4>
are:</p>
<ol> <p>If your application accesses remote servers or services, make sure you are using the production
<li>You <em>must</em> obtain the Maps API Key before you compile your URL or path for the server or service and not a test URL or path.</p>
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> <h4>Implement Licensing (if you are releasing on Android Market)</h4>
<p>When you've prepared your application as described in the previous sections, <p>If you are releasing a paid application through Android Market, consider adding support for
you can compile your application for release.</p> 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 even if you are
releasing your app through Android Market.</p>
<h2 id="post-compile">After you compile your application</h2>
<p>For more information about Android Market Licensing Service and how to use it in your
<h3 id="signapp">9. Sign your application</h3> application, see <a href="{@docRoot}guide/publishing/licensing.html">Application Licensing</a>.</p>
<p>Sign your application using your private key and then <h2 id="publishing-build">Building Your Application for Release</h2>
align it with the {@code zipalign} tool. Signing your application
correctly is critically important. Please see <p>After you finish configuring your application you can build it into a release-ready
<a href="{@docRoot}guide/publishing/app-signing.html">Signing Your <code>.apk</code> fle that is signed and optimized. The JDK includes the tools for signing the
Applications</a> for complete information. </p> <code>.apk</code> file (Keytool and Jarsigner); the Android SDK includes the tools for compiling and
optimizing the <code>.apk</code> file. If you are using Eclipse with the ADT plugin or you are using
<h3 id="testapp">10. Test your compiled and signed application</h3> the Ant build script from the command line, you can automate the entire build process.</p>
<p>Before you release your compiled application, you should thoroughly test it <h3>Building with Eclipse</h3>
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 <p>You can use the Eclipse Export Wizard to build a release-ready <code>.apk</code> file that is
data properly. If they are not, go back to <a href="#mapsApiKey">Register for a signed with your private key and optimized. To learn how to run the Export Wizard, see
Maps API Key</a> and correct the problem. You should also ensure that the <a href="{@docRoot}guide/publishing/app-signing.html#ExportWizard">Compile and sign with Eclipse
application works correctly with any server-side services and data that you are ADT</a>. The Export Wizard compiles your application for release, signs your application with your
providing or are relying on and that the application handles any authentication private key, and optimizes your application with the zipalign tool. The Export Wizard should run
requirements correctly. </p> successfully if you have run or debugged your application from Eclipse and you have no errors in
your application (see <a href="{@docRoot}guide/developing/building/building-eclipse.html">Building
<p>After testing, you are now ready to publish your application to mobile device and Running from Eclipse with ADT</a> for more information.</p>
users.</p>
<p>The Export Wizard assumes that you have a <a href="#billing-keys">certificate and private key</a>
suitable for signing your application. If you do not have a suitable certificate and private key,
the Export Wizard will help you generate one (see
<a href="{@docRoot}guide/publishing/app-signing.html">Signing Your Applications</a> for more
information about the signing process and signing guidelines.</p>
<h3>Building with Ant</h3>
<p>You can use the Ant build script (included in the Android SDK) to build a release-ready
<code>.apk</code> file that is signed with your private key and optimized. To learn how to do this,
see <a href="{@docRoot}guide/developing/building/building-cmdline.html#ReleaseMode">Building in
Release Mode</a>. This build method assumes you have a <a href="#billing-keys">certificate and
private key</a> suitable for signing your application. If you do not have a suitable certificate and
private key, the Export Wizard will help you generate one (see
<a href="{@docRoot}guide/publishing/app-signing.html">Signing Your Applications</a> for more
information about the signing process and signing guidelines.</p>
<h2 id="publishing-resources">Preparing External Servers and Resources</h2>
<p>If your application relies on a remote server, make sure the server is secure and that it is
configured for production use. This is particularly important if you are implementing <a
href="{@docRoot}guide/market/billing/index.html">in-app billing</a> in your application and you are
performing the signature verification step on a remote server.</p>
<p>Also, if your application fetches content from a remote server or a real-time service (such as a
content feed), be sure the content you are providing is up to date and production-ready.</p>
<h2 id="publishing-test">Testing Your Application for Release</h2>
<p>Testing the release version of your application helps ensure that your application runs properly
under realistic device and network conditions. Ideally, you should test your application on at least
one handset-sized device and one tablet-sized device to verify that your user interface elements are
sized correctly and that your application's performance and battery efficiency are acceptable.</p>
<p>As a starting point for testing, see
<a href="{@docRoot}guide/topics/testing/what_to_test.html">What to Test</a>. This article provides
a summary of common Android situations that you should consider when you are testing. When you are
done testing and you are satisfied that the release version of your application
behaves correctly, you can release your application to users. For more information, see
<a href="{@docRoot}guide/publishing/publishing_overview.html#publishing-release">Releasing Your
Application to Users</a>. If you are publishing your application on Android Market, see
<a href="{@docRoot}guide/publishing/publishing.html">Publishing on Android Market</a>.</p>

236
docs/html/guide/publishing/publishing_overview.jd Executable file
View File

@@ -0,0 +1,236 @@
page.title=Publishing Overview
@jd:body
<div id="qv-wrapper">
<div id="qv">
<h2>Quickview</h2>
<ul>
<li>Learn how to publish Android apps.</li>
<li>Find out how to prepare apps for release.</li>
<li>Learn how to release apps to users.</li>
</ul>
<h2>In this document</h2>
<ol>
<li><a href="#publishing-prepare">Preparing Your Application for Release</a></li>
<li><a href="#publishing-release">Releasing Your Application to Users</a>
<ol>
<li><a href="#publishing-market">Releasing on Android Market</a></li>
<li><a href="#publishing-website">Releasing on your own website</a></li>
<li><a href="#publishing-email">Releasing through email</a></li>
</ol>
</ol>
<h2>See also</h2>
<ol>
<li><a href="{@docRoot}guide/publishing/publishing_preparing.html">Preparing for
Release</a></li>
<li><a href="{@docRoot}guide/publishing/publishing.html">Publishing on Android Market</a></li>
</ol>
</div>
</div>
<p>Publishing is the process that makes your Android applications available to users. When you
publish an Android application you perform two main tasks:</p>
<ul>
<li>You prepare the application for release.
<p>During the preparation step you build a release version of your application, which users can
download and install on their Android-powered devices.</p>
</li>
<li>You release the application to users.
<p>During the release step you publicize, sell, and distribute the release version of your
application to users.</p>
</li>
</ul>
<p>Usually, you release your application through an application marketplace, such as Android Market.
However, you can also release applications by sending them directly to users or by letting users
download them from your own website.</p>
<p>Figure 1 shows how the publishing process fits into the overall Android <a
href="{@docRoot}guide/developing/index.html">application development process</a>.
The publishing process is typically performed after you finish testing your application in a debug
environment. Also, as a best practice, your application should meet all of your release criteria for
functionality, performance, and stability before you begin the publishing process.</p>
<img src="{@docRoot}images/publishing/publishing_overview.png" alt="Shows where the publishing
process fits into the overall development process" height="86" id="figure1" />
<p class="img-caption">
<strong>Figure 1.</strong> Publishing is the last phase of the Android <a
href="{@docRoot}guide/developing/index.html">application development process</a>.
</p>
<h2 id="publishing-prepare">Preparing Your Application for Release</h2>
<p>Preparing your application for release is a multi-step process that involves the following
tasks:</p>
<ul>
<li>Configuring your application for release.
<p>At a minimum you need to remove {@link android.util.Log} calls and remove the
<a href="{@docRoot}guide/topics/manifest/application-element.html#debug">android:debuggable</a>
attribute from your manifest file. You should also provide values for the
<code>android:versionCode</code> and <code>android:versionName</code> attributes, which are
located in the
<a href="{@docRoot}guide/topics/manifest/manifest-element.html">&lt;manifest&gt;</a>
element. You may also have to configure several other settings to meet Android Market
requirements or accomodate whatever method you're using to release your application.</p>
</li>
<li>Building and signing a release version of your application.
<p>The Android Development Tools (ADT) plugin and the Ant build script that are provided
with the Android SDK tools provide everything you need to build and sign a release version of
your application.</p>
</li>
<li>Testing the release version of your application.
<p>Before you distribute your application, you should thoroughly test the release version on at
least one target handset device and one target tablet device.</p>
</li>
<li>Updating application resources for release.
<p>You need to be sure that all application resources such as multimedia files and graphics
are updated and included with your application or staged on the proper production servers.</p>
</li>
<li>Preparing remote servers and services that your application depends on.
<p>If your application depends on external servers or services, you need to be sure they
are secure and production ready.</p>
</li>
</ul>
<p>You may have to perform several other tasks as part of the preparation process. For example, you
will need to get a private key for signing your application, and you may need to get a Maps API
release key if you are using the <a
href="http://code.google.com/android/add-ons/google-apis/maps-overview.html">Google Maps external
library</a>. You will also need to create an icon for your application, and you may want to prepare
an End User License Agreement (EULA) to protect your person, organization, and intellectual
property.</p>
<p>When you are finished preparing your application for release you will have a signed
<code>.apk</code> file that you can distribute to users.</p>
<p>To learn how to prepare your application for release, see <a
href="{@docRoot}guide/publishing/preparing.html">Preparing for Release</a> in the Dev Guide. This
topic provides step-by-step instructions for configuring and building a release version of your
application.</p>
<h2 id="publishing-release">Releasing Your Application to Users</h2>
<p>You can release your Android applications several ways. Usually, you release applications
through an application marketplace, such as Android Market, but you can also release applications
on your own website or by sending an application directly to a user. Android Market is the
recommended marketplace for Android applications and is particularly useful if you want to
distribute your applications to a large global audience. The other two release methods&mdash;server
distribution and email distribution&mdash;are useful if you are releasing an application to a small
group of users (for example, a work group in an enterprise environment), or if you do not want to
make your application available to the general public.</p>
<h3 id="publishing-market">Releasing Your Applications on Android Market</h3>
<p>Android Market is a robust publishing platform that helps you publicize, sell, and distribute
your Android applications to users around the world. When you release your applications through
Android Market you have access to a suite of developer tools that let you analyze your sales,
identify market trends, and control who your applications are being distributed to. You also have
access to several revenue-enhancing features that are not available anywhere else, such as <a
href="{@docRoot}guide/market/billing/index.html">in-app billing</a> and <a
href="{@docRoot}guide/publishing/licensing.html">application licensing</a>. This rich array of tools
and features, coupled with numerous end-user community features, makes Android Market the premier
marketplace for selling and buying Android applications.</p>
<p>Releasing your application on Android Market is a simple process that involves four basic
steps:</p>
<div class="figure" style="width:275px">
<img src="{@docRoot}images/publishing/publishing_unknown_sources.png"
alt="Screenshot showing the graphical user interface element that allows unknown sources
to be installed" />
<p class="img-caption">
<strong>Figure 2.</strong> The <strong>Unknown sources</strong> setting lets you install
applications that are not published on Android Market .
</p>
</div>
<ul>
<li>Preparing promotional materials.
<p>To fully leverage the marketing and publicity capabilities of Android Market, you need to
create promotional materials for your application, such as screenshots, videos, graphics, and
promotional text.</p>
</li>
<li>Planning publishing options.
<p>Android Market lets you target your application to a worldwide pool of users and devices.
Using various Android Market tools, you can choose the countries you want to reach, the
price you want to charge in each country, and the devices you want to target. You can also
use Android Market's filtering settings to target specific device features and capabilities.</p>
</li>
<li>Configuring publishing options and uploading assets.
<p>After you create your promotional materials and determine which publishing options are
suitable for your application, you can use the Android Market developer console to configure
those options and upload the promotional materials. You can also use the developer console to
upload your application as a draft (unpublished) application, which lets you do final
testing before you publish it for final release.</p>
</li>
<li>Publishing the release version of your application.
<p>When you are satisfied that your publishing settings are correctly configured and your
uploaded application is ready to be released to the public, you can simply click
<strong>Publish</strong > in the developer console and within minutes your application will be
live and available for download around the world.</p>
</li>
</ul>
<p>For information about Android Market, see <a
href="{@docRoot}guide/publishing/publishing.html#market">Publishing on Android Market</a>. This
topic provides an introduction to Android Market features and provides a step-by-step guide for
distributing your applications on Android Market.</p>
<h3 id="publishing-website">Releasing your application on your own website</h3>
<p>If you do not want to release your application on an application marketplace like Android Market,
you can release your application by making it available for download on your own website or server.
To do this, you must first prepare your application for release (that is, you must build it for
release and sign it). Then all you need to do is host the release-ready application on your website
and provide a download link for the application. When users browse to your website with their
Android-powered devices and download your application, the Android system will automatically start
installing the application on the device. However, the installation process will start automatically
only if the user has configured their device to allow the installation of non-Android Market
applications.</p>
<div class="figure" style="width:275px">
<img src="{@docRoot}images/publishing/publishing_via_email.png"
alt="Screenshot showing the graphical user interface users see when you send them an app"
height="453" />
<p class="img-caption">
<strong>Figure 3.</strong> Users can simply click <strong>Install</strong> when you send them
an application via email.
</p>
</div>
<p>By default, Android-powered devices allow users to install applications only if the applications
have been downloaded from Android Market. To allow the installation of applications from other
sources, users need to enable the <strong>Unknown sources</strong> setting on their devices, and
they need to make this configuration change before they download your application to their
device (see figure 2).</p>
<p class="note"><strong>Note:</strong> Some network providers do not allow users to install
applications from unknown sources.</p>
<p>Although it is relatively easy to release your application on your own website, it can be
inefficient and cumbersome. For example, if you want to monetize your application you will
have to process and track all financial transactions yourself and you will not be able to use
Android Market's in-app billing feature to sell in-app products. In addition, you will not be
able to use the licensing feature to help prevent unauthorized installation and use of your
application.</p>
<h3 id="publishing-email">Releasing your application through email</h3>
<p>The easiest and quickest way to release your application is to send it to a user through
email. To do this, you prepare your application for release and then attach it to an email
and send it to a user. When the user opens your email message on their Android-powered device
the Android system will recognize the <code>.apk</code> and display an <strong>Install Now</strong>
button in the email message (see figure 3). Users can install your application by touching the
button.</p>
<p class="note"><strong>Note:</strong> The <strong>Install Now</strong> button appears only if a
user has configured their device to allow the installation of non-Android Market applications and
they open your email with the native Gmail application.</p>
<p>Releasing applications through email is convenient if you are sending your application to
only a few trusted users, but it provides few protections from piracy and unauthorized
distribution; that is, anyone you send your application to can simply forward it to someone else.
else.

39
docs/html/guide/publishing/versioning.jd
View File

@@ -32,8 +32,8 @@ page.title=Versioning Your Applications
</div> </div>
</div> </div>
<p>Versioning is a critical component of your application upgrade/maintenance <p>Versioning is a critical component of your application upgrade and maintenance
strategy. </p> strategy. Versioning is important because:</p>
<ul> <ul>
<li>Users need to have specific information about the application version that <li>Users need to have specific information about the application version that
@@ -48,15 +48,14 @@ users. A publishing service may also need to check the application version to
determine compatibility and establish upgrade/downgrade relationships.</li> determine compatibility and establish upgrade/downgrade relationships.</li>
</ul> </ul>
<p>The Android system itself <em>does not ever</em> check the application version <p>The Android system does not use app version information to enforce
information for an application, such as to enforce restrictions on upgrades, restrictions on upgrades, downgrades, or compatibility of third-party apps. Instead, you (the
compatibility, and so on. Instead, only users or applications themselves are developer) are responsible for enforcing version restrictions within your application or by
responsible for enforcing any version restrictions for applications themselves. </p> 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
<p>The Android system <em>does</em> check any system version compatibility expressed manifest. This attribute allows an application to specify the minimum system API with which it is
by an application in its manifest, in the <code>minSdkVersion</code> attribute. This compatible. For more information see <a href="#minsdkversion">Specifying Minimum System API
allows an application to specify the minimum system API with which is compatible. Version</a>.</p>
For more information see <a href="#minsdkversion">Specifying Minimum System API Version</a>.
<h2 id="appversioning">Setting Application Version</h2> <h2 id="appversioning">Setting Application Version</h2>
<p>To define the version information for your application, you set attributes in <p>To define the version information for your application, you set attributes in
@@ -65,7 +64,7 @@ always define values for both of them: </p>
<ul> <ul>
<li><code>android:versionCode</code> &mdash; An integer value that represents <li><code>android:versionCode</code> &mdash; An integer value that represents
the version of the application code, relative to other versions. the version of the application code, relative to other versions.
<p>The value is an integer so that other applications can programmatically <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 evaluate it, for example to check an upgrade or downgrade relationship. You can
@@ -83,7 +82,7 @@ user (see <code>android:versionName</code>, below). Applications and publishing
services should not display this version value to users.</p> services should not display this version value to users.</p>
</li> </li>
<li><code>android:versionName</code> &mdash; A string value that represents the <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. 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 <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 &lt;major&gt;.&lt;minor&gt;.&lt;point&gt; string, or as any other type of
absolute or relative version identifier. </p> absolute or relative version identifier. </p>
@@ -121,20 +120,20 @@ corresponds to a minor follow-on release, as shown by the
<p>The Android framework provides an API to let applications query the system <p>The Android framework provides an API to let applications query the system
for version information about your application. To obtain version information, for version information about your application. To obtain version information,
applications use the applications use the
{@link android.content.pm.PackageManager#getPackageInfo(java.lang.String, int)} {@link android.content.pm.PackageManager#getPackageInfo(java.lang.String, int)}
method of {@link android.content.pm.PackageManager PackageManager}. </p> method of {@link android.content.pm.PackageManager PackageManager}. </p>
<h2 id="minsdkversion">Specifying Your Application's System API Requirements</h2> <h2 id="minsdkversion">Specifying Your Application's System API Requirements</h2>
<p>If your application requires a specific minimum version of the Android <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 platform, or is designed only to support a certain range of Android platform
versions, you can specify those version requirements as API Level identifiers versions, you can specify those version requirements as API Level identifiers
in the application's manifest file. Doing so ensures that your in the application's manifest file. Doing so ensures that your
application can only be installed on devices that application can only be installed on devices that
are running a compatible version of the Android system. </p> are running a compatible version of the Android system. </p>
<p>To specify API Level requirements, add a <code>&lt;uses-sdk&gt;</code> <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> element in the application's manifest, with one or more of these attributes: </p>
<ul> <ul>
@@ -144,10 +143,10 @@ by the platform's API Level identifier. </li>
<li><code>android:targetSdkVersion</code> &mdash; Specifies the API Level <li><code>android:targetSdkVersion</code> &mdash; Specifies the API Level
on which the application is designed to run. In some cases, this allows the 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 application to use manifest elements or behaviors defined in the target
API Level, rather than being restricted to using only those defined API Level, rather than being restricted to using only those defined
for the minimum API Level.</li> for the minimum API Level.</li>
<li><code>android:maxSdkVersion</code> &mdash; The maximum version <li><code>android:maxSdkVersion</code> &mdash; The maximum version
of the Android platform on which the application is designed to run, 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 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> href="{@docRoot}guide/topics/manifest/uses-sdk-element.html"><code>&lt;uses-sdk&gt;</code></a>
documentation before using this attribute. </li> documentation before using this attribute. </li>

BIN
docs/html/images/developing/developing_overview.png Executable file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 120 KiB

BIN
docs/html/images/publishing/publishing_overview.png Executable file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 26 KiB

BIN
docs/html/images/publishing/publishing_overview_prep.png Executable file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 36 KiB

BIN
docs/html/images/publishing/publishing_preparing.png Executable file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 65 KiB

BIN
docs/html/images/publishing/publishing_unknown_sources.png Executable file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 48 KiB

BIN
docs/html/images/publishing/publishing_via_email.png Executable file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 52 KiB