6. Obtaining a Signing Certificate and API Key
Before you can publish your application to Android Market and have every Android user
in the world download it, you first must sign your application. In fact,
you’ve been signing your application all along, because the Android
Software Development Kit generates a debug signature that is used every
time you run your application from Eclipse. The catch is that you cannot
use the debug signature to publish your application to the world at
large; you must generate a new signature.
If you’re familiar with other mobile development environments (J2ME,
Symbian, BREW, etc.), you’re probably an old hand at signing applications.
But if you’re new to developing mobile applications, you may be asking
yourself what all this signing stuff is for, anyway. Android uses
application signing for only one purpose: to ensure that applications that
claim to be from the same developer actually are. Applications from the
same developer have special capabilities, discussed in the next
section.
Google has stated that one of its intentions with Android was to
minimize the hassle of getting applications signed. You don’t have to go
to a central signing authority to get a signing certificate; you can
create the certificate yourself. Once you generate the certificate, you
can sign your application using the jarsigner
tool that comes with the Java JDK. Once again, you don’t need to
apply for or get anyone’s approval. As you’ll see, it’s about as
straightforward as signing can be.
6.1. Getting a Signing Certificate for an Application You Are Going to
Ship
To sign your application, you are going to create an encrypted
signing certificate and use it to sign your application. You can sign
every Android application you develop with the same signing certificate.
You can create as many signing certificates as you want, but you really
need only one for all your applications. And using one certificate for
all your applications lets you do some things that you couldn’t do
otherwise:
Simplify upgrades
Signing certificates are tied to the application package
name, so if you change the signing certificate you use with
subsequent versions of your application, you’ll have to change the
package name, too. Changing certificates is manageable, but
messy.
Multiple applications per process
When all your applications share the same signing
certificate, they can run in the same Linux process. You can use
this to separate your application into smaller modules (each one
an Android application) that together make up the larger
application. If you were to do that, you could update the modules
separately and they could still communicate freely.
Code/data sharing
Android lets you enable or restrict access to parts of your
application based on the requester’s signing certificate. If all
your applications share the same certificate, it’s easy for you to
reuse parts of one application in another.
One of the things you’ll be asked when you generate a key pair and
certificate is the validity period you desire for the certificate.
Google recommends that you set it for at least 25 years, and in fact, if
you’re going to use Android Market to distribute your application, it
requires a validity date at least until October 22, 2033 (25 years to
the day from when they opened Android Market) for your
certificate.
6.1.1. Generating a key pair (public and private keys) and a signing
certificate
To generate a pair of public/private keys, use a tool called
keytool, which came with the Sun JDK when you
installed it onto your development computer.
keytool asks you for some information and uses
that to generate the pair of keys:
A private key that will be kept in a keystore on your
computer, secured with passwords. You will use the private key to
sign your application, and if you need a Map API Key for your
application, you will use the MD5 fingerprint of the signing
certificate to generate the Map API Key.
A public key that Android can use to decrypt your signing
certificate. You will send the public key along with your
published application so that it can be made available in the
runtime environment. Signing certificates are actually checked
only at install time, so once installed, your application is good
to run, even if the certificate or keys expire.
keytool is pretty straightforward. From your operating system’s command
line, enter something like:
$ keytool -genkey -v -keystore microjobs.keystore -alias mjkey -keyalg RSA
-validity 10000
This asks keytool to generate a key pair
and self-signed certificate (-genkey) in verbose mode
(-v), so you get all the information, and put it in a
keystore called microjobs.keystore
(-keystore). It also says that in the future you want
to refer to that key by the name mjkey (-alias), and that
keytool should use the RSA algorithm for
generating public/private key pairs (-keyalg).
Finally, we say that we’d like the key to be valid for 10,000 days
(-validity), or about 27 years.
keytool will prompt you for some things
it uses to build the key pair and certificate:
A password to be used in the future when you want to access
the keystore
Your first and last names
Your organizational unit (the name for your division of your
company, or something like “self” if you aren’t developing for a
company)
Your organization name (the name of your company, or
anything else you want to use)
The name of your city or locality
The name of your state or province
The two-letter country code where you are located
keytool will then echo all this
information back to you to make sure it’s accurate, and if you confirm
the information, will generate the key pair and certificate. It will
then ask you for another password to use for the key itself (and give
you the option of using the same password you used for the keystore).
Using that password, keytool will store the key
pair and certificate in the keystore.
You can get more information about security, key pairs, and the
keytool utility on Sun’s website at http://java.sun.com/j2se/1.5.0/docs/tooldocs/#security.
6.2. Getting a Signing Certificate While Debugging
When you’re creating and debugging your application that uses a MapView, or
when you’re running a demo application like MJAndroid, you still need a
valid Map API Key to get map tiles from Google Maps, and you need the
fingerprint of your debug signing certificate to obtain a Map API
Key. You can’t just use the apiKey that we
have coded into the MJAndroid source files, because it is tied to the
signing certificate that was generated by our debug environment. Your
debug environment will generate its own, different signing certificate
for you to use, so you need to obtain a Map API Key to match.
There are two steps to getting the key:
Get a copy of the MD5 fingerprint for your Debug signing
certificate.
Use that fingerprint to obtain a valid Map API Key from Google
and enter it into AndroidManifest.xml.
6.2.1. Getting the MD5 fingerprint of your Debug signing
certificate
When the Android SDK automatically generates a Debug signing
certificate for you, it places it in a keystore called debug.keystore. The trick is to find this
keystore. At least for the current version of the SDK, as this is
being written, the location is operating system dependent:
Under Linux and Mac OS X, it is in the .android subdirectory under your home directory: ~/.android/debug.keystore.
Under Windows Vista, it’s a little harder to find; it’s
under your personal Application Data directory:
C:\Users\your_username\AppData\Local\Android\debug.keystore.
Windows XP is similar to Vista: C:\Documents and
Settings\your_username\Local
Settings\Application Data\Android\debug.keystore
(unlike Vista, you will need to use a quoted string for the XP
shell).
Once you’ve found debug.keystore,
keytool can give you the MD5 fingerprint of your Debug signing
certificate. Under Linux or OS X you’d type:
$ keytool -list -alias androiddebugkey -keystore ~/.android/debug.keystore -storepass
android -keypass android
For Vista or XP, just substitute the correct location in the
-keystore option. keytool
prints the date the Debug signing certificate was created and the MD5
fingerprint. As an interesting note, Debug signing certificates are
good for 365 days after creation.
After your certificate expires, you’ll get a build error
whenever you try to build your application. The error will be
displayed on the Android console (one of the tabs in the bottom pane
of the Java and DDMS Perspectives), and it will say something
like: 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 To fix it, just delete your
debug.keystore file (see the earlier list for
its location in different host operating systems). The next time you
build, the Android SDK will generate a new
debug.keystore with a new Debug signing
certificate, and your application can build and run. |
Now that you have the MD5 fingerprint of your Debug Signing
Certificate, you can use it to get a valid Map API Key for your
system.
6.2.2. Getting a Map API Key from Google
Now that you have a signing certificate to use for your
application, you can apply to Google for a Map API Key. Map API Keys
are tied to a signing certificate, so obviously the Map API Key you
get will work only with applications signed with the same certificate
(another good reason for sticking with the same certificate for all
your applications). Getting the key is pretty easy, and it’s
free.
When an application that contains a MapView runs, it requests
map “tiles” from Google Maps via the Internet. As part of that
request, it sends the Map API Key that was obtained when the developer
signed up with Google, as well as the MD5 fingerprint of the
application’s signing certificate. Google Maps checks to see that the
key is registered to a developer, and then checks to see that the Map
API Key matches the one on file for applications with that signing
certificate fingerprint. If they match, it sends the requested tiles.
If they don’t match, no tiles are sent.
So we’re going to need the MD5 fingerprint of the signing
certificate that we just created. Fortunately,
keytool can get that for us:
$ keytool -list -alias mjkey -keystore microjobs.keystore
keytool asks for the passwords to the
keystore (and key, if they’re different), and prints out the MD5
fingerprint in hexadecimal. Use your mouse to copy the fingerprint so
you can paste it into the Google page later.
Now you can go to the Google Map API Key website at http://code.google.com/android/maps-api-signup.html to
actually get the Map API Key. The Terms of Service are shown in a text
box. Read them, and if appropriate, click on the checkbox that
indicates you accept. Paste the MD5 fingerprint into the form, click
the “Generate API key” button, and the website will ask you to log
into your Google account. If you don’t have a Google account, you can
quickly create one on the spot.
Once you log in, the website returns the Map API Key, which can
be used with any application that uses the signing certificate whose
fingerprint you entered. It’s a long alphanumeric string, so you will
want to copy it into your clipboard and paste it into the XML layout
file for your Map Activity.
As an example, the XML layout file for MJAndroid’s Map Activity
(called MicroJobs) has the following section defining the MapView and
the API Key that matches our debug environment:
<com.google.android.maps.MapView
android:id="@+id/mapmain"
android:layout_width="fill_parent"
android:layout_height="fill_parent"
android:clickable="true"
android:apiKey="0P18K0TAE0dO2GifdtbuScgEGLWe3p4CYUQngMg"
/>
Of course, you will have to substitute your own
apiKey for ours.
7. Signing Your Application
We’re almost ready to sign your
application, but first you need to create an unsigned version that you can sign
with your signature certificate. To do that, in the Package Explorer
window of Eclipse, right-click on your project name. You’ll get a long
pop-up menu; toward the bottom, click on Android Tools. You
should see another menu that includes the item you want: “Export Unsigned
Application Package...”. This item takes you to a File Save dialog box,
where you can pick the place to save the unsigned version of your
apk file. It doesn’t matter where you put it—just
pick a place you can remember.
Now that you have an unsigned version of your
apk file, we can go ahead and sign it using jarsigner. Open a terminal or
command window in the directory where you stored the unsigned
apk file. Here’s the line we used to sign MJAndroid,
using the key we generated earlier in the keystore
microjobs.keystore:
$ jarsigner -verbose -keystore microjobs.keystore MJAndroid.apk mjkey
Congratulations! You now have a signed version of your application
that can be loaded and run on any Android device. But before you send it
in to Android Market, there’s one more intervening step....
8. Retesting Your Application
If everything went smoothly, your application is now signed and will
function just as well as it did before you went through this process. But
to be sure things went smoothly, it is wise to retest your application,
again testing on real Android devices where possible. You really don’t
want thousands of people downloading a broken application attributed to
you, so just to be safe, retest on as many Android devices as you can get
your hands on.
9. Publishing on Android Market
After you’re satisfied that your application runs as expected on
real Android devices, you’re ready to upload to Android Market, Google’s
service for publishing and downloading Android applications. The procedure
is pretty straightforward:
Sign up as an Android Developer (if you’re not already signed
up).
Upload your signed application.
9.1. Signing Up As an Android Developer
Go to Google’s website at http://market.android.com/publish, and fill out the forms
provided. As this is written, Android Market is still in beta, and you
will be asked to:
Use your Google account to log in (if you don’t have a Google
account, you can get one for free by following the Create Account
link on the login page).
Agree to the Android Market Terms of Service.
Pay a one-time fee of $25 (payable by credit card via Google
Checkout; again, if you don’t have an account set up, you can do so
quickly).
The forms ask for a minimal amount of information—your name, phone
number, etc.—and you are signed
up.
9.2. Uploading Your Application
Now you can go to http://market.android.com/publish/Home to
upload your application. To identify and categorize your
application, you will be asked for the following:
Application apk file Name and
Location
The apk file of your application,
signed with your private signature certificate.
Title and Description
These are very important, because they are the core of your
marketing message to potential users. Try to make the title
descriptive and catchy at the same time, and describe the
application in a way that will make your target market want to
download it.
Application Type
There are currently two choices: Applications or
Games.
Category
The allowable list of categories varies depending on
Application Type. The currently available categories for
Applications are: Communications, Demo, Entertainment, Finance,
Lifestyle, Multimedia, News & Weather, Productivity,
Reference, Shopping, Social, Software Libraries, Tools, and
Travel. For Games, the currently available categories
include: Arcade & Action, Brain & Puzzle, Cards &
Casino, and Casual.
Price
This must be “Free” under the beta version of Android
Market. Google has said they will enable charging for applications
in the near future (maybe by the time you read this).
Geography
You can limit where your application is available, or choose
to make it available everywhere.
Finally, you are asked to confirm that your application meets the
Android Content Guidelines and that it does not knowingly violate any
export laws. After that, you can upload your apk
file, and within a few days your application will appear on the Android
Market online catalog, accessible from any connected Android device.
There is currently no way to access Android Market directly from your PC
or Mac, so you’ll have to use your Android phone to find out when your
application is available for
download.