+ + Figure 1. The development process for Android applications. +
+Note: Before you begin developing Android applications, make - sure you have gone through all of the steps outlined in Installing the SDK.
+
+ + Figure 1. The development process for Android applications. +
+The basic steps for developing applications with or without Eclipse are the same:
+The basic steps for developing applications (with or without Eclipse) are shown in figure 1. The +development steps encompass four development phases, which include:
-You need to create Android Virtual Devices (AVD) or connect hardware devices on which - you will install your applications.
- -See Managing Virtual Devices +
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 + applications.
+See Managing Virtual Devices and Using Hardware Devices for more -information. -
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 + Create an Android project.
+During this phase you build your project into a debuggable .apk 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
+ adb. For more information, see
+ Build and run your application.
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, + Debug your application with the + SDK debugging and logging tools.
+Last, you test your application using various Android SDK testing tools. For more + information, see Test your application + with the Testing and Instrumentation framework.
+During this phase you configure and build your application for release and distribute your + application to users. For more information, see + Publishing Overview.
+An Android project contains all source code and resource files for your application. It is
- built into an .apk package that you can install on Android devices.
If you are using Eclipse, builds are generated each time you save changes and you can install
- your application on a device by clicking Run. If you're using another IDE, you can build your
- project using Ant and install it on a device using adb.
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.
-The Android SDK provides a testing and instrumnetation framework to help you set up and - run tests within an emulator or device.
-When developing in IDEs or editors other than Eclipse, be familiar with @@ -101,7 +98,7 @@ information.
If you are using Eclipse and ADT, tools such as adb and android
are automatically called by Eclipse and ADT so you don't have to manually invoke these tools.
You need to be familiar with adb, however, because certain functions are not
@@ -109,19 +106,20 @@ accessible from
Eclipse, such as the adb shell commands. You might also need to call Keytool and
Jarsigner to
sign your applications, but you can set up Eclipse to do this automatically as well.
For more information on the tools provided with the Android SDK, see the Tools section of the documentation.
- +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 section for documentation. -
+
+IntelliJ IDEA is a powerful Java IDE from JetBrains that provides @@ -148,5 +146,5 @@ Jarsigner to
This document provides information about signing your Android applications prior to publishing them for mobile device users.
- -The Android system requires that all installed applications be digitally -signed with a certificate whose private key is held by the application's -developer. The Android system uses the certificate as a means of identifying the author of -an application and establishing trust relationships between applications. The certificate is not -used to control which applications the user can install. The certificate -does not need to be signed by a certificate authority: it is perfectly -allowable, and typical, for Android applications to use self-signed -certificates.
+The Android system requires that all installed applications be digitally signed with a +certificate whose private key is held by the application's developer. The Android system uses the +certificate as a means of identifying the author of an application and establishing trust +relationships between applications. The certificate is not used to control which applications the +user can install. The certificate does not need to be signed by a certificate authority: it is +perfectly allowable, and typical, for Android applications to use self-signed certificates.
The important points to understand about signing Android applications are:
zipalign tool to optimize the final APK package.zipalign tool to optimize the final APK package.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.
+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 can +run it or debug it on an emulator or device.
-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. +
The Android build process signs your application differently depending on which build mode you +use to build your application. There are two build modes: debug mode and release +mode. You use debug mode when you are developing and testing your application. You use +release mode when you want to build a release version of your application that you can +distribute directly to users or publish on an application marketplace such as Android Market.
-When you build in debug mode the Android SDK build tools use the Keytool utility
+(included in the JDK) to create a debug key. Because the SDK build tools created the debug key,
+they know the debug key's alias and password. Each time you compile your application in debug mode,
+the build tools use the debug key along with the Jarsigner utility (also included in the JDK) to
+sign your application's .apk file. Because the alias and password are known to the SDK
+build tools, the tools don't need to prompt you for the debug key's alias and password each time
+you compile.
Once your application is signed, don't forget to run {@code zipalign} on the APK -for additional optimization.
+When you build in release mode you use your own private key to sign your application. If
+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 .apk 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.
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 debug 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
+release option.
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 +
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.
Before you begin, you should make sure that
-Keytool is available to the SDK build
-tools. In most cases, you can tell the SDK build tools how to find Keytool by setting
-your JAVA_HOME environment variable to references a suitable JDK.
-Alternatively, you can add the JDK version of Keytool to your PATH variable.
Before you begin, make sure that the Keytool utility and Jarsigner utility are available to
+the SDK build tools. Both of these tools are available in the JDK. In most cases, you can tell
+the SDK build tools how to find these utilities by setting your JAVA_HOME environment
+variable so it references a suitable JDK. Alternatively, you can add the JDK version of Keytool and
+Jarsigner to your PATH variable.
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 be sure it points
+
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 be sure it points
to the Keytool in the JDK.
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.
-The Android build tools provide a debug signing mode that makes it easier for you +
The Android build tools provide a debug signing mode that makes it easier for you to develop and debug your application, while still meeting the Android system requirement for signing your .apk. When using debug mode to build your app, the SDK tools invoke Keytool to automatically create @@ -209,7 +198,7 @@ you do not need to sign the package with your own key.
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 @@ -218,38 +207,38 @@ debug key (as described above). (To do so in Eclipse/ADT, go to Windows > Preferences > Android > Build.)
-Caution: You cannot release your application +
Caution: You cannot release your application to the public when signed with the debug certificate.
If you are developing in Eclipse/ADT (and have set up Keytool as described above in +
If you are developing in Eclipse/ADT (and have set up Keytool and Jarsigner as described above in Basic Setup for Signing), signing in debug mode is enabled by default. When you run or debug your -application, ADT signs the .apk with the debug certificate, runs {@code zipalign} on the -package, then installs it on -the selected emulator or connected device. No specific action on your part is needed, +application, ADT signs the .apk with the debug certificate, runs {@code zipalign} on the +package, then installs it on +the selected emulator or connected device. No specific action on your part is needed, provided ADT has access to Keytool.
If you are using Ant to build your .apk files, debug signing mode +
If you are using Ant to build your .apk files, debug signing mode
is enabled by using the debug option with the ant command
(assuming that you are using a build.xml file generated by the
-android tool). When you run ant debug to
-compile your app, the build script generates a keystore/key and signs the .apk for you.
+android tool). When you run ant debug to
+compile your app, the build script generates a keystore/key and signs the .apk for you.
The script then also aligns the .apk with the zipalign tool.
-No other action on your part is needed. Read
+No other action on your part is needed. Read
Building and Running Apps
on the Command Line for more information.
The self-signed certificate used to sign your application in debug mode (the default on +
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.
-When the certificate expires, you will get a build error. On Ant builds, the error +
When the certificate expires, you will get a build error. On Ant builds, the error looks like this:
debug: @@ -258,59 +247,59 @@ looks like this:In Eclipse/ADT, you will see a similar error in the Android console.
-To fix this problem, simply delete the
debug.keystorefile. -The default storage location for AVDs is in~/.android/on OS X and Linux, +To fix this problem, simply delete the
debug.keystorefile. +The default storage location for AVDs is in~/.android/on OS X and Linux, inC:\Documents and Settings\<user>\.android\on Windows XP, and inC:\Users\<user>\.android\on Windows Vista and Windows 7.The next time you build, the build tools will regenerate a new keystore and debug key.
-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 +
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 -I can't compile my app because the build tools generated an expired debug +I can't compile my app because the build tools generated an expired debug certificate.
-Signing for Public Release
+Signing in Release Mode
When your application is ready for release to other users, you must:
- Obtain a suitable private key
-- Compile the application in release mode
+- Compile the application in release mode
- Sign your application with your private key
- Align the final APK package
If you are developing in Eclipse with the ADT plugin, you can use the Export Wizard -to perform the compile, sign, and align procedures. The Export Wizard even allows you to -generate a new keystore and private key in the process. So if you use Eclipse, you can +to perform the compile, sign, and align procedures. The Export Wizard even allows you to +generate a new keystore and private key in the process. So if you use Eclipse, you can skip to Compile and sign with Eclipse ADT.
1. Obtain a suitable private key
-In preparation for signing your application, you must first ensure that -you have a suitable private key with which to sign. A suitable private +
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:
If you plan to publish your application(s) on Android Market, note that a +or application suite. A validity period of more than 25 years is recommended. +
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. +application if it is signed with a key whose validity expires before that date.
The key may be self-signed. If you do not have a suitable key, you must +
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 Basic Setup.
@@ -318,8 +307,8 @@ in Basic Setup. command and pass any of the options listed below (and any others, as needed). -Warning: Keep your private key secure. -Before you run Keytool, make sure to read +
Warning: Keep your private key secure. +Before you run Keytool, make sure to read Securing Your Private Key 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 @@ -342,7 +331,7 @@ keys) the first 8 characters of the alias are used.
-keyalg <alg>-keyalg <alg>-dname <name>A Distinguished Name that describes who created the key. The value is used as the issuer and subject fields in the self-signed certificate.
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).
Here's an example of a Keytool command that generates a private key:
-$ keytool -genkey -v -keystore my-release-key.keystore +$ keytool -genkey -v -keystore my-release-key.keystore -alias alias_name -keyalg RSA -keysize 2048 -validity 10000Running 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 -
@@ -401,7 +390,7 @@ http://java.sun.com/j2se/1.5.0/docs/tooldocs/#securitymy-release-key.keystore. The keystore and key are -protected by the passwords you entered. The keystore contains +my-release-key.keystore. 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.2. Compile the application in release mode
-In order to release your application to users, you must compile it in release mode. +
In order to release your application to users, you must compile it in release mode. In release mode, the compiled application is not signed by default and you will need to sign it with your private key.
@@ -410,19 +399,19 @@ You can not release your application unsigned, or signed with the debug key.With Eclipse
-To export an unsigned .apk from Eclipse, right-click the project in the Package -Explorer and select Android Tools > Export Unsigned Application +
To export an unsigned .apk from Eclipse, right-click the project in the Package +Explorer and select Android Tools > Export Unsigned Application Package. Then specify the file location for the unsigned .apk. -(Alternatively, open your
-AndroidManifest.xmlfile in Eclipse, open +(Alternatively, open yourAndroidManifest.xmlfile in Eclipse, open the Overview tab, and click Export an unsigned .apk.)Note that you can combine the compiling and signing steps with the Export Wizard. See +
Note that you can combine the compiling and signing steps with the Export Wizard. See Compiling and signing with Eclipse ADT.
With Ant
If you are using Ant, you can enable release mode by using the
releaseoption -with theantcommand. For example, if you are running Ant from the +with theantcommand. For example, if you are running Ant from the directory containing your {@code build.xml} file, the command would look like this:ant release@@ -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, the build script will prompt you for your keystore and alias password when you performant release, 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<your_project_name>-release.apk. With these steps automated for you, you're able to skip the manual procedures below (steps 3 and 4). To learn how to specify your keystore and alias in the {@code ant.properties} file, @@ -455,7 +444,7 @@ the keystore containing your private key is available.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.
+sign the .apk. The table below shows the options you could use.
-storepass <password> | The password for the -keystore. As a security precaution, do not include this option +keystore. 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 +If not supplied, Jarsigner prompts you to enter the password. In this way, your password is not stored in your shell history. |
-keypass <password> | The password for the private -key. As a security precaution, do not include this option +key. 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 +If not supplied, Jarsigner prompts you to enter the password. In this way, your password is not stored in your shell history. |
Here's how you would use Jarsigner to sign an application package called
-my_application.apk, using the example keystore created above.
+my_application.apk, using the example keystore created above.
$ jarsigner -verbose -keystore my-release-key.keystore +$ jarsigner -verbose -keystore my-release-key.keystore my_application.apk alias_nameRunning 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 +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.
To verify that your .apk is signed, you can use a command like this:
$ jarsigner -verify my_signed.apk-If the .apk is signed properly, Jarsigner prints "jar verified". +
If the .apk is signed properly, Jarsigner prints "jar verified". If you want more details, you can try one of these commands:
$ jarsigner -verify -verbose my_application.apk@@ -510,7 +499,7 @@ If you want more details, you can try one of these commands:$ jarsigner -verify -verbose -certs my_application.apk-The command above, with the
-certsoption added, will show you the +The command above, with the
-certsoption added, will show you the "CN=" line that describes who created the key.Note: 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 RAM consumed by the running application.
-The
zipaligntool is provided with the Android SDK, inside the +The
zipaligntool is provided with the Android SDK, inside thetools/directory. To align your signed .apk, execute:zipalign -v 4 your_project_name-unaligned.apk your_project_name.apkThe {@code -v} flag turns on verbose output (optional). {@code 4} is the byte-alignment (don't use anything other than 4). The first file argument is -your signed .apk (the input) and the second file is the destination .apk file (the output). +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.
Caution: Your input .apk must be signed with your private key before you optimize the package with {@code zipalign}. If you sign it after using {@code zipalign}, it will undo the alignment.
-For more information, read about the +
For more information, read about the zipalign tool. @@ -568,15 +557,15 @@ in the Basic Setup for Signing.
To create a signed and aligned .apk in Eclipse:
-
@@ -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 are compromised. -- Select the project in the Package +
- Select the project in the Package Explorer and select File > Export.
-- Open the Android folder, select Export Android Application, +
- Open the Android folder, select Export Android Application, and click Next. -
The Export Android Application wizard now starts, which will +
The Export Android Application wizard now starts, which will guide you through the process of signing your application, including steps for selecting the private key with which to sign the .apk (or creating a new keystore and private key).
-- Complete the Export Wizard and your application will be compiled, +
- Complete the Export Wizard and your application will be compiled, signed, aligned, and ready for distribution.
If a third party should manage to take your key without your knowledge or +
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 +sign and distribute applications under your identity that attack other applications or the system itself, or corrupt or steal user data.
Your reputation as a developer entity depends on your securing your private @@ -602,12 +591,12 @@ keeping your key secure:
-storepass and -keypass options at the command line.
-If you do so, your passwords will be available in your shell history,
+-storepass and -keypass 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.-storepass and -keypass
+-storepass and -keypass
options at the command line. Publishing an application means testing it, packaging it appropriately, and -making it available to users of Android-powered mobile devices.
+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. +
Before you distribute your Android application to users you need to prepare it for release. The +preparation process is a required development +task for all Android applications and is the first step in the publishing process (see figure +1).
+ +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
+.apk file, which you can distribute directly to users or distribute through an
+application marketplace such as Android Market.
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 Publishing on +Android Market to be sure your release-ready application satisfies all Android Market +requirements.
+ +Note: 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.
+ +
++ Figure 1. Preparing for release is a required development +task and is the first step in the publishing process.
-If you will publish your application on Android Market, please also see Publishing on Android Market -for specific preparation requirements for your application.
+For general information about the ways that you can publish an applications, -see the Publishing Your -Applications document.
+To release your application to users you need to create a release-ready package that users can
+install and run on their Android-powered devices. The release-ready package contains the same
+components as the debug .apk file — compiled source code, resources, manifest
+file, and so on — and it is built using the same build tools. However, unlike the debug
+.apk file, the release-ready .apk file is signed with your own certificate
+and it is optimized with the zipalign tool.
Before you consider your application ready for release:
- -Before you do the final compile of your application:
- -After you compile your application:
-
+ + Figure 2. You perform five main tasks to prepare your application for + release. +
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.
-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.
-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 UI/Application -Exerciser Monkey.
+You usually perform the tasks listed in figure 2 after you have throroughly debugged and tested +your application. The Android SDK contains several tools to help you test and debug your Android +applications. For more information, see the Debugging and Testing sections in the Dev Guide.
+ +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.
+ +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 Obtain a +suitable private key.
+ +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 MapView class, which is part of the Google Maps external +library, 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 Obtaining a Maps API +key.
+ +Be sure you have an application icon and that it meets the recommended icon guidelines. 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.
+ +Note: If you are releasing your application on Android Market, you +need to create a high resolution + version of your icon. See Graphic +Assets for your Application for more information.
+ +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.
+ +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 + +Graphic Assets for your Application
+ +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.
+ +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 package attribute +documentation.
+ +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
+android:debuggable attribute from the <application> tag in your
+manifest file, or by setting the android:debuggable attribute to
+false in your manifest file. Also, remove any log files or static test files that
+were created in your project.
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.
+ +Clean up your project and make sure it conforms to the directory structure described in Android Projects. +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:
-dpi,
--device, -scale, -netspeed,
--netdelay, -cpu-delay 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. jni/, lib/, and src/
+ directories. The jni/ directory should contain only source files associated with the
+ Android NDK, such as
+ .c, .cpp, .h, and .mk files. The
+ lib/ directory should contain only third-party library files or private library
+ files, including prebuilt shared and static libraries (for example, .so files). The
+ src/ directory should contain only the source files for your application
+ (.java and .aidl files). The src/ directory should not
+ contain any .jar files.res/ directory for old
+ drawable files, layout files, and values files that you are no longer using and delete them.lib/ directory for test libraries and remove them if they are no
+ longer being used by your application.assets/ directory and your res/raw/
+ directory for raw asset files and static files that you need to update or remove prior to
+ release.To protect your person, organization, and intellectual property, you may want -to provide an End User License Agreement (EULA) with your application. - -
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. - -
For complete information about Android Market Licensing Service and how to -use it in your application, see Licensing Your -Applications.
- -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.
- -To specify an icon and label, you define the attributes
-android:icon and android:label in the
-<application> element of the manifest.
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.
- -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.
-android:debuggable="true" attribute from the
-<application> element of the manifest.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 android:versionCode and android:versionName
-attributes of the <manifest> element in the application's
-manifest file. Carefully consider your version numbering plans in the context of
-your overall application upgrade strategy.
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 android:versionCode and
-android:versionName attributes of the <manifest>
-element in the application's manifest file, using appropriate values.
For detailed information about how to define version information for your -application, see Versioning -Your Applications.
- -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.
- -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 -Obtaining a Suitable Private Key.
- -Once you have obtained (or generated) a suitable private key, you will use it -to:
+Verify that the following manifest items are set correctly:
You should specify only those permissions that are relevant and required for your application.
+android:icon and android:label attributes
+ You must specify values for these attributes, which are located in the + <application> + element.
+android:versionCode and android:versionName attributes.
+ We recommend that you specify values for these attributes, which are located in the + <manifest> + element. For more information see + Versioning your Application.
+There are several additional manifest elements that you can set if you are releasing your
+application on Android Market. For example, the android:minSdkVersion and
+android:targetSdkVersion attributes, which are located in the <uses-sdk> element. For more
+information about these and other Android Market settings, see Market Filters.
-For complete information about getting a Maps API Key, see -Obtaining a Maps API Key.
-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.
+Android provides several tools and techniques to make your application compatible with a wide +range of devices. To make your application available to the largest number of users, consider +doing the following:
-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.
+Make sure you meet the + + best practices for supporting multiple screens. 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.
+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 + Optimizing Apps for Android 3.0 + .
+If your application is designed for devices running Android 3.x, make your application + compatible with older versions of Android by adding the + Support Library 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.
+If your application uses MapView elements, the important points to understand -are:
+android:apiKey — 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.
-If your application accesses remote servers or services, make sure you are using the production +URL or path for the server or service and not a test URL or path.
-When you've prepared your application as described in the previous sections, -you can compile your application for release.
- - -Sign your application using your private key and then -align it with the {@code zipalign} tool. Signing your application -correctly is critically important. Please see -Signing Your -Applications for complete information.
- -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 Register for a -Maps API Key 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.
- -After testing, you are now ready to publish your application to mobile device -users.
+If you are releasing 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 even if you are +releasing your app through Android Market.
+ +For more information about Android Market Licensing Service and how to use it in your +application, see Application Licensing.
+ +After you finish configuring your application you can build it into a release-ready
+.apk fle that is signed and optimized. The JDK includes the tools for signing the
+.apk file (Keytool and Jarsigner); the Android SDK includes the tools for compiling and
+optimizing the .apk file. If you are using Eclipse with the ADT plugin or you are using
+the Ant build script from the command line, you can automate the entire build process.
You can use the Eclipse Export Wizard to build a release-ready .apk file that is
+signed with your private key and optimized. To learn how to run the Export Wizard, see
+Compile and sign with Eclipse
+ADT. The Export Wizard compiles your application for release, signs your application with your
+private key, and optimizes your application with the zipalign tool. The Export Wizard should run
+successfully if you have run or debugged your application from Eclipse and you have no errors in
+your application (see Building
+and Running from Eclipse with ADT for more information.
The Export Wizard assumes that you have a certificate and private key +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 +Signing Your Applications for more +information about the signing process and signing guidelines.
+ +You can use the Ant build script (included in the Android SDK) to build a release-ready
+.apk file that is signed with your private key and optimized. To learn how to do this,
+see Building in
+Release Mode. This build method assumes you have a certificate and
+private key 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
+Signing Your Applications for more
+information about the signing process and signing guidelines.
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 in-app billing in your application and you are +performing the signature verification step on a remote server.
+ +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.
+ +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.
+ +As a starting point for testing, see +What to Test. 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 +Releasing Your +Application to Users. If you are publishing your application on Android Market, see +Publishing on Android Market.
diff --git a/docs/html/guide/publishing/publishing_overview.jd b/docs/html/guide/publishing/publishing_overview.jd new file mode 100755 index 0000000000000..a0f6ae35de0ad --- /dev/null +++ b/docs/html/guide/publishing/publishing_overview.jd @@ -0,0 +1,236 @@ +page.title=Publishing Overview +@jd:body + +Publishing is the process that makes your Android applications available to users. When you +publish an Android application you perform two main tasks:
+ +During the preparation step you build a release version of your application, which users can + download and install on their Android-powered devices.
+During the release step you publicize, sell, and distribute the release version of your + application to users.
+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.
+ +Figure 1 shows how the publishing process fits into the overall Android application development process. +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.
+ +
++ Figure 1. Publishing is the last phase of the Android application development process. +
+ +Preparing your application for release is a multi-step process that involves the following +tasks:
+ +At a minimum you need to remove {@link android.util.Log} calls and remove the
+ android:debuggable
+ attribute from your manifest file. You should also provide values for the
+ android:versionCode and android:versionName attributes, which are
+ located in the
+ <manifest>
+ 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.
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.
+Before you distribute your application, you should thoroughly test the release version on at + least one target handset device and one target tablet device.
+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.
+If your application depends on external servers or services, you need to be sure they + are secure and production ready.
+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 Google Maps external +library. 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.
+ +When you are finished preparing your application for release you will have a signed
+.apk file that you can distribute to users.
To learn how to prepare your application for release, see Preparing for Release in the Dev Guide. This +topic provides step-by-step instructions for configuring and building a release version of your +application.
+ +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—server +distribution and email distribution—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.
+ +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 in-app billing and application licensing. 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.
+ +Releasing your application on Android Market is a simple process that involves four basic + steps:
+ +
+ + Figure 2. The Unknown sources setting lets you install + applications that are not published on Android Market . +
+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.
+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.
+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.
+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 + Publish in the developer console and within minutes your application will be + live and available for download around the world.
+For information about Android Market, see Publishing on Android Market. This +topic provides an introduction to Android Market features and provides a step-by-step guide for +distributing your applications on Android Market.
+ +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.
+ +
+ + Figure 3. Users can simply click Install when you send them + an application via email. +
+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 Unknown sources setting on their devices, and +they need to make this configuration change before they download your application to their +device (see figure 2).
+ +Note: Some network providers do not allow users to install +applications from unknown sources.
+ +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.
+ +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 .apk and display an Install Now
+button in the email message (see figure 3). Users can install your application by touching the
+button.
Note: The Install Now 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.
+ +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. \ No newline at end of file diff --git a/docs/html/guide/publishing/versioning.jd b/docs/html/guide/publishing/versioning.jd index 01bfba85d4e5e..79ebf96bba680 100644 --- a/docs/html/guide/publishing/versioning.jd +++ b/docs/html/guide/publishing/versioning.jd @@ -32,8 +32,8 @@ page.title=Versioning Your Applications
Versioning is a critical component of your application upgrade/maintenance -strategy.
+Versioning is a critical component of your application upgrade and maintenance +strategy. Versioning is important because:
The Android system itself does not ever 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.
- -The Android system does check any system version compatibility expressed
-by an application in its manifest, in the minSdkVersion attribute. This
-allows an application to specify the minimum system API with which is compatible.
-For more information see Specifying Minimum System API Version.
+
The Android system does not use app version information to enforce
+restrictions on upgrades, downgrades, or compatibility of third-party apps. Instead, you (the
+developer) are responsible for enforcing version restrictions within your application or by
+informing users of the version restrictions and limitations. The Android system does, however,
+enforce system version compatibility as expressed by the minSdkVersion attribute in the
+manifest. This attribute allows an application to specify the minimum system API with which it is
+compatible. For more information see Specifying Minimum System API
+Version.
To define the version information for your application, you set attributes in @@ -65,7 +64,7 @@ always define values for both of them:
android:versionCode — 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.
The value is an integer so that other applications can programmatically
evaluate it, for example to check an upgrade or downgrade relationship. You can
@@ -83,7 +82,7 @@ user (see android:versionName, below). Applications and publishing
services should not display this version value to users.
android:versionName — 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.
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.
@@ -121,20 +120,20 @@ corresponds to a minor follow-on release, as shown by theThe 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)} +applications use the +{@link android.content.pm.PackageManager#getPackageInfo(java.lang.String, int)} method of {@link android.content.pm.PackageManager PackageManager}.
If your application requires a specific minimum version of the Android platform, or is designed only to support a certain range of Android platform -versions, you can specify those version requirements as API Level identifiers -in the application's manifest file. Doing so ensures that your +versions, you can specify those version requirements as API Level identifiers +in the application's manifest file. Doing so ensures that your application can only be installed on devices that are running a compatible version of the Android system.
-To specify API Level requirements, add a <uses-sdk>
+
To specify API Level requirements, add a <uses-sdk>
element in the application's manifest, with one or more of these attributes:
android:targetSdkVersion — Specifies the API Level
on which the application is designed to run. In some cases, this allows the
application to use manifest elements or behaviors defined in the target
-API Level, rather than being restricted to using only those defined
+API Level, rather than being restricted to using only those defined
for the minimum API Level.android:maxSdkVersion — 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. Important: Please read the <uses-sdk>
documentation before using this attribute.