diff options
Diffstat (limited to 'docs/html/guide/publishing')
| -rw-r--r-- | docs/html/guide/publishing/app-signing.jd | 489 | ||||
| -rw-r--r-- | docs/html/guide/publishing/preparing.jd | 254 | ||||
| -rw-r--r-- | docs/html/guide/publishing/publishing.jd | 250 | ||||
| -rw-r--r-- | docs/html/guide/publishing/versioning.jd | 155 |
4 files changed, 1148 insertions, 0 deletions
diff --git a/docs/html/guide/publishing/app-signing.jd b/docs/html/guide/publishing/app-signing.jd new file mode 100644 index 0000000..28c927a --- /dev/null +++ b/docs/html/guide/publishing/app-signing.jd @@ -0,0 +1,489 @@ +page.title=Signing Your Applications +@jd:body + +<div id="qv-wrapper"> +<div id="qv"> + +<h2>Signing quickview</h2> + +<ul> +<li>All Android apps <em>must</em> be signed</a></li> +<li>You can sign with a self-signed key</li> +<li>How you sign your apps is critical — read this document carefully</li> +<li>Determine your signing strategy early in the development process</li> +</ul> + +<h2>In this document</h2> + +<ol> +<li><a href="#overview">Overview</a></li> +<li><a href="#strategies">Signing Strategies</a></li> +<li><a href="#setup">Basic Setup for Signing</a></li> +<li><a href="#debugmode">Signing in Debug Mode</a></li> +<li><a href="#releasemode">Signing for Public Release</a> + <ol> + <li><a href="#releasecompile">Compiling for Release</a></li> + <li><a href="#cert">Obtaining a Suitable Private Key</a></li> + <li><a href="#signapp">Signing Your Application</a></li> + </ol> +</li> +<li><a href="#secure-key">Securing Your Private Key</a></li> + +</ol> + +<h2>See also</h2> + +<ol> +<li><a href="{@docRoot}guide/publishing/versioning.html">Versioning Your Applications</a></li> +<li><a href="{@docRoot}guide/publishing/preparing.html">Preparing to Publish</a></li> +</ol> + +</div> +</div> + +<p>This document provides information about signing your Android applications prior to publishing them for mobile device users.</p> + +<h2 id="overview">Overview</h2> + +<p>The Android system requires that all installed applications be digitally +signed with a certificate whose private key is held by the application's +developer. The system uses the certificate as a means of identifying the author of +an application and establishing trust relationships between applications, rather +than for controlling which applications the user can install. The certificate +does not need to be signed by a certificate authority: it is perfectly +allowable, and typical, for Android applications to use self-signed +certificates.</p> + +<p>The important points to understand about signing Android applications are:</p> + +<ul> + <li>All applications <em>must</em> be signed. The system will not install an application +that is not signed.</li> + <li>You can use self-signed certificates to sign your applications. No certificate authority +is needed.</li> + <li>When you are ready to publish your application, you must sign it with a suitable private +key. You can not publish an application that is signed with the default key generated +by the SDK tools. + </li> + <li>The system tests a signer certificate's expiration date only at install time. If an +application's signer certificate expires after the application is installed, the application +will continue to function normally.</li> + <li>You can use standard tools — Keytool and Jarsigner — to generate keys and +sign your application .apk files.</li> +</ul> + +<p>The Android system will not install or run an application that is not signed appropriately. This +applies wherever the Android system is run, whether on an actual device or on the emulator. +For this reason, you must set up signing for your application before you will be able to +run or debug it on an emulator or device.</p> + +<p>The Android SDK tools assist you in signing your applications when debugging. Both the ADT Plugin +for Eclipse and the Ant build tool offer two signing modes — debug mode and release mode. + +<ul> +<li>In debug mode, the build tools use the Keytool utility, included in the JDK, to create +a keystore and key with a known alias and password. At each compilation, the tools then use +the debug key to sign the application .apk file. Because the password is known, the tools +don't need to prompt you for the keystore/key password each time you compile.</li> + +<li>When your application is ready for release, you compile it in release signing mode. +In this mode, the tools compile your .apk <em>without</em> signing it. You must then sign +the .apk manually — <span style="color:red">with your private key</span> — +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> +</ul> + +<h2 id="strategies">Signing Strategies</h2> + +<p>Some aspects of application signing may affect how you approach the development +of your application, especially if you are planning to release multiple +applications. </p> + +<p>In general, the recommended strategy for all developers is to sign +all of your applications with the same certificate, throughout the expected +lifespan of your applications. There are several reasons why you should do so: </p> + +<ul> +<li>Application upgrade — As you release upgrades to your +application, you will want to sign the upgrades with the same certificate, if you +want users to upgrade seamlessly to the new version. When the system is +installing an update to an application, if any of the certificates in the +new version match any of the certificates in the old version, then the +system allows the update. If you sign the version without using a matching +certificate, you will also need to assign a different package name to the +application — in this case, the user installs the new version as a +completely new application. </li> + +<li>Application modularity — The Android system allows applications that +are signed by the same certificate to run in the same process, if the +applications so request, so that the system treats them as a single application. +In this way you can deploy your application in modules, and users can update +each of the modules independently if needed.</li> + +<li>Code/data sharing through permissions — The Android system provides +signature-based permissions enforcement, so that an application can expose +functionality to another application that is signed with a specified +certificate. By signing multiple applications with the same certificate and +using signature-based permissions checks, your applications can share code and +data in a secure manner. </li> + +</ul> + +<p>Another important consideration in determining your signing strategy is +how to set the validity period of the key that you will use to sign your +applications.</p> + +<ul> +<li>If you plan to support upgrades for a single application, you should ensure +that your key has a validity period that exceeds the expected lifespan of +that application. A validity period of 25 years or more is recommended. +When your key's validity period expires, users will no longer be +able to seamlessly upgrade to new versions of your application.</li> + +<li>If you will sign multiple distinct applications with the same key, +you should ensure that your key's validity period exceeds the expected +lifespan of <em>all versions of all of the applications</em>, including +dependent applications that may be added to the suite in the future. </li> + +<li>If you plan to publish your application(s) on Android Market, the +key you use to sign the application(s) must have a validity period +ending after 22 October 2033. The Market server enforces this requirement +to ensure that users can seamlessly upgrade Market applications when +new versions are available. </li> +</ul> + +<p>As you design your application, keep these points in mind and make sure to +use a <a href="#cert">suitable certificate</a> to sign your applications. </p> + +<h2 id="setup">Basic Setup for Signing</h2> + +<p>To support the generation of a keystore and debug key, you should first make sure that +Keytool is available to the SDK build +tools. In most cases, you can tell the SDK build tools how to find Keytool by making sure +that your JAVA_HOME environment variable is set and that it references a suitable JDK. +Alternatively, you can add the JDK version of Keytool to your PATH variable.</p> + +<p>If you are developing on a version of Linux that originally came with GNU Compiler for +Java, make sure that the system is using the JDK version of Keytool, rather than the gcj +version. If Keytool is already in your PATH, it might be pointing to a symlink at +/usr/bin/keytool. In this case, check the symlink target to make sure that it points +to the Keytool in the JDK.</p> + +<p>If you will release your application to the public, you will also need to have +the Jarsigner tool available on your machine. Both Jarsigner and Keytool are included +in the JDK. </p> + +<h2 id="debugmode">Signing in Debug Mode</h2> + +<p>The Android build tools provide a debug signing mode that makes it easier for you +to develop and debug your application, while still meeting the Android system +requirement for signing your .apk when it is installed in the emulator or a device. +When you use debug mode, the SDK tools invoke Keytool to create a debug +keystore and key. </p> + +<p>The SDK tools create the debug keystore/key with predetermined names/passwords;</p> +<ul> +<li>Keystore name — "debug.keystore"</li> +<li>Keystore password — "android"</li> +<li>Key alias — "androiddebugkey"</li> +<li>Key password — "android"</li> +<li>CN — "CN=Android Debug,O=Android,C=US"</li> +</ul></p> + +<p>If you are developing in Eclipse/ADT and have set up Keytool as described +above, signing in debug mode is enabled by default. When you run or debug your +application, ADT signs the .apk with the debug certificate and installs it on +the emulator. No specific action on your part is needed, provided ADT has +access to Keytool.</p> + +<p>If you use Ant to build your .apk files, debug signing mode +is enabled by default, assuming that you are using a build.xml file generated by the +activitycreator tool included in the latest SDK. When you run Ant against build.xml to +compile your app, the build script generates a keystore/key and signs the .apk for you. +No specific action on your part is needed.</p> + +<p>If necessary, you can change the location/name of the debug keystore/key or +supply a custom debug keystore/key to use. In Eclipse/ADT, you can use +<strong>Windows</strong> > <strong>Prefs</strong> > +<strong>Android</strong> > <strong>Build</strong>. However, any custom debug +keystore/key must use the same keystore/key names and passwords as the default +debug key (as described above). </p> + +<p>Note that you <em>cannot</em> release your application to the public if it +is signed with the debug certificate. </p> + +<h3 id="debugexpiry">Expiry of the Debug Certificate</h3> + +<p>The self-signed certificate used to sign your application in debug mode (the default on +Eclipse/ADT and Ant builds) will have an expiration date of 365 days from its creation date.</p> + +<p>When the certificate expires, you will get a build error. On Ant builds, the error +looks like this:</p> + +<pre>debug: +[echo] Packaging bin/samples-debug.apk, and signing it with a debug key... +[exec] Debug Certificate expired on 8/4/08 3:43 PM</pre> + +<p>In Eclipse/ADT, you will see a similar error in the Android console.</p> + +<p>To fix this problem, simply delete the <code>debug.keystore</code> file. On Linux/Mac OSX, +the file is stored in <code>~/.android</code>. On Windows XP, the file is stored in <code> +C:\Documents and Settings\<user>\Local Settings\Application Data\Android</code>. +On Windows Vista, the file is stored in <code> +C:\Users\<user>\AppData\Local\Android</code>.</p> + +<p>The next time you build, the build tools will regenerate a new keystore and debug key.</p> + +<p>Note that, if your development machine is using a non-Gregorian locale, the build +tools may erroneously generate an already-expired debug certificate, so that you get an +error when trying to compile your application. For workaround information, see the +troubleshooting topic <a href="{@docRoot}guide/appendix/faq/troubleshooting.html#signingcalendar"> +I can't compile my app because the build tools generated an expired debug +certificate</a>. </p> + +<h2 id="releasemode">Signing for Public Release</h2> + +<p>When your application is ready for release to other users, you must:</p> +<ol> +<li>Compile the application in release mode</li> +<li>Obtain a suitable private key, and then</li> +<li>Sign the application with your private key</li> +<li>Secure your private key</li> +</ol> + +<p>The sections below provide information about these steps. </p> + +<h3 id="releasecompile">Compiling for Release</h3> + +<p>To prepare your application for release, you must first compile it in release mode. +In release mode, the Android build tools compile your application as usual, +but without signing it with the debug key. </p> + +<p>If you are developing in Eclipse/ADT, right-click the project in the Package +pane and select <strong>Android Tools</strong> > <strong>Export Application +Package</strong>. You can then specify the file location for the unsigned .apk. +Alternatively, you can follow the "Exporting the unsigned .apk" +link in the Manifest Editor overview page. </p> + +<p>If you are using Ant, all you need to do is specify the build target +"release" in the Ant command. For example, if you are running Ant from the +directory containing your build.xml file, the command would look like this:</p> + +<pre>$ ant release</pre> + +<p>The build script compiles the application .apk without signing it. + +<p>Note that you can not release your application unsigned, or signed with the debug key.</p> + +<h3 id="cert">Obtaining a Suitable Private Key</h3> + +<p>In preparation for signing your application, you must first ensure that +you have a suitable private key with which to sign. A suitable private +key is one that:</p> + +<ul> +<li>Is in your possession</li> +<li>Represents the personal, corporate, or organizational entity to be identified +with the application</li> +<li>Has a validity period that exceeds the expected lifespan of the application +or application suite. A validity period of more than 25 years is recommended. +<p>If you plan to publish your application(s) on Android Market, note that a +validity period ending after 22 October 2033 is a requirement. You can not upload an +application if it is signed with a key whose validity expires before that date. +</p></li> +<li>Is not the debug key generated by the Android SDK tools. </li> +</ul> + +<p>The key may be self-signed. If you do not have a suitable key, you must +generate one using Keytool. Make sure that you have Keytool available, as described +in <a href="#setup">Basic Setup</a>.</p> + +<p>To generate a self-signed key with Keytool, use the <code>keytool</code> +command and pass any of the options listed below (and any others, as +needed). </p> + +<p class="warning">Before you run Keytool, make sure to read +<a href="#secure-key">Securing Your Private Key</a> for a discussion of how to keep +your key secure and why doing so is critically important to you and to users. In +particular, when you are generating your key, you should select strong passwords +for both the keystore and key.</p> + +<table> +<tr> +<th>Keytool Option</th> +<th>Description</th> +</tr> +<tr> +<td><code>-genkey</code></td><td>Generate a key pair (public and private +keys)</td> +</tr> +<tr> +<td><code>-v</code></td><td>Enable verbose output.</td> +</tr> +<tr> +<td><code>-keystore <keystore-name>.keystore</code></td><td>A name +for the keystore containing the private key.</td> +</tr> +<tr> +<td><code>-storepass <password></code></td><td><p>A password for the +keystore.</p><p>As a security precaution, do not include this option +in your command line unless you are working at a secure computer. +If not supplied, Keytool prompts you to enter the password. In this +way, your password is not stored in your shell history.</p></td> +</tr> +<tr> +<td><code>-alias <alias_name></code></td><td>An alias for the key.</td> +</tr> +<tr> +<td><code>-keyalg <alg></code></td><td>The encryption algorithm to use +when generating the key. Both DSA and RSA are supported.</td> +</tr> +<tr> +<td><code>-dname <name></code></td><td><p>A Distinguished Name that describes +who created the key. The value is used as the issuer and subject fields in the +self-signed certificate. </p><p>Note that you do not need to specify this option +in the command line. If not supplied, Jarsigner prompts you to enter each +of the Distinguished Name fields (CN, OU, and so on).</p></td> +</tr> +<tr> +<td><code>-validity <valdays></code></td><td><p>The validity period for the +key, in days. </p><p><strong>Note:</strong> A value of 10000 or greater is recommended.</p></td> +</tr> +<tr> +<td><code>-keypass <password></code></td><td><p>The password for the key.</p> +<p>As a security precaution, do not include this option +in your command line unless you are working at a secure computer. +If not supplied, Keytool prompts you to enter the password. In this +way, your password is not stored in your shell history.</p></td> +</tr> +</table> + + +<p>Here's an example of a Keytool command that generates a private key:</p> + +<pre>$ keytool -genkey -v -keystore my-release-key.keystore +-alias alias_name -keyalg RSA -validity 10000</pre> + +<p>Running the example command above, Keytool prompts you to provide +passwords for the keystore and key, and to provide the Distinguished +Name fields for your key. It then generates the keystore as a file called +<code>my-release-key.keystore</code>. The keystore and key are +protected by the passwords you entered. The keystore contains +a single key, valid for 10000 days. The alias is a name that you — +will use later, to refer to this keystore when signing your application. </p> + +<p>For more information about Keytool, see the documentation at +<a +href="http://java.sun.com/j2se/1.5.0/docs/tooldocs/#security"> +http://java.sun.com/j2se/1.5.0/docs/tooldocs/#security</a></p> + +<h3 id="signapp">Signing Your Application</h3> + +<p>When you are ready to actually sign your .apk for release, you can do so +using the Jarsigner tool. Make sure that you have Jarsigner available on your +machine, as described in <a href="#setup">Basic Setup</a>. Also, make sure that +the keystore containing your private key is available.</p> + +<p>To sign your application, you run Jarsigner, referencing both the +application's .apk and the keystore containing the private key with which to +sign the .apk. The table below shows the options you could use. <p> + +<table> +<tr> +<th>Jarsigner Option</th> +<th>Description</th> +</tr> +<tr> +<td><code>-keystore <keystore-name>.keystore</code></td><td>The name of +the keystore containing your private key.</td> +</tr> +<tr> +<td><code>-verbose</code></td><td>Enable verbose output.</td> +</tr> +<tr> +<td><code>-storepass <password></code></td><td><p>The password for the +keystore. </p><p>As a security precaution, do not include this option +in your command line unless you are working at a secure computer. +If not supplied, Jarsigner prompts you to enter the password. In this +way, your password is not stored in your shell history.</p></td> +</tr> +<tr> +<td><code>-keypass <password></code></td><td><p>The password for the private +key. </p><p>As a security precaution, do not include this option +in your command line unless you are working at a secure computer. +If not supplied, Jarsigner prompts you to enter the password. In this +way, your password is not stored in your shell history.</p></td> +</tr> +</table> + +<p>Here's how you would use Jarsigner to sign an application package called +<code>my_application.apk</code>, using the example keystore created above. +</p> + +<pre>$ jarsigner -verbose -keystore my-release-key.keystore +my_application.apk alias_name</pre> + +<p>Running the example command above, Jarsigner prompts you to provide +passwords for the keystore and key. It then modifies the APK +in-place, meaning the .apk is now signed. Note that you can sign an +APK multiple times with different keys.</p> + +<p>To verify that your .apk is signed, you can use a command like this:</p> + +<pre>$ jarsigner -verify my_signed.apk</pre> + +<p>If the .apk is signed properly, Jarsigner prints "jar verified". +If you want more details, you can try one of these commands:</p> + +<pre>$ jarsigner -verify -verbose my_application.apk</pre> + +<p>or</p> + +<pre>$ jarsigner -verify -verbose -certs my_application.apk</pre> + +<p>The command above, with the <code>-certs</code> option added, will show you the +"CN=" line that describes who created the key.</p> + +<p class="note">Note: if you see "CN=Android Debug", this means the .apk was +signed with the debug key generated by the Android SDK. If you intend to release +your application, you must sign it with your private key instead of the debug +key.</p> + +<p>For more information about Jarsigner, see the documentation at +<a href="http://java.sun.com/j2se/1.5.0/docs/tooldocs/#security"> +http://java.sun.com/j2se/1.5.0/docs/tooldocs/#security</a></p> + +<h2 id="secure-key">Securing Your Private Key</h2> + +<p>Maintaining the security of your private key is of critical importance, both +to you and to the user. If you allow someone to use your key, or if you leave +your keystore and passwords in an unsecured location such that a third-party +could find and use them, your authoring identity and the trust of the user +are compromised. </p> + +<p>If a third party should manage to take your key without your knowledge or +permission, that person could sign and distribute applications that maliciously +replace your authentic applications or corrupt them. Such a person could also +sign and distribute applications under your identity that attack other +applications or the system itself, or corrupt or steal user data. </p> + +<p>Your reputation as a developer entity depends on your securing your private +key properly, at all times, until the key is expired. Here are some tips for +keeping your key secure: </p> + +<ul> +<li>Select strong passwords for the keystore and key.</li> +<li>When you generate your key with Keytool, <em>do not</em> supply the +<code>-storepass</code> and <code>-keypass</code> options at the command line. +If you do so, your passwords will be available in your shell history, +which any user on your computer could access.</li> +<li>Similarly, when signing your applications with Jarsigner, +<em>do not</em> supply the <code>-storepass</code> and <code>-keypass</code> +options at the command line. </li> +<li>Do not give or lend anyone your private key, and do not let unauthorized +persons know your keystore and key passwords.</li> +</ul> + +<p>In general, if you follow common-sense precautions when generating, using, +and storing your key, it will remain secure. </p>
\ No newline at end of file diff --git a/docs/html/guide/publishing/preparing.jd b/docs/html/guide/publishing/preparing.jd new file mode 100644 index 0000000..d355265 --- /dev/null +++ b/docs/html/guide/publishing/preparing.jd @@ -0,0 +1,254 @@ +page.title=Preparing to Publish: A Checklist +@jd:body + +<!-- +<div id="qv-wrapper"> +<div id="qv"> + +<h2>In this document</h2> + +<ol> +<li><a href=""></a></li> +</ol> + +</div> +</div> +--> + +<p>Publishing an application means testing it, packaging it appropriately, and +making it available to users of Android-powered mobile devices.</p> + +<p>If you plan to publish your application for installation on +Android-powered devices, there are several things you need to do, to get +your application ready. This document highlights the significant +checkpoints for preparing your application for a successful release. +</p> + +<p>If you will publish your application on Android Market, please also see <a +href="{@docRoot}guide/publishing/publishing.html#market">Publishing on Android Market</a> +for specific preparation requirements for your application. </p> + +<p>For general information about the ways that you can publish an applications, +see the <a href="{@docRoot}guide/publishing/publishing.html">Publishing Your +Applications</a> document. </p> + +<div class="special"> + +<p>Before you consider your application ready for release:</p> + +<ol> +<li>Test your application extensively on an actual device </li> +<li>Consider adding an End User License Agreement in your application</li> +<li>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>Before you do the final compile of your application:</p> + +<ol start="5"> +<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><em>Compile your application...</em></p> +<p>After compiling your application:</p> +<ol start="8"> +<li>Sign your application</li> +<li>Test your compiled application</li> +</ol> +</div> + +<h2 id="releaseready">Before you consider your application ready for release</h2> + +<h3 id="test">1. Test your application extensively on an actual device</h3> + +<p>It's important to test your application as extensively as possible, in as +many areas as possible. To help you do that, Android provides a variety of +testing classes and tools. You can use +{@link android.app.Instrumentation Instrumentation} to run JUnit and other +test cases, and you can use testing +tools such as the <a href="{@docRoot}guide/developing/tools/monkey.html">UI/Application +Exerciser Monkey</a>. </p> + +<ul> +<li>To ensure that your application will run properly for users, you should make +every effort to obtain one or more physical mobile device(s) of the type on +which you expect the application to run. You should then test your application +on the actual device, under realistic network conditions. Testing your +application on a physical device is very important, because it enables you to +verify that your user interface elements are sized correctly (especially for +touch-screen UI) and that your application's performance and battery efficiency +are acceptable.</li> + +<li>If you can not obtain a mobile device of the type you are targeting for your +application, you can use emulator options such as <code>-dpi</code>, +<code>-device</code>, <code>-scale</code>, <code>-netspeed</code>, +<code>-netdelay</code>, <code>-cpu-delay</code> and others to model the +emulator's screen, network performance, and other attributes to match the target +device to the greatest extent possible. You can then test your application's UI +and performance. However, we strongly recommend that you test your application +on an actual target device before publishing it. </li> + +<li>If you are targeting the <a href="http://www.t-mobileg1.com/">T-Mobile +G1</a> device for your application, make sure that your UI handles screen +orientation changes. </li> +</ul> + +<h3 id="eula">2. Consider adding an End User License Agreement in your +application</h3> + +<p>To protect your person, organization, and intellectual property, you may want +to provide an End User License Agreement (EULA) with your application. + +<h3 id="iconlabel">3. 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><application></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">4. 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><application></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">5. 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><manifest></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><manifest></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">6. Obtain a suitable cryptographic key</h3> + +<p>If you have read and followed all of the preparation steps up to this point, +your application is compiled and ready for signing. Inside the .apk, the +application is properly versioned, and you've cleaned out extra files and +private data, as described above. </p> + +<p>Before you sign your application, you need to make sure that you have a +suitable private key. For complete information about how to obtain (or generate) +a private key, see <a href="{@docRoot}guide/publishing/app-signing.html#cert"> +Obtaining a Suitable Private Key</a>.</p> + +<p>Once you have obtained (or generated) a suitable private key, you will use it +to:</p> + +<ul> +<li>Register for a Maps API Key (see below), if your application uses MapView +elements.</li> +<li>Sign your application for release, later in the preparation process</li> +</ul> + +<h3 id="mapsApiKey">7. Register for a Maps API Key, if your application is using +MapView elements</h3> + +<div class="sidebox" style="margin-bottom:.5em;padding:1em;"><p> +For complete information about getting a Maps API Key, see <a +href="{@docRoot}guide/topics/location/geo/mapkey.html">Obtaining a Maps API +Key</a>.<br></p></div> + +<p>If your application uses one or more Mapview elements, you will need to +register your application with the Google +Maps service and obtain a Maps API Key, before your MapView(s) will be able to +retrieve data from Google Maps. To do so, you supply an MD5 fingerprint of your +signer certificate to the Maps service. </p> + +<p>During development, you can get a temporary Maps API Key by registering the +debug key generated by the SDK tools. However, before publishing your +application, you must register for a new Maps API Key that is based on your +private key. </p> + +<p>If your application uses MapView elements, the important points to understand +are:</p> + +<ol> +<li>You <em>must</em> obtain the Maps API Key before you compile your +application for release, because you must add the Key to a special attribute in +each MapView element — <code>android:apiKey</code> — 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 — 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> + +<p>For more information about signing and your private key, see <a +href="#signing">Signing Your Applications</a>.</p> + + +<h2 id="compile">Compile your application</h2> + +<p>When you've prepared your application as described in the previous sections, +you can compile your application for release. </p> + +<h2 id="post-compile">After compiling your application</h2> + +<h3 id="signapp">8. Sign your application</h3> + +<p>Sign your application using your private key. Signing your application +correctly is critically important. Please see <a href="#signing">Signing Your +Applications</a> for complete information. </p> + +<h3 id="testapp">9. Test your compiled and signed application</h3> + +<p>Before you release your compiled application, you should thoroughly test it +on the target mobile device (and target network, if possible). In particular, +you should make sure that any MapView elements in your UI are receiving maps +data properly. If they are not, go back to <a href="#mapsApiKey">Register for a +Maps API Key</a> and correct the problem. You should also ensure that the +application works correctly with any server-side services and data that you are +providing or are relying on and that the application handles any authentication +requirements correctly. </p> + +<p>After testing, you are now ready to publish your application to mobile device +users.</p> + + diff --git a/docs/html/guide/publishing/publishing.jd b/docs/html/guide/publishing/publishing.jd new file mode 100644 index 0000000..3aea3cf --- /dev/null +++ b/docs/html/guide/publishing/publishing.jd @@ -0,0 +1,250 @@ +page.title=Publishing Your Applications +@jd:body + +<div id="qv-wrapper"> +<div id="qv"> + +<h2>Publishing quickview</h2> + +<ul> +<li>You can publish your application using a hosted service such as Android Market or through a web server.</li> +<li>Before you publish, make sure you have prepared your application properly.</li> +<li>Android Market makes it easy for users of Android-powered devices to see and download your application.</li> +</ul> + + +<h2>In this document</h2> + +<ol> +<li><a href="#overview">Publishing on Android Market</a> + <ol> + <li><a href="#marketupgrade">Publishing Upgrades on Android Market</a> + <li><a href="#marketintent">Using Intents to Launch the Market Application</a></li> + </ol></li> +<!-- +<li><span style="color:ccc">Publishing on Other Hosted Services</a></li> +<li><span style="color:ccc">Publishing through a Web Server</a></li> +--> +</ol> + +<h2>See also</h2> + +<ol> +<li><a href="{@docRoot}guide/publishing/preparing.html">Preparing to Publish</a></li> +</ol> + +<div id="qv-extra"> + <img id="rule" src="{@docRoot}assets/images/grad-rule-qv.png"> + <div id="qv-sub-rule"> + <img src="{@docRoot}assets/images/icon_market.jpg" style="float:left;margin:0;padding:0;"> + <p style="color:#669999;">Interested in publishing your app on Android Market?</p> + <a id="publish-link" href="http://market.android.com/publish">Go to Android Market »</a> + </div> +</div> + +</div> +</div> + +<p>Publishing an application means testing it, packaging it appropriately, and making +it available to users of Android-powered mobile devices for download or sideload.</p> + +<p>If you've followed the steps outlined in +<a href="{@docRoot}guide/publishing/preparing.html">Preparing to +Publish Your Applications</a>, the result of the process is a compiled .apk that +is signed with your release private key. Inside the .apk, the application is +properly versioned and any MapView elements reference a Maps API Key that you +obtained by registering the MD5 fingerprint of the same certificate used to sign +the .apk. Your application is now ready for publishing. </p> + +<p>The sections below provide information about publishing your Android +application to mobile device users.</p> + +<h2 id="market">Publishing on Android Market</h2> + +<p>Android Market is a hosted service that makes it easy for users to find and +download Android applications to their Android-powered devices, and makes it +easy for developers to publish their applications to Android users.</p> + +<p>To publish your application on Android Market, you first need to register +with the service using your Google account and agree to the terms of service. +Once you are registered, you can upload your application to the service whenever +you want, as many times as you want, and then publish it when you are ready. +Once published, users can see your application, download it, and rate it using +the Market application installed on their Android-powered devices. </p> + +<p>To register as an Android Market developer and get started with publishing, +visit the Android Market: </p> + +<p style="margin-left:3em;"><a +href="http://market.android.com/publish">http://market.android.com/publish</a> +</p> + +<p>If you plan to publish your application on Android Market, you must make sure +that it meets the requirements listed below, which are enforced by the Market +server when you upload the application.</p> + +<div class="special"> +<p>Requirements enforced by the Android Market server:</p> +<ol> +<li>Your application must be signed with a cryptographic private key whose +validity period ends after <span style="color:red">22 October 2033</span>. </li> +<li>Your application must define both an <code>android:versionCode</code> and an +<code>android:versionName</code> attribute in the <code><manifest></code> +element of its manifest. The server uses the <code>android:versionCode</code> as +the basis for identifying the application internally and handling upgrades, and +it displays the <code>android:versionName</code> to users as the application's +version.</li> +<li>Your application must define both an <code>android:icon</code> and an +<code>android:label</code> attribute in the <code><application></code> +element of its manifest.</li> +</ol> +</div> + +<h3 id="marketupgrade">Publishing Upgrades on Android Market</h3> + +<p>The beta version of Android Market does not support notifying your users when +you publish a new version of your application. This capability will be +added soon, but currently the user must independently initiate download of an +upgraded application. When you publish an upgrade, you can assist users by +notifying them that the upgrade is available and giving them a way to download +the upgraded application from Android Market.</p> + +<p>Here is a suggested way of tracking installed application versions and +notifying users that an upgrade is available:</p> + +<ol> +<li>Have your app occasionally check in with a web-service that you're +running. This web service should return two values: the latest available +version number for the application (corresponding to +<code>android:versionCode</code>) and a URI string that your application +can later send in an Intent, to launch Market and search for the +upgraded application for the user. + +<p>The URI that your web service returns should be properly formatted to +search Android Market for your upgraded application. See +<a href="#marketintent">Using Intents to Launch the Market Application</a> +for more information. The URI should specify the upgraded +application's package name as the query parameter, since the package name +is guaranteed to be unique on Android Market. The URI format for the +package name search is: </p> + +<p><code>http://market.android.com/search?q=pname:<package></code> or +<br><code>market://search?q=pname:<package></code></p> + +</li> +<li>Your application can then compare its own version number against +that retrieved. If the retrieved value is greater, your application can +show a dialog informing the user that a new version is available. The +dialog can offer buttons to begin the download or cancel. </li> <li>If +the user clicks the button to begin the download, your application can +call startActivity() using the ACTION_VIEW Intent, passing the URI +received from your web service. The Intent launches the Market +application on the device and initiates an immediate search on the +Android Market site, based on the query parameters in the URI. When the +result is displayed, the user can view the details of the upgraded +application and begin the download. + +<p>Note that, because the URI string is received from your web +service and not hard-coded into your application, you can easily change +the Market launch behaviors whenever needed, without +having to change your application. </p></li></ol> + +<p>For more information about URIs you can pass to the Market application at +launch, see <a href="#marketintent">Using Intents to Launch the Market +Application</a>, below.</p> + +<h3 id="marketintent">Using Intents to Launch the Market Application on +a Device</h3> + +<p>Android-powered devices include a preinstalled Market application that gives +users access to the Android Market site. From Market, users can +browse or search available applications, read ratings and reviews, and +download/install applications.</p> + +<p>You can launch the Market application from another Android +application by sending an Intent to the system. You might want to do +this, for example, to help the user locate and download an upgrade to an +installed application, or to let the user know about related +applications that are available for download. </p> + +<p>To launch Market, you send an ACTION_VIEW Intent, passing a Market-handled +URI string as the Intent data. In most cases, your application would call +startActivity() to send the ACTION_VIEW Intent with the Market-handled URI.</p> + +<p>The URI that you supply with the Intent lets the system route the intent +properly and also expresses the type of action that you want Market to perform +after launch. Currently, you can have Market initiate a search for applications +on Android Market, based on query parameters that you provide. For example, you +can specify URIs to search for applications by:</p> + +<ul> +<li>Package name</li> +<li>Developer name</li> +<li>String match across application name, developer name, and +description, or </li> +<li>Any combination of the above</li> +</ul> + +<p>Note that the URI queries return results from the public metadata supplied by +developers in their Android Market profiles or application publishing +information, but not from the developer's private account or from the +certificate used to sign the application. </p> + +<p>The table below provides a list of URIs and actions currently +supported by the Market application.</p> + +<table> +<tr> +<th>For this Result</th> +<th>Pass this URI with the ACTION_VIEW Intent</th> +<th>Comments</th> +</tr> + +<!-- +<tr> +<td>Display the details screen for a specific application, as identified +by its Market appID string.</td> +<td><code>http://market.android.com/details?id=<appMarketAppIdString></code> +or<br> +<code>market://details?id=<appMarketUidString></code></td> +<td>Note that Market appID is specific to an application +<em>and</em> its version. That is, an appID query loads the details page +for a specific version of an application.</td> +</tr> +--> +<tr> +<td>Search for an application by its fully qualified Java package name and +display the result.</td> +<td><code>http://market.android.com/search?q=pname:<package></code> or<br> +<code>market://search?q=pname:<package></code></td> +<td>Searches only the Java package name of applications. Returns only exact +matches.</td> +</tr> + +<tr> +<td>Search for applications by developer name and display the results.</td> +<td><code>http://market.android.com/search?q=pub:"<Developer Name>"</code> +or<br> <code>market://search?q=pub:"<Developer Name>"</code></td> +<td>Searches only the "Developer Name" fields of Market public profiles. +Returns exact matches only. </td> +</tr> + +<tr> +<td>Search for applications by substring and display the results.</td> +<td><code>http://market.android.com/search?q=<substring></code> or +<br><code>market://search?q=<substring></code></td> +<td>Searches all public fields (application title, developer name, and +application description) for all applications. Returns exact and partial +matches.</td> +</tr> + +<tr> +<td>Search using multiple query parameters and display the results.</td> +<td>Example:<p><code>http://market.android.com/search?q=world pname:com.android.hello pub:Android</code></p></td> +<td>Returns a list of applications meeting all the supplied parameters. </td> +</tr> +</table> + +<p>Note that these URIs work only when passed as intent data — you +can't currently load the URIs in a web browser, either on a desktop machine or +on the device. </p>
\ No newline at end of file diff --git a/docs/html/guide/publishing/versioning.jd b/docs/html/guide/publishing/versioning.jd new file mode 100644 index 0000000..d0eafcd --- /dev/null +++ b/docs/html/guide/publishing/versioning.jd @@ -0,0 +1,155 @@ +page.title=Versioning Your Applications +@jd:body + +<div id="qv-wrapper"> +<div id="qv"> + +<h2>Versioning quickview</h2> + +<ul> +<li>Your application <em>must</em> be versioned</a></li> +<li>You set the version in the application's manifest file</li> +<li>How you version your applications affects how users upgrade </li> +<li>Determine your versioning strategy early in the development process, including considerations for future releases.</li> +</ul> + +<h2>In this document</h2> + +<ol> +<li><a href="#appversion">Setting Application Version</a></li> +<li><a href="#minsdkversion">Specifying Minimum System API Version</a> +</ol> + + +<h2>See also</h2> + +<ol> +<li><a href="{@docRoot}guide/publishing/preparing.html">Preparing to Publish Your Application</a></li> +<li><a href="{@docRoot}guide/publishing/publishing.html#market">Publishing On Android Market</a></li> +<li><a href="{@docRoot}guide/topics/manifest/manifest-intro.html">The AndroidManifest.xml File</a></li> +</ol> + +</div> +</div> + +<p>Versioning is a critical component of your application upgrade/maintenance +strategy. </p> + +<ul> +<li>Users need to have specific information about the application version that +is installed on their devices and the upgrade versions available for +installation. </li> +<li>Other applications — including other applications that you publish as +a suite — need to query the system for your application's version, to +determine compatibility and identify dependencies.</li> +<li>Services through which you will publish your application(s) may also need to +query your application for its version, so that they can display the version to +users. A publishing service may also need to check the application version to +determine compatibility and establish upgrade/downgrade relationships.</li> +</ul> + +<p>The Android system itself <em>does not ever</em> check the application version +information for an application, such as to enforce restrictions on upgrades, +compatibility, and so on. Instead, only users or applications themselves are +responsible for enforcing any version restrictions for applications themselves. </p> + +<p>The Android system <em>does</em> check any system version compatibility expressed +by an application in its manifest, in the <code>minSdkVersion</code> attribute. This +allows an application to specify the minimum system API with which is compatible. +For more information see <a href="#minsdkversion">Specifying Minimum System API Version</a>. + +<h2 id="appversioning">Setting Application Version</h2> +<p>To define the version information for your application, you set attributes in +the application's manifest file. Two attributes are available, and you should +always define values for both of them: </p> + +<ul> +<li><code>android:versionCode</code> — An integer value that represents +the version of the application code, relative to other versions. + +<p>The value is an integer so that other applications can programatically +evaluate it, for example to check an upgrade or downgrade relationship. You can +set the value to any integer you want, however you should make sure that each +successive release of your application uses a greater value. The system does not +enforce this behavior, but increasing the value with successive releases is +normative. </p> + +<p>Typically, you would release the first version of your application with +versionCode set to 1, then monotonically increase the value with each release, +regardless whether the release constitutes a major or minor release. This means +that the <code>android:versionCode</code> value does not necessarily have a +strong resemblence to the application release version that is visible to the +user (see <code>android:versionName</code>, below). Applications and publishing +services should not display this version value to users.</p> +</li> +<li><code>android:versionName</code> — A string value that represents the +release version of the application code, as it should be shown to users. +<p>The value is a string so that you can describe the application version as a +<major>.<minor>.<point> string, or as any other type of +absolute or relative version identifier. </p> + +<p>As with <code>android:versionCode</code>, the system does not use this value +for any internal purpose, other than to enable applications to display it to +users. Publishing services may also extract the <code>android:versionName</code> +value for display to users.</p> +</li> +</ul> + +<p>You define both of these version attributes in the +<code><manifest></code> element of the manifest file. </p> + +<p>Here's an example manifest that shows the <code>android:versionCode</code> +and <code>android:versionName</code> attributes in the +<code><manifest></code> element. </p> + +<pre> +<?xml version="1.0" encoding="utf-8"?> +<manifest xmlns:android="http://schemas.android.com/apk/res/android" + package="com.example.package.name" + android:versionCode="2" + android:versionName="1.1"> + <application android:icon="@drawable/icon" android:label="@string/app_name"> + ... + </application> +</manifest> +</pre> + +<p>In this example, note that <code>android:versionCode</code> value indicates +that the current .apk contains the second release of the application code, which +corresponds to a minor follow-on release, as shown by the +<code>android:codeName</code> string. </p> + +<p>The Android framework provides an API to let applications query the system +for version information about your application. To obtain version information, +applications use the +{@link android.content.pm.PackageManager#getPackageInfo(java.lang.String, int)} +method of {@link android.content.pm.PackageManager PackageManager}. </p> + +<h2 id="minsdkversion">Specifying Minimum System API Version</h2> + +<p>If your application requires a specific minimum version of the Android +platform, you can specify that version as an API Level identifier +in the application's manifest file. Doing so ensures that your +application can only be installed on devices that +are running a compatible version of the Android system. </p> + +<p>To specify the minimum system version in the manifest, use this attribute: </p> + +<ul> +<li><code>android:minSdkVersion</code> — An integer value corresponding to +the code version of the Android platform. +<p>When preparing to install an application, the system checks the value of this +attribute and compares it to the system version. If the +<code>android:minSdkVersion</code> value is greater than the system version, the +system aborts the installation of the application. </p> + +<p>If you do not specify this attribute in your manifest, the system assumes +that your application is compatible with all platform versions.</p></li> +</ul> + +<p>To specify a minimum platform version for your application, add a +<code><uses-sdk></code> element as a child of +<code><manifest></code>, then define the +<code>android:minSdkVersion</code> as an attribute. </p> + +<p>For more information, also see the <a href="{@docRoot}sdk/android-1.1.html">Android System Image 1.1 Version Notes</a>.</p> |