diff options
Diffstat (limited to 'docs/html/guide/publishing')
| -rw-r--r-- | docs/html/guide/publishing/app-signing.jd | 96 | ||||
| -rw-r--r-- | docs/html/guide/publishing/licensing.html | 11 | ||||
| -rw-r--r-- | docs/html/guide/publishing/licensing.jd | 2388 | ||||
| -rw-r--r-- | docs/html/guide/publishing/preparing.jd | 51 | ||||
| -rw-r--r-- | docs/html/guide/publishing/publishing.jd | 481 | ||||
| -rwxr-xr-x | docs/html/guide/publishing/publishing_overview.jd | 71 | ||||
| -rw-r--r-- | docs/html/guide/publishing/versioning.jd | 2 |
7 files changed, 439 insertions, 2661 deletions
diff --git a/docs/html/guide/publishing/app-signing.jd b/docs/html/guide/publishing/app-signing.jd index 9abcdf7..5bd9be55 100644 --- a/docs/html/guide/publishing/app-signing.jd +++ b/docs/html/guide/publishing/app-signing.jd @@ -66,7 +66,7 @@ on an emulator or a device if it is not signed.</li> 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> +sign your application {@code .apk} files.</li> <li>After you sign your application for release, we recommend that you use the <code>zipalign</code> tool to optimize the final APK package.</li> </ul> @@ -82,7 +82,7 @@ run it or debug it on an emulator or device.</p> use to build your application. There are two build modes: <em>debug mode</em> and <em>release mode</em>. 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.</p> +distribute directly to users or publish on an application marketplace such as Google Play.</p> <p>When you build in <em>debug mode</em> 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, @@ -158,10 +158,10 @@ 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 +<li>If you plan to publish your application(s) on Google Play, 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 +ending after 22 October 2033. Google Play enforces this requirement +to ensure that users can seamlessly upgrade applications when new versions are available. </li> </ul> @@ -186,9 +186,9 @@ to the Keytool in the JDK.</p> <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. +requirement for signing your APK. When using debug mode to build your app, the SDK tools invoke Keytool to automatically create -a debug keystore and key. This debug key is then used to automatically sign the .apk, so +a debug keystore and key. This debug key is then used to automatically sign the APK, so you do not need to sign the package with your own key.</p> <p>The SDK tools create the debug keystore/key with predetermined names/passwords:</p> @@ -215,19 +215,19 @@ to the public when signed with the debug certificate.</p> <p>If you are developing in Eclipse/ADT (and have set up Keytool and Jarsigner as described above in <a href="#setup">Basic Setup for Signing</a>), 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 +application, ADT signs the {@code .apk} file with the debug certificate, runs {@code zipalign} on +the package, then installs it on the selected emulator or connected device. No specific action on your part is needed, provided ADT has access to Keytool.</p> <h3>Ant Users</h3> -<p>If you are using Ant to build your .apk files, debug signing mode +<p>If you are using Ant to build your {@code .apk} file, debug signing mode is enabled by using the <code>debug</code> option with the <code>ant</code> command (assuming that you are using a <code>build.xml</code> file generated by the <code>android</code> tool). When you run <code>ant debug</code> to -compile your app, the build script generates a keystore/key and signs the .apk for you. -The script then also aligns the .apk with the <code>zipalign</code> tool. +compile your app, the build script generates a keystore/key and signs the APK for you. +The script then also aligns the APK with the <code>zipalign</code> tool. No other action on your part is needed. Read <a href="{@docRoot}guide/developing/building/building-cmdline.html#DebugMode">Building and Running Apps on the Command Line</a> for more information.</p> @@ -292,7 +292,7 @@ key is one that:</p> 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 +<p>If you plan to publish your application(s) on Google Play, 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> @@ -383,8 +383,8 @@ 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> +href="http://docs.oracle.com/javase/6/docs/technotes/tools/windows/keytool.html"> +http://docs.oracle.com/javase/6/docs/technotes/tools/windows/keytool.html</a></p> @@ -399,11 +399,11 @@ You can not release your application unsigned, or signed with the debug key.</p> <h4>With Eclipse</h4> -<p>To export an <em>unsigned</em> .apk from Eclipse, right-click the project in the Package +<p>To export an <em>unsigned</em> APK from Eclipse, right-click the project in the Package Explorer and select <strong>Android Tools</strong> > <strong>Export Unsigned Application -Package</strong>. Then specify the file location for the unsigned .apk. -(Alternatively, open your <code>AndroidManifest.xml</code> file in Eclipse, open -the <em>Overview</em> tab, and click <strong>Export an unsigned .apk</strong>.)</p> +Package</strong>. Then specify the file location for the unsigned APK. +(Alternatively, open your <code>AndroidManifest.xml</code> file in Eclipse, select +the <strong>Manifest</strong> tab, and click <strong>Export an unsigned APK</strong>.)</p> <p>Note that you can combine the compiling and signing steps with the Export Wizard. See <a href="#ExportWizard">Compiling and signing with Eclipse ADT</a>.</p> @@ -414,11 +414,11 @@ the <em>Overview</em> tab, and click <strong>Export an unsigned .apk</strong>.)< with the <code>ant</code> command. For example, if you are running Ant from the directory containing your {@code build.xml} file, the command would look like this:</p> -<pre>ant release</pre> +<pre>$ ant release</pre> -<p>By default, the build script compiles the application .apk without signing it. The output file +<p>By default, the build script compiles the application APK without signing it. The output file in your project {@code bin/} will be <code><em><your_project_name></em>-unsigned.apk</code>. -Because the application .apk is still unsigned, you must manually sign it with your private +Because the application APK is still unsigned, you must manually sign it with your private key and then align it using {@code zipalign}.</p> <p>However, the Ant build script can also perform the signing @@ -443,8 +443,8 @@ 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> +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> @@ -459,6 +459,14 @@ the keystore containing your private key.</td> <td><code>-verbose</code></td><td>Enable verbose output.</td> </tr> <tr> +<td><code>-sigalg</code></td><td>The name of the signature algorithim to use in signing the APK. +Use the value {@code MD5withRSA}.</td> +</tr> +<tr> +<td><code>-digestalg</code></td><td>The message digest algorithim to use in processing the entries +of an APK. Use the value {@code SHA1}.</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. @@ -478,19 +486,23 @@ way, your password is not stored in your shell history.</p></td> <code>my_application.apk</code>, using the example keystore created above. </p> -<pre>$ jarsigner -verbose -keystore my-release-key.keystore +<pre>$ jarsigner -verbose -sigalg MD5withRSA -digestalg SHA1 -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> +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 class="caution"><strong>Caution:</strong> As of JDK 7, the default signing algorithim has +changed, requiring you to specify the signature and digest algorithims ({@code -sigalg} and {@code +-digestalg}) when you sign an APK.</p> -<p>To verify that your .apk is signed, you can use a command like this:</p> +<p>To verify that your APK is signed, you can use a command like this:</p> <pre>$ jarsigner -verify my_signed.apk</pre> -<p>If the .apk is signed properly, Jarsigner prints "jar verified". +<p>If the APK is signed properly, Jarsigner prints "jar verified". If you want more details, you can try one of these commands:</p> <pre>$ jarsigner -verify -verbose my_application.apk</pre> @@ -502,19 +514,19 @@ If you want more details, you can try one of these commands:</p> <p>The command above, with the <code>-certs</code> option added, will show you the "CN=" line that describes who created the key.</p> -<p class="note"><strong>Note:</strong> If you see "CN=Android Debug", this means the .apk was +<p class="note"><strong>Note:</strong> If you see "CN=Android Debug", this means the APK was signed with the debug key generated by the Android SDK. If you intend to release your application, you must sign it with your private key instead of the debug key.</p> <p>For more information about Jarsigner, see the documentation at -<a href="http://java.sun.com/j2se/1.5.0/docs/tooldocs/#security"> -http://java.sun.com/j2se/1.5.0/docs/tooldocs/#security</a></p> +<a href="http://docs.oracle.com/javase/6/docs/technotes/tools/windows/jarsigner.html"> +http://docs.oracle.com/javase/6/docs/technotes/tools/windows/jarsigner.html</a></p> <h3 id="align">4. Align the final APK package</h3> -<p>Once you have signed the .apk with your private key, run <code>zipalign</code> on the file. +<p>Once you have signed the APK with your private key, run <code>zipalign</code> on the file. This tool ensures that all uncompressed data starts with a particular byte alignment, relative to the start of the file. Ensuring alignment at 4-byte boundaries provides a performance optimization when installed on a device. When aligned, the Android @@ -524,16 +536,16 @@ of the data from the package. The benefit is a reduction in the amount of RAM consumed by the running application.</p> <p>The <code>zipalign</code> tool is provided with the Android SDK, inside the -<code>tools/</code> directory. To align your signed .apk, execute:</p> +<code>tools/</code> directory. To align your signed APK, execute:</p> -<pre>zipalign -v 4 <em>your_project_name</em>-unaligned.apk <em>your_project_name</em>.apk</pre> +<pre>$ zipalign -v 4 <em>your_project_name</em>-unaligned.apk <em>your_project_name</em>.apk</pre> <p>The {@code -v} flag turns on verbose output (optional). {@code 4} is the byte-alignment (don't use anything other than 4). The first file argument is -your signed .apk (the input) and the second file is the destination .apk file (the output). -If you're overriding an existing .apk, add the {@code -f} flag.</p> +your signed {@code .apk} file (the input) and the second file is the destination {@code .apk} file +(the output). If you're overriding an existing APK, add the {@code -f} flag.</p> -<p class="caution"><strong>Caution:</strong> Your input .apk must be signed with your +<p class="caution"><strong>Caution:</strong> Your input APK must be signed with your private key <strong>before</strong> you optimize the package with {@code zipalign}. If you sign it after using {@code zipalign}, it will undo the alignment.</p> @@ -544,7 +556,7 @@ If you sign it after using {@code zipalign}, it will undo the alignment.</p> <h3 id="ExportWizard">Compile and sign with Eclipse ADT</h3> <p>If you are using Eclipse with the ADT plugin, you can use the Export Wizard to -export a <em>signed</em> .apk (and even create a new keystore, +export a <em>signed</em> APK (and even create a new keystore, if necessary). The Export Wizard performs all the interaction with the Keytool and Jarsigner for you, which allows you to sign the package using a GUI instead of performing the manual procedures to compile, sign, @@ -554,7 +566,7 @@ Because the Export Wizard uses both Keytool and Jarsigner, you should ensure that they are accessible on your computer, as described above in the <a href="#setup">Basic Setup for Signing</a>.</p> -<p>To create a signed and aligned .apk in Eclipse:</p> +<p>To create a signed and aligned APK in Eclipse:</p> <ol> <li>Select the project in the Package @@ -563,7 +575,7 @@ Explorer and select <strong>File > Export</strong>.</li> and click <strong>Next</strong>. <p>The Export Android Application wizard now starts, which will guide you through the process of signing your application, - including steps for selecting the private key with which to sign the .apk + including steps for selecting the private key with which to sign the APK (or creating a new keystore and private key).</p> <li>Complete the Export Wizard and your application will be compiled, signed, aligned, and ready for distribution.</li> diff --git a/docs/html/guide/publishing/licensing.html b/docs/html/guide/publishing/licensing.html new file mode 100644 index 0000000..8e97f32 --- /dev/null +++ b/docs/html/guide/publishing/licensing.html @@ -0,0 +1,11 @@ +<html> +<head> +<meta http-equiv="refresh" +content="0;url=http://developer.android.com/guide/market/licensing/index.html"> +<title>Redirecting...</title> +</head> +<body> +<p>You should have been redirected. Please <a +href="http://developer.android.com/guide/market/licensing/index.html">click here</a>.</p> +</body> +</html>
\ No newline at end of file diff --git a/docs/html/guide/publishing/licensing.jd b/docs/html/guide/publishing/licensing.jd deleted file mode 100644 index 609241b..0000000 --- a/docs/html/guide/publishing/licensing.jd +++ /dev/null @@ -1,2388 +0,0 @@ -page.title=Application Licensing -@jd:body - -<div id="qv-wrapper"> -<div id="qv"> - - <h2>Quickview</h2> - <ul> - <li>Licensing lets you protect your application on any device that includes Android Market.</li> - <li>Your app maintains control of how it enforces its licensing status. </li> - <li>Adding licensing to an app is straightforward, using the library available through the SDK.</li> - <li>The service is free and is available to all developers who publish on Android Market. </li> - </ul> - - <h2>In this document</h2> - <ol> - <li><a href="#account">Setting Up A Publisher Account</a></li> - <li><a href="#dev-setup">Setting Up the Development Environment</a></li> - <li><a href="#app-integration">Integrating the LVL with Your Application</a> - <ol> - <li><a href="#add-library">Including the LVL</a></li> - <li><a href="#manifest-permission">Adding the licensing permission</a></li> - <li><a href="#impl-Policy">Implementing a Policy</a></li> - <li><a href="#impl-Obfuscator">Implementing an Obfuscator</a></li> - <li><a href="#impl-lc">Checking the license</a></li> - <li><a href="#impl-DeviceLimiter">Implementing a DeviceLimiter</a></li> - </ol></li> - <li><a href="#test-env">Setting Up the Test Environment</a> - <ol> - <li><a href="#test-response">Test responses</a></li> - <li><a href="#test-acct-setup">Test accounts</a></li> - <li><a href="#acct-signin">Signing in on a device or emulator</a></li> - </ol></li> - <li><a href="#app-obfuscation">Obfuscating Your Application</a></li> - <li><a href="#app-publishing">Publishing a Licensed Application</a></li> - <li><a href="#support">Where to Get Support</a></li> - </ol> - - <h2>Appendix</h2> - <ol> - <li><a href="#lvl-summary">Summary of LVL Classes and Interfaces</a></li> - <li><a href="#server-response-codes">Server Response Codes</a></li> - <li><a href="#extras">Server Response Extras</a></li> - </ol> - -</div> -</div> - -<p>Android Market offers a licensing service that lets you enforce licensing -policies for paid applications that you publish through Android Market. With -Android Market Licensing, your applications can query Android Market at run time to -obtain their licensing status for the current user, then allow or disallow -further use as appropriate. </p> - -<p>Using the service, you can apply a flexible licensing policy on an -application-by-application basis — each application can enforce licensing -in the way most appropriate for it. If necessary, an application can apply custom -constraints based on the licensing status obtained from Android Market. -For example, an application can check the licensing status and then apply custom -constraints that allow the user to run it unlicensed for a specific number -of times, or for a specific validity period. An application can also restrict use of the -application to a specific device, in addition to any other constraints. </p> - -<p>The licensing service is a secure means of controlling access to your -applications. When an application checks the licensing status, the Market server -signs the licensing status response using a key pair that is uniquely associated -with the publisher account. Your application stores the public key in its -compiled <code>.apk</code> file and uses it to verify the licensing status -response.</p> - -<p>Any application that you publish through Android Market can use the Android -Market Licensing service. No special account or registration is needed. -Additionally, because the service uses no dedicated framework APIs, you can add -licensing to any legacy application that uses a minimum API level of 3 or -higher.</p> - -<p>To help you add licensing to your application, the Android SDK provides -library sources that you can include in your application project. The -License Verification Library (LVL) handles all of -the licensing-related communication with the Android Market client and the -licensing service. With the LVL integrated, your application can determine its -licensing status for the current user by simply calling a library checker method -and implementing a callback that receives the status.</p> - -<p>This document explains how the licensing service works and how to add it to -your application. </p> - - -<h2 id="overview">Overview</h2> - -<p>Android Market Licensing is a network-based service that lets an application -on an Android-powered device query a trusted licensing server, to determine -whether the application is licensed to the current device user. After receiving -the server response, the application can then allow or disallow further use of -the application as needed. In the service, the role of the licensing server is -to provide the license status for the current user; the application itself is -responsible for querying the server and conditionally granting access to the -application. </p> - -<h4>Application, Android Market client, and server</h4> - -<p>The licensing service is based on the capability of the Android Market server -to determine whether a given user is licensed to use a given application. The licensing server -considers a user to be licensed if the user is a recorded purchaser of an application. If a paid -application has been uploaded to Android Market but saved only as a draft application (in -other words, the app is unpublished), the licensing server considers all users to be licensed users -of the application. Keep in mind, you cannot implement Android Market Licensing in a free -application.</p> - -<p>To properly identify -the user and determine the license status, the server requires information about -the application and user — the application and the Android Market client -work together to assemble the information and pass it to the server. </p> - -<p>In the licensing service, an application does not query the licensing server -directly, but instead calls the Android Market client over remote IPC to -initiate a license request. In the license request:</p> - -<ul> -<li>The application provides its package name and a nonce that is later used to -validate any response from the server, as well as a callback over which the -response can be returned asynchronously.</li> -<li>The Android Market client, which has greater permissions than the -application, collects the necessary information about the user and the device, -such as the device's primary Google account username, IMSI, and other -information. It then sends the license check request to the server on behalf of -the application.</li> -<li>The server evaluates the request using all available information, attempting -to establish the user's identity to a sufficient level of confidence. The server -then checks the user identity against purchase records for the application and -returns a license response, which the Android Market client returns to the -application over the IPC callback.</li> -</ul> - -<p>Notice that during a license check, the application does not manage any -network connections or use any licensing related APIs in the Android platform. -</p> - -<div class="figure" style="width:469px"> -<img src="{@docRoot}images/licensing_arch.png" alt=""/> -<p class="img-caption"><strong>Figure 1.</strong> Your application initiates a -license check through the LVL and the Android Market -client, which handles communication with the Market server.</p> -</div> - -<h4>License responses secured through public key cryptography</h4> - -<p>To ensure the integrity of each license query, the server signs the license -response data using an RSA key pair that is shared exclusively between the -server and the application publisher.</p> - -<p>The licensing service generates a single licensing key pair for each -publisher account and exposes the public key in the account's profile page. The -publisher copies the public key and embeds it in the application source code, -then compiles and publishes the <code>.apk.</code> The server retains the -private key internally and uses it to sign license responses for applications -published on that account. </p> - -<p>When the application receives a signed response, it uses the embedded public -key to verify the data. The use of public key cryptography in the licensing -service makes it possible for the application to detect responses that have been -tampered with or that are spoofed.</p> - -<h4>Use of licensing in your application</h4> - -<p>To use licensing in your application, add code to the application to -initiate a license check request and handle the response when it is received. -You can choose when, and how often, you want your application to check its -license and you have full control over how it handles the response, verifies the -signed response data, and enforces access controls. </p> - -<p>To simplify the process of adding support for licensing, download and -integrate the Licensing Verification Library, described below. Integration is -straightforward.</p> - -<p>When you are finished integrating the LVL, use a test environment -provided by the publisher site to test your application's handling of server -responses. </p> - -<p>Finally, publish the application <code>.apk</code> on Market using the -normal process. If you previously used the copy-protection provided by Android -Market, you can remove it from applications that use licensing. </p> - -<h4>Licensing Verification Library simplifies implementation</h4> - -<p>The Android SDK includes a License Verification Library (LVL) that you can -download and use as the basis for your application's licensing implementation. -The LVL greatly simplifies the process of adding licensing to your application -and helps ensure a more secure, robust implementation for your application. The -LVL provides internal classes that handle most of the standard operations of a -license query, such as contacting Android Market to initiate a license request -and verifying and validating the responses. It also exposes key interfaces that -let you easily plug in your custom code for defining licensing policy and -managing access as needed by your application. The key LVL interfaces are: </p> - -<ul> -<li>Policy — your implementation determines whether to allow access to the -application, based on the license response received from the server and any -other data available (such as from a backend server associated with your -application). The implementation can evaluate the various fields of the license -response and apply other constraints, if needed. The implementation also lets -you manage the handling of license checks that result in errors, such as network -errors.</li> -<li>LicenseCheckerCallback — your implementation manages access to the -application, based on the result of the Policy's handling of the license -response. Your implementation can manage access in any way needed, including -displaying the license result in the UI or directing the user to purchase the -application (if not currently licensed). </li> -</ul> - -<p>To help you get started with a Policy, the LVL provides two fully complete -Policy implementations that you can use without modification or adapt to your -needs:</p> - -<ul> -<li><a href="#ServerManagedPolicy">ServerManagedPolicy</a> is a flexible Policy -that uses settings provided by the licensing server to manage response caching -and access to the application while the device is offline (such as when the -user is on an airplane). For most applications, the use of -ServerManagedPolicy is highly recommended. </li> -<li><a href="#StrictPolicy">StrictPolicy</a> is a restrictive Policy that -does not cache any response data and allows the application access <em>only</em> -when the server returns a licensed response.</li> -</ul> - -<p>The LVL is available as a downloadable component of the Android SDK. The -component includes both the LVL itself and an example application that shows how -the library should be integrated with your application and how your application -should manage response data, UI interaction, and error conditions. </p> - -<p>The LVL sources are provided as an Android <em>library project</em>, which -means that you can maintain a single set of library sources and share them -across multiple applications. A full test environment is also available through -the SDK, so you can develop and test the licensing implementation in your -applications before publishing them, even if you don't have access to a -physical device.</p> - -<h4>Requirements and limitations</h4> - -<p>Android Market Licensing is designed to let you apply license controls to -applications that you publish through Android Market. The service is not -designed to let you control access to applications that are not published -through Android Market or that are run on devices that do not offer the Android -Market client. </p> - -<p>Here are some points to keep in mind as you implement licensing in your -application: </p> - -<ul> -<li>Only paid applications published through Market can use the -service.</li> -<li>An application can use the service only if the Android Market client is -installed on its host device and the device is running Android 1.5 (API level 3) -or higher.</li> -<li>To complete a license check, the licensing server must be accessible over -the network. You can implement license caching behaviors to manage access when -there is no network connectivity. </li> -<li>The security of your application's licensing controls ultimately relies on -the design of your implementation itself. The service provides the building -blocks that let you securely check licensing, but the actual enforcement and -handling of the license are factors in your control. By following the best -practices in this document, you can help ensure that your implementation will be -secure.</li> -<li>Adding licensing to an application does not affect the way the application -functions when run on a device that does not offer Android Market.</li> -<li>Licensing is currently for paid apps only, since draft apps are -licensed for all users. If your application is already published as a free app, -you won't be able to upload a new version that uses licensing.</li> -</ul> - -<h4>Replacement for Copy Protection</h4> - -<p>Android Market Licensing is a flexible, secure mechanism for controlling -access to your applications. It effectively replaces the Copy Protection -mechanism offered on Android Market and gives you wider distribution -potential for your applications. </p> - -<ul> -<li>A limitation of the legacy Copy Protection mechanism on Android Market is -that applications using it can be installed only on compatible devices that -provide a secure internal storage environment. For example, a copy-protected -application cannot be downloaded from Market to a device that provides root -access, and the application cannot be installed to a device's SD card. </li> -<li>With Android Market licensing, you can move to a license-based model in -which access is not bound to the characteristics of the host device, but to your -publisher account on Android Market and the licensing policy that you define. -Your application can be installed and controlled on any compatible device on -any storage, including SD card.</li> -</ul> - -<p>Although no license mechanism can completely prevent all unauthorized use, -the licensing service lets you control access for most types of normal usage, -across all compatible devices, locked or unlocked, that run Android 1.5 or -higher version of the platform.</p> - -<p>The sections below describe how to add Android Market licensing to your -applications. </p> - -<h2 id="account">Setting Up a Publisher Account</h2> - -<p>Android Market licensing lets you manage access to applications that -users have downloaded from Android Market. To use licensing in an application, -you need to have a publisher account on Android Market so that you can -publish the application to users. </p> - -<p>If you don't already have a publisher account, you need to register for one -using your Google account and agree to the terms of service. Once you are -registered, you can upload applications at your convenience and begin debugging -and testing your licensing implementation. For more information about publishing -on Android Market, see <a -href="{@docRoot}guide/publishing/publishing.html">Publishing Your -Applications</a></p> - -<p>To register as an Android Market developer and set up your publisher account, -visit the Android Market publisher site:</p> - -<p style="margin-left:2em;"><a -href="http://market.android.com/publish">http://market.android.com/publish</a> -</p> - -<p>If you already have a publisher account on Android Market, use your existing -account to set up licensing. You <em>do not</em> need to register for a new -account to support licensing (and doing so is not recommended, especially if you -are adding licensing support to applications that you have already published). -In all cases, if you have published applications, you manage licensing for those -applications through the account on which the applications are published. </p> - -<p>Once your publisher account is set up, use the account to:</p> - -<ul> -<li>Obtain a public key for licensing</li> -<li>Debug and test an application's licensing implementation, prior to -publishing the application</li> -<li>Publish the applications to which you have added licensing support</li> -</ul> - -<h4>Administrative settings for licensing</h4> - -<p>Once you are signed into your publisher account, you can manage several -administrative controls for Android Market licensing. The controls are available -in the Edit Profile page, in the "Licensing" panel, shown below. The controls -let you: </p> - -<ul> -<li>Set up multiple "test accounts", identified by email address. The licensing -server allows users signed into test accounts on a device or emulator to send -license checks and receive static test responses.</li> -<li>Obtain the account's public key for licensing. When you are implementing -licensing in an application, you must copy the public key string into the -application.</li> -<li>Configure static test responses that the server sends, when it receives a -license check for an application uploaded to the publisher account, from a user -signed in to the publisher account or a test account.</li> -</ul> - -<div style="margin-bottom:2em;"> - -<img src="{@docRoot}images/licensing_public_key.png" style="text-align:left;margin-bottom:0;" /> -<div style="margin:0 2em;padding:0"><strong>Figure 2.</strong> The Licensing -panel of your account's Edit Profile page lets you manage administrative -settings for licensing.</div> -</div> - -<p>For more information about how to work with test accounts and static test -responses, see <a href="#test-env">Setting Up a Testing Environment</a>, below. - -<h2 id="dev-setup">Setting Up the Development Environment</h2> - -<p>Once you've set up your publisher account on Android Market, the next step is -to set up your development environment for licensing. </p> - -<p>Setting up your environment for licensing involves these tasks:</p> - -<ol> -<li><a href="#download-sdk">Downloading the latest SDK</a>, if you haven't already done so </li> -<li><a href="#runtime-setup">Setting up the runtime environment</a> for development</li> -<li><a href="#download-lvl">Downloading the Market Licensing component</a> into your SDK </li> -<li><a href="#lvl-setup">Setting up the Licensing Verification Library</a></li> -<li><a href="#add-library">Including the LVL library project in your application</a></li> -</ol> - -<p>The sections below describe these tasks. When you are done with setup, -you can begin <a href="#app-integration">integrating the LVL into your applications</a>.</p> - -<p>To get started, you need to set up a proper runtime environment on which -you can run, debug and test your application's implementation of license -checking and enforcement. </p> - - -<h3 id="download-sdk">Downloading the latest SDK</h3> - -<div class="sidebox-wrapper"> -<div class="sidebox"> -<h2>Licensing sample application</h2> - -<p>To work with Android Market licensing, you need a functioning Android -application to which you can add licensing support. </p> - -<p style="margin-top:.5em;">If you are new to Android -and don't yet have a functioning application, the LVL component includes a sample -application that you can set up as a new application project. The sample provides -a complete, working example of how licensing works. For more information, see <a -href="#download-lvl">Downloading the LVL</a>.</p> - -</div> -</div> - -<p>If you haven't done so, you need to download the Android SDK before you can -develop Android applications. The SDK provides the tools that you need to build -and debug Android applications, including applications that use Android Market -licensing. For complete information, including installation instructions, see -the <a href="{@docRoot}sdk/index.html">Android SDK</a>. </p> - -<p>If you have already installed the SDK, make sure to update the -SDK tools and ADT Plugin to the latest versions. You can update the SDK tools -using the Android SDK and AVD Manager and ADT through <strong>Help</strong> > -<strong>Software Updates...</strong> in Eclipse. </p> - -<p>After you've installed the latest SDK and tools, set up your development -environment as described below. </p> - - -<h3 id="runtime-setup">Setting up the runtime environment</h3> - -<p>As described earlier, applications check licensing status not by contacting -the licensing server directly, but by binding to a service provided by the -Android Market application and initiating a license check request. The Android -Market service then handles the direct communication with the licensing server -and finally routes the response back to your application. To debug and test -licensing in your application, you need to set up a runtime environment that -includes the necessary Android Market service, so that your application is able -to send license check requests to the licensing server. </p> - -<p>There are two types of runtime environment that you can use: </p> - -<ul> -<li>An Android-powered device that includes the Android Market application, or</li> -<li>An Android emulator running the Google APIs Add-on, API level 8 (release 2) -or higher</li> -</ul> - -<p>The sections below provide more information. </p> - -<h4 id="runtime-device">Running on a device</h4> - -<p>You can use an Android-powered device as the runtime environment for -debugging and testing licensing on your application.</p> - -<p>The device you use must:</p> - -<ul> -<li>Run a standard version of the Android 1.5 or later (API level -3 or higher) platform, <em>and</em> </li> -<li>Run a system image on which the Android Market client application -is preinstalled. </li> -</ul> - -<p>If Android Market is not preinstalled in the system image, your application won't -be able to communicate with the Android Market licensing server. </p> - -<p>For general information about how to set up a device for use in developing -Android applications, see <a -href="{@docRoot}guide/developing/device.html">Developing on a Device</a>.</p> - -<h4 id="runtime-emulator">Running on an Android emulator</h4> - -<p>You can also use an Android emulator as your runtime -environment for debugging and testing licensing.</p> - -<p>Because the standard Android platforms provided in the Android SDK <em>do -not</em> include Android Market, you need to download the Google APIs Add-On -platform, API Level 8 (or higher), from the SDK repository. After downloading -the add-on, you need to create an AVD configuration that uses that system image. -</p> - -<p>The Google APIs Add-On does not include the full Android Market client. -However, it does provide: </p> - -<ul> -<li>An Android Market background service that implements the -ILicensingService remote interface, so that your application can -send license checks over the network to the licensing server. </li> -<li>A set of underlying account services that let you add an a Google account on -the AVD and sign in using your publisher account or test account credentials. -Signing in using your publisher or test account enables you to debug and test -your application without having publish it. For more information see <a -href="#acct-signin">Signing in to an authorized account</a>, below.</li> -</ul> - -<p>Several versions of the add-on are available in the SDK repository, but only -<strong>Google APIs Add-On, API 8 (release 2) or higher</strong> version of the -add-on includes the necessary Android Market services. This means that you -cannot use Google APIs Add-On API 7 or lower as a runtime environment for -developing licensing on an emulator.</p> - -<div style="margin-bottom:2em;"> - -<img src="{@docRoot}images/licensing_gapis_8.png" style="text-align:left;margin-bottom:0;" /> -<div style="margin:0 2em;padding:0"><strong>Figure 3.</strong> Google APIs -Add-On, API 8 (release 2) or higher lets you debug and test your licensing -implementation in an emulator.</div> -</div> - -<p>To set up an emulator for adding licensing to an application, follow -these steps: </p> - -<ol> - <li>Launch the Android SDK and AVD Manager. </li> - <li>In the <strong>Available Packages</strong> panel, select and download the -SDK component "Google APIs (Google Inc.) - API Level 8" (or higher) from the SDK -repository, as shown in the figure above. - <p>When the download is complete, use the Android SDK and AVD Manager to -create a new AVD based on that component, described next.</p></li> - <li>In the <strong>Virtual -Devices</strong> panel of the Android SDK and AVD Manager, click -<strong>New</strong> and set the configuration details for the new AVD. </li> - <li>In the dialog that appears, assign a descriptive name to the AVD and then -use the "Target" menu to choose the "Google APIs (Google Inc.) - API Level 8" as -the system image to run on the new AVD. Set the other configuration details as -needed and then click <strong>Create AVD</strong> to finish. The SDK tools -create the new AVD configuration, which then appears in the list of available -Android Virtual Devices.</li> -</ol> - -<p>If you are not familiar with AVDs or how to use them, see <a -href="{@docRoot}guide/developing/devices/index.html">Managing Virtual Devices</a>.</p> - -<h4 id="project-update">Updating your project configuration</h4> - -<p>After you set up a runtime environment that meets the requirements described -above — either on an actual device or on an emulator — make sure to -update your application project or build scripts as needed, so that your compiled -<code>.apk</code> files that use licensing are deployed into that environment. -In particular, if you are developing in Eclipse, make sure that you set up a -Run/Debug Configuration that targets the appropriate device or AVD. </p> - -<p>You do not need to make any changes to your application's -build configuration, provided that the project is already configured to compile -against a standard Android 1.5 (API level 3) or higher library. For example: - -<ul> -<li>If you have an existing application that is compiled against -the Android 1.5 library, you do not need to make any changes to your -build configuration to support licensing. The build target meets the minimum -requirements for licensing, so you would continue building -against the same version of the Android platform.</li> - -<li>Similarly, if you are building against Android 1.5 (API level 3) but -are using an emulator running the Google APIs Add-On API 8 as the application's -runtime environment, there is no need to change your application's build -configuration. </li> -</ul> - -<p>In general, adding licensing to an application should have no impact -whatsoever on the application's build configuration.</p> - - -<h3 id="download-lvl">Downloading the LVL</h3> - -<p>The License Verification Library (LVL) is a collection of helper classes that -greatly simplify the work that you need to do to add licensing to your -application. In all cases, we recommend that you download the LVL and use it as -the basis for the licensing implementation in your application.</p> - -<p>The LVL is available as a downloadable component of the Android SDK. The -component includes: </p> - -<ul> -<li>The LVL sources, stored inside an Android library project. </li> -<li>An example application called "sample" that depends on the LVL library -project. The example illustrates how an application uses the library helper -classes to check and enforce licensing.</li> -</ul> - -<p>To download the LVL component into your development environment, use the -Android SDK and AVD Manager. Launch the Android SDK and AVD Manager and then -select the "Market Licensing" component, as shown in the figure below. -Accept the terms and click <strong>Install Selected</strong> to begin the download. </p> - -<div style="margin-bottom:2em;"> - -<img src="{@docRoot}images/licensing_package.png" style="text-align:left;margin-bottom:0;" /> -<div style="margin:0 2em;padding:0"><strong>Figure 4.</strong> The Market -Licensing package contains the LVL and the LVL sample application. </div> -</div> - -<p>When the download is complete, the Android SDK and AVD Manager installs both -the LVL library project and the example application into these directories: </p> - -<p style="margin-left:2em"><code><<em>sdk</em>>/extras/google/market_licensing/library/</code> - (the LVL library project)<br /> -<code><<em>sdk</em>>/extras/google/market_licensing/sample/</code> (the example -application)</p> - -<p>If you aren't familiar with how to download components into your SDK, see the -<a href="{@docRoot}sdk/adding-components.html">Adding SDK Components</a> -document. </p> - - -<h3 id="lvl-setup">Setting Up the Licensing Verification Library</h3> - -<p>After downloading the LVL to your computer, you need to set it up in your -development environment, either as an Android library project or by -copying (or importing) the library sources directly into your existing -application package. In general, using the LVL as a library project is recommended, -since it lets you reuse your licensing code across multiple applications and -maintain it more easily over time. Note that the LVL is not designed to be -compiled separately and added to an application as a static .jar file. </p> - -<h4>Moving the library sources to a new location</h4> - -<p>Because you will be customizing the LVL sources to some extent, you should -make sure to <em>move or copy</em> the library sources (the entire -directory at <code><<em>sdk</em>>/market_licensing/library/</code>) -to a working directory outside of the SDK. You should then use the relocated -sources as your working set. If you are using a source-code management -system, add and track the sources that are in the working location rather -than those in default location in the SDK. </p> - -<p>Moving the library sources is important is because, when you later update the -Market licensing package, the SDK installs the new files to the same location as -the older files. Moving your working library files to a safe location ensures -that your work won't be inadvertently overwritten should you download a new -version of the LVL.</p> - -<h4>Creating the LVL as a library project</h4> - -<div class="sidebox-wrapper"> -<div class="sidebox"> -<h2>Working with library projects</h2> - -<p>The LVL is provided as an Android library project, which means that you can -share its code and resources across multiple applications. </p> - -<p style="margin-top:.5em;">If you aren't familiar with library projects or how -to use them, see <a href="{@docRoot}guide/developing/projects/index.html#LibraryProjects"> -Managing Projects</a>. -</p> -</div> -</div> - -<p>The recommended way of using the LVL is setting it up as a new Android -<em>library project</em>. A library project is a type of development project -that holds shared Android source code and resources. Other Android application -projects can reference the library project and, at build time, include its -compiled sources in their <code>.apk</code> files. In the context of licensing, -this means that you can do most of your licensing development once, in a library -project, then include the library sources in your various application projects. -In this way, you can easily maintain a uniform implementation of licensing -across all of your projects and maintain it centrally. </p> - -<p>The LVL is provided as a configured library project — once you have -downloaded it, you can start using it right away. </p> - -<p>If you are working in Eclipse with ADT, you need to add the LVL to your -workspace as a new development project, in the same way as you would a new -application project. </p> - -<ol> -<li>Use the New Project Wizard to create a new -project from existing sources. Select the LVL's <code>library</code> directory -(the directory containing the library's AndroidManifest.xml file) as the project -root.</li> -<li>When you are creating the library project, you can select any application -name, package, and set other fields as needed. </li> -<li>For the library's build target, select Android 1.5 (API level 3) or higher.</li> -</ol> - -<p> When created, the project is -predefined as a library project in its <code>project.properties</code> file, so -no further configuration is needed. </p> - -<p>For more information about how to create an application project or work with -library projects in Eclipse, see <a -href="{@docRoot}guide/developing/projects/projects-eclipse.html">Managing Projects from -Eclipse with ADT</a></p>. - -<h4>Copying the LVL sources to your application</h4> - -<p>As an alternative to adding the LVL as a library project, you can copy the -library sources directly into your application. To do so, copy (or import) the -LVL's <code>library/src/com</code> directory into your application's -<code>src/</code> directory.</p> - -<p>If you add the LVL sources directly to your application, you can skip the -next section and start working with the library, as described in <a -href="#app-integration"></a>.</p> - - -<h3 id="add-library">Including the LVL library project sources in your -application</h3> - -<p>If you want to use the LVL sources as a library project, you need to add a -reference to the LVL library project in your application project properties. This tells -build tools to include the LVL library project sources in your application at -compile time. The process for adding a reference to a library project depends -on your development environment, as described below.</p> - -<p> If you are developing in Eclipse with ADT, you should already have added the -library project to your workspace, as described in the previous section. If you -haven't done that already, do it now before continuing. </p> - -<p>Next, open the application's project properties window, as shown below. -Select the "Android" properties group and click <strong>Add</strong>, then -choose the LVL library project (com_android_vending_licensing) and click -<strong>OK</strong>. For more information, see -<a href="{@docRoot}guide/developing/projects/projects-eclipse.html#SettingUpLibraryProject"> -Managing Projects from Eclipse with ADT</a></p>. - -<div style="margin-bottom:2em;"> - -<img src="{@docRoot}images/licensing_add_library.png" style="text-align:left;margin-bottom:0;" /> -<div style="margin:0 2em;padding:0"><strong>Figure 5.</strong> If you are -working in Eclipse with ADT, you can add the LVL library project to your -application from the application's project properties.</div> -</div> - -<p>If you are developing using the SDK command-line tools, navigate to the -directory containing your application project and open the -<code>project.properties</code> file. Add a line to the file that specifies the -<code>android.library.reference.<n></code> key and the path to the -library. For example: </p> - -<pre>android.library.reference.1=path/to/library_project</pre> - -<p>Alternatively, you can use this command to update the project -properties, including the reference to the library project:</p> - -<pre class="no-pretty-print" style="color:black">android update lib-project ---target <em><target_ID></em> \ ---path <em>path/to/my/app_project</em> \ ---library <em>path/to/my/library_project</em> -</pre> - -<p>For more information about working with library projects, -see <a href="{@docRoot}guide/developing/projects/projects-cmdline.html#SettingUpLibraryProject"> -Managing Projects from the Command Line</a></p>. - - -<h2 id="app-integration">Integrating the LVL with Your Application</h2> - -<p>Once you've followed the steps above to set up a publisher account and -development environment, you are ready to begin integrating the LVL with your -application. </p> - -<p>Integrating the LVL with your application code involves these tasks:</p> - -<ol> -<li><a href="#manifest-permission">Adding the licensing permission</a> your application's manifest.</li> -<li><a href="#impl-Policy">Implementing a Policy</a> — you can choose one of the full implementations provided in the LVL or create your own.</li> -<li><a href="#impl-Obfuscator">Implementing an Obfuscator</a>, if your Policy will cache any license response data. </li> -<li><a href="#impl-lc">Adding code to check the license</a> in your application's main Activity</li> -<li><a href="#impl-DeviceLimiter">Implementing a DeviceLimiter</a> (optional and not recommended for most applications)</li> -</ol> - -<p>The sections below describe these tasks. When you are done with the -integration, you should be able to compile your application successfully and you -can begin testing, as described in <a href="#test-env">Setting Up the Test -Environment</a>.</p> - -<p>For an overview of the full set of source files included in the LVL, see <a -href="#lvl-summary">Summary of LVL Classes and Interfaces</a>.</p> - - -<h3 id="manifest-permission">Adding the licensing permission to your -AndroidManifest.xml</h3> - -<p>To use the Android Market application for sending a license check to the -server, your application must request the proper permission, -<code>com.android.vending.CHECK_LICENSE</code>. If your application does -not declare the licensing permission but attempts to initiate a license check, -the LVL throws a security exception.</p> - -<p>To request the licensing permission in your application, declare a <a -href="{@docRoot}guide/topics/manifest/uses-permission-element.html"><code><uses-permission></code></a> -element as a child of <code><manifest></code>, as follows: </p> - -<p style="margin-left:2em;"><code><uses-permission -android:name="com.android.vending.CHECK_LICENSE"></code></p> - -<p>For example, here's how the LVL sample application declares the permission: -</p> - -<pre><?xml version="1.0" encoding="utf-8"?> - -<manifest xmlns:android="http://schemas.android.com/apk/res/android" ..."> - <!-- Devices >= 3 have version of Android Market that supports licensing. --> - <uses-sdk android:minSdkVersion="3" /> - <!-- Required permission to check licensing. --> - <uses-permission android:name="com.android.vending.CHECK_LICENSE" /> - ... -</manifest> -</pre> - -<p class="note"><strong>Note:</strong> Currently, you cannot declare the -<code>CHECK_LICENSE</code> permission in the LVL library project's manifest, -because the SDK Tools will not merge it into the manifests of dependent -applications. Instead, you must declare the permission in each dependent -application's manifest. </p> - - -<h3 id="impl-Policy">Implementing a Policy</h3> - -<div class="sidebox-wrapper"> -<div class="sidebox"> -<h2>ServerManagedPolicy</h2> - -<p>The LVL includes a complete Policy implementation called ServerManagedPolicy -that makes use of license-management settings provided by the Android Market -server. </p> - -<p style="margin-top:.5em;">Use of ServerManagedPolicy as the basis for your -Policy is strongly recommended. For more information, see <a -href="#ServerManagedPolicy">ServerManagedPolicy</a> section, below.</p> - -</div> -</div> - -<p>Android Market licensing service does not itself determine whether a -given user with a given license should be granted access to your application. -Rather, that responsibility is left to a Policy implementation that you provide -in your application.</p> - -<p>Policy is an interface declared by the LVL that is designed to hold your -application's logic for allowing or disallowing user access, based on the result -of a license check. To use the LVL, your application <em>must</em> provide an -implementation of Policy. </p> - -<p>The Policy interface declares two methods, <code>allowAccess()</code> and -<code>processServerResponse()</code>, which are called by a LicenseChecker -instance when processing a response from the license server. It also declares an -enum called <code>LicenseResponse</code>, which specifies the license response -value passed in calls to <code>processServerResponse()</code>. </p> - -<ul> -<li><code>processServerResponse()</code> lets you preprocess the raw response -data received from the licensing server, prior to determining whether to grant -access. - -<p>A typical implementation would extract some or all fields from the license -response and store the data locally to a persistent store, such as through -{@link android.content.SharedPreferences} storage, to ensure that the data is -accessible across application invocations and device power cycles. For example, -a Policy would maintain the timestamp of last successful license check, the -retry count, the license validity period, and similar information in a -persistent store, rather than resetting the values each time the application is -launched.</p> - -<p>When storing response data locally, the Policy must ensure that the data is -obfuscated (see <a href="#impl-Obfuscator">Implementing an Obfuscator</a>, -below).</p></li> - -<li><code>allowAccess()</code> determines whether to grant the user access to -your application, based on any available license response data (from the -licensing server or from cache) or other application-specific information. For -example, your implementation of <code>allowAccess()</code> could take into -account additional criteria, such as usage or other data retrieved from a -backend server. In all cases, an implementation of <code>allowAccess()</code> -should only return <code>true</code> if the user is licensed to use the -application, as determined by the licensing server, or if there is a transient -network or system problem that prevents the license check from completing. In -such cases, your implementation can maintain a count of retry responses and -provisionally allow access until the next license check is complete.</li> - -</ul> - -<p>To simplify the process of adding licensing to your application and to -provide an illustration of how a Policy should be designed, the LVL includes -two full Policy implementations that you can use without modification or -adapt to your needs:</p> - -<ul> -<li><a href="#ServerManagedPolicy">ServerManagedPolicy</a>, a flexible Policy -that uses server-provided settings and cached responses to manage access across -varied network conditions, and</li> -<li><a href="#StrictPolicy">StrictPolicy</a>, which does not cache any response -data and allows access <em>only</em> if the server returns a licensed -response.</li> -</ul> - -<p>For most applications, the use of ServerManagedPolicy is highly -recommended. ServerManagedPolicy is the LVL default and is integrated with -the LVL sample application.</p> - - -<h4 id="custom-policies">Guidelines for custom policies</h4> - -<p>In your licensing implementation, you can use one of the complete policies -provided in the LVL (ServerManagedPolicy or StrictPolicy) or you can create a -custom policy. For any type of custom policy, there are several important design -points to understand and account for in your implementation.</p> - -<p>The licensing server applies general request limits to guard against overuse -of resources that could result in denial of service. When an application exceeds -the request limit, the licensing server returns a 503 response, which gets -passed through to your application as a general server error. This means that no -license response will be available to the user until the limit is reset, which -can affect the user for an indefinite period.</p> - -<p>If you are designing a custom policy, we recommend that the Policy: -<ol> -<!-- <li>Limits the number of points at which your app calls for a license check -to the minimum. </li> --> -<li>Caches (and properly obfuscates) the most recent successful license response -in local persistent storage.</li> -<li>Returns the cached response for all license checks, for as long as the -cached response is valid, rather than making a request to the licensing server. -Setting the response validity according to the server-provided <code>VT</code> -extra is highly recommended. See <a href="#extras">Server Response Extras</a> -for more information.</li> -<li>Uses an exponential backoff period, if retrying any requests the result in -errors. Note that the Android Market client automatically retries failed -requests, so in most cases there is no need for your Policy to retry them.</li> -<li>Provides for a "grace period" that allows the user to access your -application for a limited time or number of uses, while a license check is being -retried. The grace period benefits the user by allowing access until the next -license check can be completed successfully and it benefits you by placing a -hard limit on access to your application when there is no valid license response -available.</li> -</ol> - -<p>Designing your Policy according to the guidelines listed above is critical, -because it ensures the best possible experience for users while giving you -effective control over your application even in error conditions. </p> - -<p>Note that any Policy can use settings provided by the licensing server to -help manage validity and caching, retry grace period, and more. Extracting the -server-provided settings is straightforward and making use of them is highly -recommended. See the ServerManagedPolicy implementation for an example of how to -extract and use the extras. For a list of server settings and information about -how to use them, see <a href="#extras">Server Response Extras</a> in the -Appendix of this document.</p> - -<h4 id="ServerManagedPolicy">ServerManagedPolicy</h4> - -<div class="sidebox-wrapper"> -<div class="sidebox"> -<h2>Server Response Extras</h2> - -<p>For certain types of licensing responses, the licensing server appends extra -settings to the responses, to help the application manage licensing effectively. -</p> - -<p style="margin-top:.5em;">See <a href="#extras">Server Response Extras</a> for -a list of settings and <code>ServerManagedPolicy.java</code> for information -about how a Policy can use the extras.</p> - -</div> -</div> - -<p>The LVL includes a full and recommended implementation of the Policy -interface called ServerManagedPolicy. The implementation is integrated with the -LVL classes and serves as the default Policy in the library. </p> - -<p>ServerManagedPolicy provides all of the handling for license and retry -responses. It caches all of the response data locally in a -{@link android.content.SharedPreferences} file, obfuscating it with the -application's Obfuscator implementation. This ensures that the license response -data is secure and persists across device power cycles. ServerManagedPolicy -provides concrete implementations of the interface methods -<code>processServerResponse()</code> and <code>allowAccess()</code> and also -includes a set of supporting methods and types for managing license -responses.</p> - -<p>Importantly, a key feature of ServerMangedPolicy is its use of -server-provided settings as the basis for managing licensing across an -application's refund period and through varying network and error conditions. -When an application contacts the Android Market server for a license check, the -server appends several settings as key-value pairs in the extras field of certain -license response types. For example, the server provides recommended values for the -application's license validity period, retry grace period, and maximum allowable -retry count, among others. ServerManagedPolicy extracts the values from the -license response in its <code>processServerResponse()</code> method and checks -them in its <code>allowAccess()</code> method. For a list of the server-provided -settings used by ServerManagedPolicy, see <a href="#extras">Server Response -Extras</a> in the Appendix of this document.</p> - -<p>For convenience, best performance, and the benefit of using license settings -from the Android Market server, <strong>using ServerManagedPolicy as your -licensing Policy is strongly recommended</strong>. </p> - -<p>If you are concerned about the security of license response data that is -stored locally in SharedPreferences, you can use a stronger obfuscation -algorithm or design a stricter Policy that does not store license data. The LVL -includes an example of such a Policy — see <a -href="#StrictPolicy">StrictPolicy</a> for more information.</p> - -<p>To use ServerManagedPolicy, simply import it to your Activity, create an -instance, and pass a reference to the instance when constructing your -LicenseChecker. See <a href="#lc-lcc">Instantiate LicenseChecker and -LicenseCheckerCallback</a> for more information. </p> - -<h4 id="StrictPolicy">StrictPolicy</h4> - -<p>The LVL includes an alternative full implementation of the Policy interface -called StrictPolicy. The StrictPolicy implementation provides a more restrictive -Policy than ServerManagedPolicy, in that it does not allow the user to access -the application unless a license response is received from the server at the -time of access that indicates that the user is licensed.</p> - -<p>The principal feature of StrictPolicy is that it does not store <em>any</em> -license response data locally, in a persistent store. Because no data is stored, -retry requests are not tracked and cached responses can not be used to fulfill -license checks. The Policy allows access only if:</p> - -<ul> -<li>The license response is received from the licensing server, and </li> -<li>The license response indicates that the user is licensed to access the -application. </li> -</ul> - -<p>Using StrictPolicy is appropriate if your primary concern is to ensure that, -in all possible cases, no user will be allowed to access the application unless -the user is confirmed to be licensed at the time of use. Additionally, the -Policy offers slightly more security than ServerManagedPolicy — since -there is no data cached locally, there is no way a malicious user could tamper -with the cached data and obtain access to the application.</p> - -<p>At the same time, this Policy presents a challenge for normal users, since it -means that they won't be able to access the application when there is no network -(cell or wi-fi) connection available. Another side-effect is that your -application will send more license check requests to the server, since using a -cached response is not possible.</p> - -<p>Overall, this policy represents a tradeoff of some degree of user convenience -for absolute security and control over access. Consider the tradeoff carefully -before using this Policy.</p> - -<p>To use StrictPolicy, simply import it to your Activity, create an instance, -and pass a reference to it when constructing your LicenseChecker. See -<a href="#lc-lcc">Instantiate LicenseChecker and LicenseCheckerCallback</a> -for more information. </p> - -<h3 id="impl-Obfuscator">Implementing an Obfuscator</h3> - -<div class="sidebox-wrapper"> -<div class="sidebox"> -<h2>AESObfuscator</h2> - -<p>The LVL includes a full Obfuscator implementation in the -<code>AESObfuscator.java</code> file. The Obfuscator uses AES encryption to -obfuscate/unobfuscate data. If you are using a Policy (such as -ServerManagedPolicy) that caches license response data, using AESObfuscator as -basis for your Obfuscator implementation is highly recommended. </p> - -</div> -</div> - -<p>A typical Policy implementation needs to save the license response data for -an application to a persistent store, so that it is accessible across -application invocations and device power cycles. For example, a Policy would -maintain the timestamp of the last successful license check, the retry count, -the license validity period, and similar information in a persistent store, -rather than resetting the values each time the application is launched. The -default Policy included in the LVL, ServerManagedPolicy, stores license response -data in a {@link android.content.SharedPreferences} instance, to ensure that the -data is persistent. </p> - -<p>Because the Policy will use stored license response data to determine whether -to allow or disallow access to the application, it <em>must</em> ensure that any -stored data is secure and cannot be reused or manipulated by a root user on a -device. Specifically, the Policy must always obfuscate the data before storing -it, using a key that is unique for the application and device. Obfuscating using -a key that is both application-specific and device-specific is critical, because -it prevents the obfuscated data from being shared among applications and -devices.</p> - -<p>The LVL assists the application with storing its license response data in a -secure, persistent manner. First, it provides an Obfuscator -interface that lets your application supply the obfuscation algorithm of its -choice for stored data. Building on that, the LVL provides the helper class -PreferenceObfuscator, which handles most of the work of calling the -application's Obfuscator class and reading and writing the obfuscated data in a -SharedPreferences instance. </p> - -<p>The LVL provides a full Obfuscator implementation called -AESObfuscator that uses AES encryption to obfuscate data. You can -use AESObfuscator in your application without modification or you -can adapt it to your needs. For more information, see the next section.</p> - - -<h4 id="AESObfuscator">AESObfuscator</h4> - -<p>The LVL includes a full and recommended implementation of the Obfuscator -interface called AESObfuscator. The implementation is integrated with the -LVL sample application and serves as the default Obfuscator in the library. </p> - -<p>AESObfuscator provides secure obfuscation of data by using AES to -encrypt and decrypt the data as it is written to or read from storage. -The Obfuscator seeds the encryption using three data fields provided -by the application: </p> - -<ol> -<li>A salt — an array of random bytes to use for each (un)obfuscation. </li> -<li>An application identifier string, typically the package name of the application.</li> -<li>A device identifier string, derived from as many device-specific sources -as possible, so as to make it as unique.</li> -</ol> - -<p>To use AESObfuscator, first import it to your Activity. Declare a private -static final array to hold the salt bytes and initialize it to 20 randomly -generated bytes.</p> - -<pre> ... - // Generate 20 random bytes, and put them here. - private static final byte[] SALT = new byte[] { - -46, 65, 30, -128, -103, -57, 74, -64, 51, 88, -95, - -45, 77, -117, -36, -113, -11, 32, -64, 89 - }; - ... -</pre> - -<p>Next, declare a variable to hold a device identifier and generate a value for -it in any way needed. For example, the sample application included in the LVL -queries the system settings for the -<code>android.Settings.Secure.ANDROID_ID</code>, which is unique to each device. -</p> - -<p>Note that, depending on the APIs you use, your application might need to -request additional permissions in order to acquire device-specific information. -For example, to query the {@link android.telephony.TelephonyManager} to obtain -the device IMEI or related data, the application will also need to request the -<code>android.permission.READ_PHONE_STATE</code> permission in its manifest.</p> - -<p>Before requesting new permissions for the <em>sole purpose</em> of acquiring -device-specific information for use in your Obfuscator, consider -how doing so might affect your application or its filtering on Android Market -(since some permissions can cause the SDK build tools to add -the associated <code><uses-feature></code>).</p> - -<p>Finally, construct an instance of AESObfuscator, passing the salt, -application identifier, and device identifier. You can construct the instance -directly, while constructing your Policy and LicenseChecker. For example:</p> - -<pre> ... - // Construct the LicenseChecker with a Policy. - mChecker = new LicenseChecker( - this, new ServerManagedPolicy(this, - new AESObfuscator(SALT, getPackageName(), deviceId)), - BASE64_PUBLIC_KEY // Your public licensing key. - ); - ... -</pre> - -<p>For a complete example, see MainActivity in the LVL sample application.</p> - - -<h3 id="impl-lc">Checking the license from your application's main Activity</h3> - -<p>Once you've implemented a Policy for managing access to your application, the -next step is to add a license check to your application, which initiates a query -to the licensing server if needed and manages access to the application based on -the license response. All of the work of adding the license check and handling -the response takes place in your main {@link android.app.Activity} source file. -</p> - -<p>To add the license check and handle the response, you must:</p> - -<ol> - <li><a href="#imports">Add imports</a></li> - <li><a href="#lc-impl">Implement LicenseCheckerCallback</a> as a private inner class</li> - <li><a href="#thread-handler">Create a Handler</a> for posting from LicenseCheckerCallback to the UI thread</li> - <li><a href="#lc-lcc">Instantiate LicenseChecker</a> and LicenseCheckerCallback</li> - <li><a href="#check-access">Call checkAccess()</a> to initiate the license check</li> - <li><a href="#account-key">Embed your public key</a> for licensing</li> - <li><a href="#handler-cleanup">Call your LicenseChecker's onDestroy() method</a> to close IPC connections.</li> -</ol> - -<p>The sections below describe these tasks. </p> - -<h4 id="lc-overview">Overview of license check and response</h4> - -<div class="sidebox-wrapper"> -<div class="sidebox"> -<h2>Example: MainActivity</h2> - -<p>The sample application included with the LVL provides a full example of how -to initiate a license check and handle the result, in the -<code>MainActivity.java</code> file.</p> - -</div> -</div> - -<p>In most cases, you should add the license check to your application's main -{@link android.app.Activity}, in the <code>onCreate()</code> method. This -ensures that when the user launches your application directly, the license check -will be invoked immediately. In some cases, you can add license checks in other -locations as well. For example, if your application includes multiple Activity -components that other applications can start by {@link android.content.Intent}, -you could add license checks in those Activities.</p> - -<p>A license check consists of two main actions: </p> - -<ul> -<li>A call to a method to initiate the license check — in the LVL, this is -a call to the <code>checkAccess()</code> method of a LicenseChecker object that -you construct.</li> -<li>A callback that returns the result of the license check. In the LVL, this is -a <code>LicenseCheckerCallback</code> interface that you implement. The -interface declares two methods, <code>allow()</code> and -<code>dontAllow()</code>, which are invoked by the library based on to the -result of the license check. You implement those two methods with whatever logic -you need, to allow or disallow the user access to your application. Note that -these methods do not determine <em>whether</em> to allow access — that -determination is the responsibility of your Policy implementation. Rather, these -methods simply provide the application behaviors for <em>how</em> to allow and -disallow access (and handle application errors).</li> -</ul> - -<div style="margin-bottom:2em;"> - -<img src="{@docRoot}images/licensing_flow.png" style="text-align:left;margin-bottom:0;margin-left:3em;" /> -<div style="margin:.5em 0 1.5em 2em;padding:0"><strong>Figure 6.</strong> Overview of a -typical license check interaction.</div> -</div> - -<p>The diagram above illustrates how a typical license check takes place: </p> - -<ol> -<li>Code in the application's main Activity instantiates LicenseCheckerCallback -and LicenseChecker objects. When constructing LicenseChecker, the code passes in -{@link android.content.Context}, a Policy implementation to use, and the -publisher account's public key for licensing as parameters. </li> -<li>The code then calls the <code>checkAccess()</code> method on the -LicenseChecker object. The method implementation calls the Policy to determine -whether there is a valid license response cached locally, in -{@link android.content.SharedPreferences}. -<ul> -<li>If so, the <code>checkAccess()</code> implementation calls -<code>allow()</code>.</li> -<li>Otherwise, the LicenseChecker initiates a license check request that is sent -to the licensing server.</li> -</ul> -<p class="note"><strong>Note:</strong> The licensing server always returns -<code>LICENSED</code> when you perform a license check of a draft application.</p> -</li> -<li>When a response is received, LicenseChecker creates a LicenseValidator that -verifies the signed license data and extracts the fields of the response, then -passes them to your Policy for further evaluation. - <ul> - <li>If the license is valid, the Policy caches the response in -SharedPreferences and notifies the validator, which then calls the -<code>allow()</code> method on the LicenseCheckerCallback object. </li> - <li>If the license not valid, the Policy notifies the validator, which calls -the <code>dontAllow()</code> method on LicenseCheckerCallback. </li> - </ul> -</li> -<li>In case of a recoverable local or server error, such as when the network is -not available to send the request, LicenseChecker passes a RETRY response to -your Policy's <code>processServerResponse()</code> method. </li> -<li>In case of a application error, such as when the application attempts to -check the license of an invalid package name, LicenseChecker passes an error -response to the LicenseCheckerCallback's <code>applicationError()</code> -method. </li> -</ol> - -<p>Note that, in addition to initiating the license check and handling the -result, which are described in the sections below, your application also needs -to provide a <a href="#impl-Policy">Policy implementation</a> and, if the Policy -stores response data (such as ServerManagedPolicy), an <a -href="#impl-Obfuscator">Obfuscator</a> implementation. </p> - - -<h4 id="imports">Add imports</h4> - -<p>First, open the class file of the application's main Activity and import -LicenseChecker and LicenseCheckerCallback from the LVL package.</p> - -<pre> import com.android.vending.licensing.LicenseChecker; - import com.android.vending.licensing.LicenseCheckerCallback;</pre> - -<p>If you are using the default Policy implementation provided with the LVL, -ServerManagedPolicy, import it also, together with the AESObfuscator. If you are -using a custom Policy or Obfuscator, import those instead. </p> - -<pre> import com.android.vending.licensing.ServerManagedPolicy; - import com.android.vending.licensing.AESObfuscator;</pre> - -<h4 id="lc-impl">Implement LicenseCheckerCallback as a private inner class</h4> - -<p>LicenseCheckerCallback is an interface provided by the LVL for handling -result of a license check. To support licensing using the LVL, you must -implement LicenseCheckerCallback and -its methods to allow or disallow access to the application.</p> - -<p>The result of a license check is always a call to one of the -LicenseCheckerCallback methods, made based on the validation of the response -payload, the server response code itself, and any additional processing provided -by your Policy. Your application can implement the methods in any way needed. In -general, it's best to keep the methods simple, limiting them to managing UI -state and application access. If you want to add further processing of license -responses, such as by contacting a backend server or applying custom constraints, -you should consider incorporating that code into your Policy, rather than -putting it in the LicenseCheckerCallback methods. </p> - -<p>In most cases, you should declare your implementation of -LicenseCheckerCallback as a private class inside your application's main -Activity class. </p> - -<p>Implement the <code>allow()</code> and <code>dontAllow()</code> methods as -needed. To start with, you can use simple result-handling behaviors in the -methods, such as displaying the license result in a dialog. This helps you get -your application running sooner and can assist with debugging. Later, after you -have determined the exact behaviors you want, you can add more complex handling. -</p> - -<p>Some suggestions for handling unlicensed responses in -<code>dontAllow()</code> include: </p> - -<ul> -<li>Display a "Try again" dialog to the user, including a button to initiate a -new license check. </li> -<li>Display a "Purchase this application" dialog, including a button that -deep-links the user to the application's details page on Market, from which the -use can purchase the application. For more information on how to set up such -links, see <a -href="{@docRoot}guide/publishing/publishing.html#marketintent">Using Intents to -Launch the Market Application on a Device</a>. </li> -<li>Display a Toast notification that indicates that the features of the -application are limited because it is not licensed. </li> -</ul> - -<p>The example below shows how the LVL sample application implements -LicenseCheckerCallback, with methods that display the license check result in a -dialog. </p> - -<pre> private class MyLicenseCheckerCallback implements LicenseCheckerCallback { - public void allow() { - if (isFinishing()) { - // Don't update UI if Activity is finishing. - return; - } - // Should allow user access. - displayResult(getString(R.string.allow)); - } - - public void dontAllow() { - if (isFinishing()) { - // Don't update UI if Activity is finishing. - return; - } - displayResult(getString(R.string.dont_allow)); - // Should not allow access. An app can handle as needed, - // typically by informing the user that the app is not licensed - // and then shutting down the app or limiting the user to a - // restricted set of features. - // In this example, we show a dialog that takes the user to Market. - showDialog(0); - } - } -</pre> - -<p>Additionally, you should implement the <code>applicationError()</code> -method, which the LVL calls to let your application handle errors that are not -retryable. For a list of such errors, see <a -href="#server-response-codes">Server Response Codes</a> in the Appendix of this -document. You can implement the method in any way needed. In most cases, the -method should log the error code and call <code>dontAllow()</code>.</p> - -<h4 id="thread-handler">Create a Handler for posting from LicenseCheckerCallback -to the UI thread</h4> - -<p>During a license check, the LVL passes the request to the Android Market -application, which handles communication with the licensing server. The LVL -passes the request over asynchronous IPC (using {@link android.os.Binder}) so -the actual processing and network communication do not take place on a thread -managed by your application. Similarly, when the Android Market application -receives the result, it invokes a callback method over IPC, which in turn -executes in an IPC thread pool in your application's process.</p> - -<p>The LicenseChecker class manages your application's IPC communication with -the Android Market application, including the call that sends the request and -the callback that receives the response. LicenseChecker also tracks open license -requests and manages their timeouts. </p> - -<p>So that it can handle timeouts properly and also process incoming responses -without affecting your application's UI thread, LicenseChecker spawns a -background thread at instantiation. In the thread it does all processing of -license check results, whether the result is a response received from the server -or a timeout error. At the conclusion of processing, the LVL calls your -LicenseCheckerCallback methods from the background thread. </p> - -<p>To your application, this means that:</p> - -<ol> -<li>Your LicenseCheckerCallback methods will be invoked, in many cases, from a -background thread.</li> -<li>Those methods won't be able to update state or invoke any processing in the -UI thread, unless you create a Handler in the UI thread and have your callback -methods post to the Handler.</li> -</ol> - -<p>If you want your LicenseCheckerCallback methods to update the UI thread, -instantiate a {@link android.os.Handler} in the main Activity's -{@link android.app.Activity#onCreate(android.os.Bundle) onCreate()} method, -as shown below. In this example, the LVL sample application's -LicenseCheckerCallback methods (see above) call <code>displayResult()</code> to -update the UI thread through the Handler's -{@link android.os.Handler#post(java.lang.Runnable) post()} method.</p> - -<pre>private Handler mHandler; - - @Override - public void onCreate(Bundle savedInstanceState) { - ... - mHandler = new Handler(); - } -</pre> - -<p>Then, in your LicenseCheckerCallback methods, you can use Handler methods to -post Runnable or Message objects to the Handler. Here's how the sample -application included in the LVL posts a Runnable to a Handler in the UI thread -to display the license status.</p> - -<pre> private void displayResult(final String result) { - mHandler.post(new Runnable() { - public void run() { - mStatusText.setText(result); - setProgressBarIndeterminateVisibility(false); - mCheckLicenseButton.setEnabled(true); - } - }); - } -</pre> - -<h4 id="lc-lcc">Instantiate LicenseChecker and LicenseCheckerCallback</h4> - -<p>In the main Activity's -{@link android.app.Activity#onCreate(android.os.Bundle) onCreate()} method, -create private instances of LicenseCheckerCallback and LicenseChecker. You must -instantiate LicenseCheckerCallback first, because you need to pass a reference -to that instance when you call the contructor for LicenseChecker. </p> - -<p>When you instantiate LicenseChecker, you need to pass in these parameters:</p> - -<ul> -<li>The application {@link android.content.Context}</li> -<li>A reference to the Policy implementation to use for the license check. In -most cases, you would use the default Policy implementation provided by the LVL, -ServerManagedPolicy. </li> -<li>The String variable holding your publisher account's public key for -licensing. </li> -</ul> - -<p>If you are using ServerManagedPolicy, you won't need to access the class -directly, so you can instantiate it in the LicenseChecker constructor, -as shown in the example below. Note that you need to pass a reference to a new -Obfuscator instance when you construct ServerManagedPolicy.</p> - -<p>The example below shows the instantiation of LicenseChecker and -LicenseCheckerCallback from the <code>onCreate()</code> method of an Activity -class. </p> - -<pre>public class MainActivity extends Activity { - ... - private LicenseCheckerCallback mLicenseCheckerCallback; - private LicenseChecker mChecker; - - @Override - public void onCreate(Bundle savedInstanceState) { - super.onCreate(savedInstanceState); - ... - // Construct the LicenseCheckerCallback. The library calls this when done. - mLicenseCheckerCallback = new MyLicenseCheckerCallback(); - - // Construct the LicenseChecker with a Policy. - mChecker = new LicenseChecker( - this, new ServerManagedPolicy(this, - new AESObfuscator(SALT, getPackageName(), deviceId)), - BASE64_PUBLIC_KEY // Your public licensing key. - ); - ... - } -} -</pre> - - -<p>Note that LicenseChecker calls the LicenseCheckerCallback methods from the UI -thread <em>only</em> if there is valid license response cached locally. If the -license check is sent to the server, the callbacks always originate from the -background thread, even for network errors. </p> - - -<h4 id="check-access">Call checkAccess() to initiate the license check</h4> - -<p>In your main Activity, add a call to the <code>checkAccess()</code> method of the -LicenseChecker instance. In the call, pass a reference to your -LicenseCheckerCallback instance as a parameter. If you need to handle any -special UI effects or state management before the call, you might find it useful -to call <code>checkAccess()</code> from a wrapper method. For example, the LVL -sample application calls <code>checkAccess()</code> from a -<code>doCheck()</code> wrapper method:</p> - -<pre> @Override - public void onCreate(Bundle savedInstanceState) { - super.onCreate(savedInstanceState); - ... - // Call a wrapper method that initiates the license check - doCheck(); - ... - } - ... - private void doCheck() { - mCheckLicenseButton.setEnabled(false); - setProgressBarIndeterminateVisibility(true); - mStatusText.setText(R.string.checking_license); - mChecker.checkAccess(mLicenseCheckerCallback); - } -</pre> - - -<h4 id="account-key">Embed your public key for licensing</h4> - -<p>For each publisher account, the Android Market service automatically -generates a 2048-bit RSA public/private key pair that is used exclusively for -licensing. The key pair is uniquely associated with the publisher account and is -shared across all applications that are published through the account. Although -associated with a publisher account, the key pair is <em>not</em> the same as -the key that you use to sign your applications (or derived from it).</p> - -<p>The Android Market publisher site exposes the public key for licensing to any -developer signed in to the publisher account, but it keeps the private key -hidden from all users in a secure location. When an application requests a -license check for an application published in your account, the licensing server -signs the license response using the private key of your account's key pair. -When the LVL receives the response, it uses the public key provided by the -application to verify the signature of the license response. </p> - -<p>To add licensing to an application, you must obtain your publisher account's -public key for licensing and copy it into your application. Here's how to find -your account's public key for licensing:</p> - -<ol> -<li>Go to the Android Market <a -href="http://market.android.com/publish">publisher site</a> and sign in. -Make sure that you sign in to the account from which the application you are -licensing is published (or will be published). </li> -<li>In the account home page, locate the "Edit profile" link and click it. </li> -<li>In the Edit Profile page, locate the "Licensing" pane, shown below. Your -public key for licensing is given in the "Public key" text box. </li> -</ol> - -<p>To add the public key to your application, simply copy/paste the key string -from the text box into your application as the value of the String variable -<code>BASE64_PUBLIC_KEY</code>. When you are copying, make sure that you have -selected the entire key string, without omitting any characters. </p> - -<p>Here's an example from the LVL sample application:</p> - -<pre> public class MainActivity extends Activity { - private static final String BASE64_PUBLIC_KEY = "MIIBIjANBgkqhkiG ... "; //truncated for this example - ... - } -</pre> - -<h4 id="handler-cleanup">Call your LicenseChecker's onDestroy() method -to close IPC connections</h4> - -<p>Finally, to let the LVL clean up before your application -{@link android.content.Context} changes, add a call to the LicenseChecker's -<code>onDestroy()</code> method from your Activity's -{@link android.app.Activity#onDestroy()} implementation. The call causes the -LicenseChecker to properly close any open IPC connection to the Android Market -application's ILicensingService and removes any local references to the service -and handler.</p> - -<p>Failing to call the LicenseChecker's <code>onDestroy()</code> method -can lead to problems over the lifecycle of your application. For example, if the -user changes screen orientation while a license check is active, the application -{@link android.content.Context} is destroyed. If your application does not -properly close the LicenseChecker's IPC connection, your application will crash -when the response is received. Similarly, if the user exits your application -while a license check is in progress, your application will crash when the -response is received, unless it has properly called the -LicenseChecker's <code>onDestroy()</code> method to disconnect from the service. -</p> - -<p>Here's an example from the sample application included in the LVL, where -<code>mChecker</code> is the LicenseChecker instance:</p> - -<pre> @Override - protected void onDestroy() { - super.onDestroy(); - mChecker.onDestroy(); - ... - } -</pre> - -<p>If you are extending or modifying LicenseChecker, you might also need to call -the LicenseChecker's <code>finishCheck()</code> method, to clean up any open IPC -connections.</p> - -<h3 id="impl-DeviceLimiter">Implementing a DeviceLimiter</h3> - -<p>In some cases, you might want your Policy to limit the number of actual -devices that are permitted to use a single license. This would prevent a user -from moving a licensed application onto a number of devices and using the -application on those devices under the same account ID. It would also prevent a -user from "sharing" the application by providing the account information -associated with the license to other individuals, who could then sign in to that -account on their devices and access the license to the application. </p> - -<p>The LVL supports per-device licensing by providing a -<code>DeviceLimiter</code> interface, which declares a single method, -<code>allowDeviceAccess()</code>. When a LicenseValidator is handling a response -from the licensing server, it calls <code>allowDeviceAccess()</code>, passing a -user ID string extracted from the response.</p> - -<p>If you do not want to support device limitation, <strong>no work is -required</strong> — the LicenseChecker class automatically uses a default -implementation called NullDeviceLimiter. As the name suggests, NullDeviceLimiter -is a "no-op" class whose <code>allowDeviceAccess()</code> method simply returns -a <code>LICENSED</code> response for all users and devices. </p> - -<div style="border-left:4px solid #FFCF00;margin:1em;padding: 0 0 0 .5em"> -<p><strong>Caution:</strong> Per-device licensing is <em>not recommended for -most applications</em> because:</p> -<ul> -<li>It requires that you provide a backend server to manage a users and devices -mapping, and </li> -<li>It could inadvertently result in a user being denied access to an -application that they have legitimately purchased on another device.</li> -</ul> -</div> - - -<h2 id="test-env">Setting Up the Testing Environment</h2> - -<p>The Android Market publisher site provides configuration tools that let you -and others test licensing on your application before it is published. As you are -implementing licensing, you can make use of the publisher site tools to test -your application's Policy and handling of different licensing responses and -error conditions.</p> - -<p>The main components of the test environment for licensing include: </p> - -<ul> -<li>A "Test response" configuration in your publisher account that lets you -set the static licensing response returned, when the server processes a -license check for an application uploaded to the publisher account, from a user -signed in to the publisher account or a test account.</li> -<li>An optional set of test accounts that will receive the static test -response when they check the license of an application that you have uploaded -(regardless whether the application is published or not).</li> -<li>A runtime environment for the application that includes the Android Market -application or Google APIs Add-On, on which the user is signed in to the -publisher account or one of the test accounts.</li> -</ul> - -<p>Setting up the test environment properly involves:</p> - -<ol> -<li><a href="#test-response">Setting static test responses</a> that are returned by the licensing server.</li> -<li><a href="#test-acct-setup">Setting up test accounts</a> as needed.</li> -<li><a href="#acct-signin">Signing in</a> properly to an emulator or device, before initiating a license check test.</li> -</ol> - -<p>The sections below provide more information.</p> - - -<h3 id="test-response">Setting test responses for license checks</h3> - -<p>Android Market provides a configuration setting in your publisher account -that lets you override the normal processing of a license check and return a -specified static response code. The setting is for testing only and applies -<em>only</em> to license checks for applications that you have uploaded, made by -any user signed in to an emulator or device using the credentials of the -publisher account or a registered test account. For other users, the server -always processes license checks according to normal rules. </p> - -<p>To set a test response for your account, sign in to your publisher account -and click "Edit Profile". In the Edit Profile page, locate the Test Response -menu in the Licensing panel, shown below. You can select from the full set of -valid server response codes to control the response or condition you want to -test in your application.</p> - -<p>In general, you should make sure to test your application's licensing -implementation with every response code available in the Test Response menu. -For a description of the codes, see <a href="#server-response-codes">Server -Response Codes</a> in the Appendix of this document.</p> - -<div style="margin-bottom:2em;" id="licensing_test_response"> - -<img src="{@docRoot}images/licensing_test_response.png" style="text-align:left;margin-bottom:0;" /> -<div style="margin:0 2em;padding:0"><strong>Figure 7.</strong> The Licensing -panel of your account's Edit Profile page, showing the Test Accounts field and the -Test Response menu.</div> -</div> - -<p>Note that the test response that you configure applies account-wide — -that is, it applies not to a single application, but to <em>all</em> -applications associated with the publisher account. If you are testing multiple -applications at once, changing the test response will affect all of those -applications on their next license check (if the user is signed into -the emulator or device using the publisher account or a test account).</p> - -<p>Before you can successfully receive a test response for a license check, -you must sign in to the device or emulator on which the application -is installed, and from which it is querying the server. Specifically, you must -sign using either your publisher account or one of the test accounts that you -have set up. For more information about test accounts, see the next section.</p> - -<p>See <a href="#server-response-codes">Server Response Codes</a> for a list of -test responses available and their meanings. </p> - - -<h3 id="test-acct-setup">Setting up test accounts</h3> - -<p>In some cases, you might want to let multiple teams of developers test -licensing on applications that will ultimately be published through your -publisher account, but without giving them access to your publisher account's -sign-in credentials. To meet that need, the Android Market publisher site lets -you set up one or more optional <em>test accounts</em> — accounts that are -authorized to query the licensing server and receive static test responses from -your publisher account.</p> - -<p>Test accounts are standard Google accounts that you register on your -publisher account, such that they will receive the test response for -applications that you have uploaded. Developers can then sign in to their -devices or emulators using the test account credentials and initiate license -checks from installed applications. When the licensing server receives a license -check from a user of a test account, it returns the static test response -configured for the publisher account. </p> - -<p>Necessarily, there are limitations on the access and permissions given to -users signed in through test accounts, including:</p> - -<ul> -<li>Test account users can query the licensing server only for applications that -are already uploaded to the publisher account. </li> -<li>Test account users do not have permission to upload applications to your -publisher account.</li> -<li>Test account users do not have permission to set the publisher account's -static test response.</li> -</ul> - -<p>The table below summarizes the differences in capabilities, between the -publisher account, a test account, and any other account.</p> - -<p class="table-caption" id="acct-types-table"><strong>Table 1.</strong> -Differences in account types for testing licensing.</p> - -<table> -<tr> -<th>Account Type</th> -<th>Can check license before upload?</th> -<th>Can receive test response?</th> -<th>Can set test response?</th> -</tr> - -<tr> -<td>Publisher account</td> -<td>Yes</td> -<td>Yes</td> -<td>Yes</td> -</tr> - -<tr> -<td>Test account</td> -<td>No</td> -<td>Yes</td> -<td>No</td> -</tr> - -<tr> -<td>Other</td> -<td>No</td> -<td>No</td> -<td>No</td> -</tr> -</table> - -<h4 id="reg-test-acct">Registering test accounts on the publisher account</h4> - -<p>To get started, you need to register each test account in your publisher -account. As shown in <a href="#licensing_test_response">Figure 7</a>, above, you -register test accounts in the Licensing panel of your publisher account's Edit -Profile page. Simply enter the accounts as a comma-delimited list and click -<strong>Save</strong> to save your profile changes.</p> - -<p>You can use any Google account as a test account. If you want to own and -control the test accounts, you can create the accounts yourself and distribute -the credentials to your developers or testers.</p> - -<h4 id="test-app-upload">Handling application upload and distribution for test -account users</h4> - -<p>As mentioned above, users of test accounts can only receive static test -responses for applications that are uploaded to the publisher account. Since -those users do not have permission to upload applications, as the publisher you -will need to work with those users to collect apps for upload and distribute -uploaded apps for testing. You can handle collection and distribution in any way -that is convenient. </p> - -<p>Once an application is uploaded and becomes known to the licensing server, -developers and testers can continue modify the application in their local -development environment, without having to upload new versions. You only need to -upload a new version if the local application increments the -<code>versionCode</code> attribute in the manifest file. </p> - -<h4 id="test-key">Distributing your public key to test account users</h4> - -<p>The licensing server handles static test responses in the normal way, -including signing the license response data, adding extras parameters, and so -on. To support developers who are implementing licensing using test accounts, -rather than the publisher account, you will need to distribute -your public key to them. Developers without access to the publisher site do not -have access to your public key, and without the key they won't be able to -verify license responses. </p> - -<p>Note that if you decide to generate a new licensing key pair for your account -for some reason, you need to notify all users of test accounts. For -testers, you can embed the new key in the application package and distribute it -to users. For developers, you will need to distribute the new key to them -directly. </p> - - -<h3 id="acct-signin">Signing in to an authorized account in the runtime -environment</h3> - -<p>The licensing service is designed to determine whether a given user is -licensed to use a given application — during a license check, the Android -Market application gathers the user ID from the primary account on the system -and sends it to the server, together with the package name of the application -and other information. However, if there is no user information available, the -license check cannot succeed, so the Android Market application terminates the -request and returns an error to the application. </p> - -<p>During testing, to ensure that your application can successfully query the -licensing server, you must make sure that you sign in to an account <em>on the -device or emulator</em> using:</p> - -<ul> -<li>The credentials of a publisher account, or</li> -<li>The credentials of a test account that is registered with a publisher -account</li> -</ul> - - -<div class="sidebox-wrapper"> -<div class="sidebox"> -<h2>Signing in to a Google account on an emulator</h2> - -<p>If you are testing licensing on an emulator, you need to sign in to a Google -account on the emulator. If you do not see an option to create a new Google -account, the problem might be that your AVD is running a standard Android system -image, rather than the Google APIs Add-On, API 8 (release 2) or higher. </p> - -<p style="margin-top:.5em;">For more information, see <a -href="#runtime-setup">Setting up the runtime environment</a>, above.</p> - -</div> -</div> - -<p>Signing in using a publisher account offers the advantage of letting your -applications receive static test responses even before the applications are -uploaded to the publisher site.</p> - -<p>If you are part of a larger organization or are working with external groups -on applications that will be published through your site, you will more likely -want to distribute test accounts instead, then use those to sign in during -testing. </p> - -<p>To sign in on a device or emulator, follow the steps below. The preferred -approach is to sign in as the primary account — however, if there are -other accounts already in use on the device or emulator, you can create an -additional account and sign in to it using the publisher or test account -credentials. </p> - -<ol> -<li>Open Settings > Accounts & sync</li> -<li>Select <strong>Add Account</strong> and choose to add a "Google" account. -</li> -<li>Select <strong>Next</strong> and then <strong>Sign in</strong>.</li> -<li>Enter the username and password of either the publisher account or a test -account that is registered in the publisher account.</li> -<li>Select <strong>Sign in</strong>. The system signs you in to the new -account.</li> -</ol> - -<p>Once you are signed in, you can begin testing licensing in your application -(if you have completed the LVL integration steps above). When your application -initiates a license check, it will receive a response containing the static test -response configured on the publisher account. </p> - -<p>Note that, if you are using an emulator, you will need to sign in to the -publisher account or test account each time you wipe data when restarting the -emulator.</p> - -<div style="margin:2em 1em 1em 1em;"> - -<img src="{@docRoot}images/licensing_device_signin.png" style="text-align:left;" /> -<div style="margin:.25em 1.25em;padding:0"><strong>Figure 8.</strong> Example of -setting up a Google account on a device or emulator.</div> -</div> - -<h2 id="app-obfuscation">Obfuscating Your Application</h2> - -<p>To ensure the security of your application, particularly for a paid -application that uses licensing and/or custom constraints and protections, it's -very important to obfuscate your application code. Properly obfuscating your -code makes it more difficult for a malicious user to decompile the application's -bytecode, modify it — such as by removing the license check — -and then recompile it.</p> - -<p>Several obfuscator programs are available for Android applications, including -<a href="http://proguard.sourceforge.net/">ProGuard</a>, which also offers -code-optimization features. The use of ProGuard or a similar program to obfuscate -your code is <em>strongly recommended</em> for all applications that use Android -Market Licensing. </p> - -<h2 id="app-publishing">Publishing a Licensed Application</h2> - -<p>When you are finished testing your license implementation, you are ready to -publish the application on Android Market. Follow the normal steps to <a -href="{@docRoot}guide/publishing/preparing.html">prepare</a>, <a -href="{@docRoot}guide/publishing/app-signing.html">sign</a>, and then <a -href="{@docRoot}guide/publishing/publishing.html">publish the application</a>. -</p> - -<h4>Removing Copy Protection</h4> - -<p>After uploading your licensed application, remember to remove copy protection -from the application, if it is currently used. To check and remove copy -protection, sign in to the publisher site and go the application's upload -details page. In the Publishing options section, make sure that the Copy -Protection radio button selection is "Off".</p> - -<h4>Considerations for Free Apps</h4> - -<p>Licensing is currently supported only for paid applications. If you already -published your application as free, you won't be able to upload an updated -version that includes licensing (that is, an application that uses the same -package name and that includes the <a href="#manifest-permission">licensing -permission</a>). Here are some points to keep in mind:</p> - -<ul> -<li>If you want to offer a free version of your application that provides a -reduced feature set (or that offers the full feature set for trial period), the -free version of your application must not include the licensing permission and -must use a different package name than the paid version of the app.</li> -<li>If you want to offer a paid version of your free application that uses -licensing, you can do so under a new package name.</li> -</ul> - -<h2 id="support">Where to Get Support</h2> - -<p>If you have questions or encounter problems while implementing or deploying -publishing in your applications, please use the support resources listed in the -table below. By directing your queries to the correct forum, you can get the -support you need more quickly. </p> - -<p class="table-caption"><strong>Table 2.</strong> Developer support resources -for Android Market Licensing Service.</p> - -<table> - -<tr> -<th>Support Type</th> -<th>Resource</th> -<th>Range of Topics</th> -</tr> -<tr> -<td rowspan="2">Development and testing issues</td> -<td>Google Groups: <a -href="http://groups.google.com/group/android-developers">android-developers</a> -</td> -<td rowspan="2">LVL download and integration, library projects, Policy -questions, user experience ideas, handling of responses, Obfuscator, IPC, test -environment setup</td> -</tr> -<tr> -<td>Stack Overflow: <a -href="http://stackoverflow.com/questions/tagged/android">http://stackoverflow.com/questions/tagged/android</a></td> -</tr> -<tr> -<td rowspan="2">Accounts, publishing, and deployment issues</td> -<td><a href="http://www.google.com/support/forum/p/Android+Market">Android -Market Help Forum</a></td> -<td rowspan="2">Publisher accounts, licensing key pair, test accounts, server -responses, test responses, application deployment and results</td> -</tr> -<tr> -<td><a -href="http://market.android.com/support/bin/answer.py?answer=186113">Market -Licensing Support FAQ</a></td> -</tr> -<tr> -<td>LVL issue tracker</td> -<td><a href="http://code.google.com/p/marketlicensing/issues/">Marketlicensing -project issue tracker</a></td> -<td>Bug and issue reports related specifically to the LVL source code classes -and interface implementations</td> -</tr> - -</table> - -<p>For general information about how to post to the groups listed above, see <a -href="{@docRoot}resources/community-groups.html">Developer Forums</a> document -in the Resources tab.</p> - -<h2 id="lvl-summary">Summary of LVL Classes and Interfaces</h2> - -<p>The table below lists all of the source files in the License Verification -Library (LVL) available through the Android SDK. All of the files are part of -the <code>com.android.vending.licensing</code> package.</p> - -<p class="table-caption"><strong>Table A-1.</strong> Summary of LVL library -classes and interfaces.</p> - -<div style="width:99%"> -<table width="100%"> - -<tr> -<th width="15%">Category</th> -<th width="20%">Name</th> -<th width="100%">Description</th> -</tr> - -<tr> -<td rowspan="2">License check and result</td> -<td>LicenseChecker</td> -<td>Class that you instantiate (or subclass) to initiate a license check.</td> -</tr> -<tr> -<td><em>LicenseCheckerCallback</em></td> -<td>Interface that you implement to handle result of the license check.</td> -</tr> - -<tr> -<td rowspan="3" width="15%">Policy</td> -<td width="20%"><em>Policy</em></td> -<td width="100%">Interface that you implement to determine whether to allow -access to the application, based on the license response. </td> -</tr> -<tr> -<td>ServerManagedPolicy</td> -<td width="100%">Default Policy implementation. Uses settings provided by the -licensing server to manage local storage of license data, license validity, -retry.</td> -</tr> -<tr> -<td>StrictPolicy</td> -<td>Alternative Policy implementation. Enforces licensing based on a direct -license response from the server only. No caching or request retry.</td> -</tr> - -<tr> -<td rowspan="2" width="15%">Data obfuscation <br><em>(optional)</em></td> -<td width="20%"><em>Obfuscator</em></td> -<td width="100%">Interface that you implement if you are using a Policy (such as -ServerManagedPolicy) that caches license response data in a persistent store. -Applies an obfuscation algorithm to encode and decode data being written or -read.</td> -</tr> -<tr> -<td>AESObfuscator</td> -<td>Default Obfuscator implementation that uses AES encryption/decryption -algorithm to obfuscate/unobfuscate data.</td> -</tr> - -<tr> -<td rowspan="2" width="15%">Device limitation<br><em>(optional)</em></td> -<td width="20%"><em>DeviceLimiter</em></td> -<td width="100%">Interface that you implement if you want to restrict use of an -application to a specific device. Called from LicenseValidator. Implementing -DeviceLimiter is not recommended for most applications because it requires a -backend server and may cause the user to lose access to licensed applications, -unless designed with care.</td> -</tr> -<tr> -<td>NullDeviceLimiter</td> -<td>Default DeviceLimiter implementation that is a no-op (allows access to all -devices).</td> -</tr> - -<tr> -<td rowspan="6" width="15%">Library core, no integration needed</td> -<td width="20%">ResponseData</td> -<td width="100%">Class that holds the fields of a license response.</td> -</tr> -<tr> -<td>LicenseValidator</td> -<td>Class that decrypts and verifies a response received from the licensing -server.</td> -</tr> -<tr> -<td>ValidationException</td> -<td>Class that indicates errors that occur when validating the integrity of data -managed by an Obfuscator.</td> -</tr> -<tr> -<td>PreferenceObfuscator</td> -<td>Utility class that writes/reads obfuscated data to the system's -{@link android.content.SharedPreferences} store.</td> -</tr> -<tr> -<td><em>ILicensingService</em></td> -<td>One-way IPC interface over which a license check request is passed to the -Android Market client.</td> -</tr> -<tr> -<td><em>ILicenseResultListener</em></td> -<td>One-way IPC callback implementation over which the application receives an -asynchronous response from the licensing server.</td> -</tr> - -</table> -</div> - - -<h2 id="server-response-codes">Server Response Codes</h2> - -<p>The table below lists all of the license response codes supported by the -licensing server. In general, an application should handle all of these response -codes. By default, the LicenseValidator class in the LVL provides all of the -necessary handling of these response codes for you. </p> - -<p class="table-caption"><strong>Table A-2.</strong> Summary of response codes -returned by the Android Market server in a license response.</p> - -<table> - -<tr> -<th>Response Code</th> -<th>Description</th> -<th>Signed?</th> -<th>Extras</th> -<th>Comments</th> -</tr> -<tr> -<td>LICENSED</td> -<td>The application is licensed to the user. The user has purchased the -application or the application only exists as a draft.</td> -<td>Yes</td> -<td><code>VT</code>, <code>GT</code>, <code>GR</code></td> -<td><em>Allow access according to Policy constraints.</em></td> -</tr> -<tr> -<td>LICENSED_OLD_KEY</td> -<td>The application is licensed to the user, but there is an updated application -version available that is signed with a different key. </td> -<td>Yes </td> -<td><code>VT</code>, <code>GT</code>, <code>GR</code>, <code>UT</code></td> -<td><em>Optionally allow access according to Policy constraints.</em> -<p style="margin-top:.5em;">Can indicate that the key pair used by the installed -application version is invalid or compromised. The application can allow access -if needed or inform the user that an upgrade is available and limit further use -until upgrade.</p> -</td> -</tr> -<tr> -<td>NOT_LICENSED</td> -<td>The application is not licensed to the user.</td> -<td>No</td> -<td></td> -<td><em>Do not allow access.</em></td> -</tr> -<tr> -<td>ERROR_CONTACTING_SERVER</td> -<td>Local error — the Android Market application was not able to reach the -licensing server, possibly because of network availability problems. </td> -<td>No</td> -<td></td> -<td><em>Retry the license check according to Policy retry limits.</em></td> -</tr> -<tr> -<td>ERROR_SERVER_FAILURE</td> -<td>Server error — the server could not load the publisher account's key -pair for licensing.</td> -<td>No</td> -<td></td> -<td><em>Retry the license check according to Policy retry limits.</em> -</td> -</tr> -<tr> -<td>ERROR_INVALID_PACKAGE_NAME</td> -<td>Local error — the application requested a license check for a package -that is not installed on the device. </td> -<td>No </td> -<td></td> -<td><em>Do not retry the license check.</em> -<p style="margin-top:.5em;">Typically caused by a development error.</p> -</td> -</tr> -<tr> -<td>ERROR_NON_MATCHING_UID</td> -<td>Local error — the application requested a license check for a package -whose UID (package, user ID pair) does not match that of the requesting -application. </td> -<td>No </td> -<td></td> -<td><em>Do not retry the license check.</em> -<p style="margin-top:.5em;">Typically caused by a development error.</p> -</td> -</tr> -<tr> -<td>ERROR_NOT_MARKET_MANAGED</td> -<td>Server error — the application (package name) was not recognized by -Android Market. </td> -<td>No</td> -<td></td> -<td><em>Do not retry the license check.</em> -<p style="margin-top:.5em;">Can indicate that the application was not published -through Android Market or that there is an development error in the licensing -implementation.</p> -</td> -</tr> - -</table> - -<p class="note"><strong>Note:</strong> As documented in <a href="#test-env"> -Setting Up The Testing Environment</a>, the response code can be manually -overridden for the application developer and any registered test users via the -Android Market publisher site. -<br/><br/> -Additionally, as noted above, applications that are in draft mode (in other -words, applicaitons that have been uploaded but have <em>never</em> been -published) will return LICENSED for all users, even if not listed as a test -user. Since the application has never been offered for download, it is assumed -that any users running it must have obtained it from an authorized channel for -testing purposes.</p> - -<h2 id="extras">Server Response Extras</h2> - -<p>The licensing server includes several settings in certain types of license -responses, to assist the application and its Policy in managing access to the -application across the 24-hour refund period and other conditions. Specifically, -the server provides recommended values for the application's license validity -period, retry grace period, maximum allowable retry count, and other settings. -The server appends the settings as key-value pairs in the license response -"extras" field. </p> - -<p>Any Policy implementation can extract the extras settings from the license -response and use them as needed. The LVL default Policy implementation, <a -href="#ServerManagedPolicy">ServerManagedPolicy</a>, serves as a working -implementation and an illustration of how to obtain, store, and use the -settings. </p> - -<p class="table-caption"><strong>Table A-3.</strong> Summary of -license-management settings supplied by the Android Market server in a license -response.</p> - -<table> -<tr> -<th>Extra</th><th>Description</th> -</tr> - -<tr> - <td>VT</td> - <td>License validity timestamp. Specifies the date/time at which the current -(cached) license response expires and must be rechecked on the licensing server. - </td> -</tr> -<tr> - <td>GT</td> - <td>Grace period timestamp. Specifies the end of the period during which a -Policy may allow access to the application, even though the response status is -RETRY. <p>The value is managed by the server, however a typical value would be 5 -or more days.</p></td> -</tr> -<tr> - <td>GR</td> - <td>Maximum retries count. Specifies how many consecutive RETRY license checks -the Policy should allow, before denying the user access to the application. -<p>The value is managed by the server, however a typical value would be "10" or -higher.</p></td> -</tr> -<tr> - <td>UT</td> - <td>Update timestamp. Specifies the day/time when the most recent update to -this application was uploaded and published. <p>The server returns this extra -only for LICENSED_OLD_KEYS responses, to allow the Policy to determine how much -time has elapsed since an update was published with new licensing keys before -denying the user access to the application. </p></td> -</tr> - -</table> - -<p>The sections below provide more information about the server-provided -settings and how to use them. </p> - -<h4>License validity period</h4> - -<p>The Android Market licensing server sets a license validity period for all -downloaded applications. The period expresses the interval of time over which an -application's license status should be considered as unchanging and cacheable by -a licensing Policy in the application. The licensing server includes the -validity period in its response to all license checks, appending an -end-of-validity timestamp to the response as an extra under the key "VT". A -Policy can extract the VT key value and use it to conditionally allow access to -the application without rechecking the license, until the validity period -expires. </p> - -<p>The license validity signals to a licensing Policy when it must recheck the -licensing status with the licensing server. It is <em>not</em> intended to imply -whether an application is actually licensed for use. That is, when an -application's license validity period expires, this does not mean that the -application is no longer licensed for use — rather, it indicates only that -the Policy must recheck the licensing status with the server. It follows that, -as long as the license validity period is not expired, it is acceptable for the -Policy to cache the initial license status locally and return the cached license -status instead of sending a new license check to the server.</p> - -<p>The licensing server manages the validity period as a means of helping the -application properly enforce licensing across the refund period offered by -Android Market for paid applications. It sets the validity period based on -whether the application was purchased and, if so, how long ago. Specifically, -the server sets a validity period as follows:</p> - -<ul> -<li>For a paid application, the server sets the initial license validity period -so that the license response remains valid for as long as the application is -refundable. A licensing Policy in the application may cache the -result of the initial license check and does not need to recheck the license -until the validity period has expired.</li> -<li>When an application is no longer refundable, the server -sets a longer validity period — typically a number of days. </li> -<li>For a free application, the server sets the validity period to a very high -value (<code>long.MAX_VALUE</code>). This ensures that, provided the Policy has -cached the validity timestamp locally, it will not need to recheck the -license status of the application in the future.</li> -</ul> - -<p>The ServerManagedPolicy implementation uses the extracted timestamp -(<code>mValidityTimestamp</code>) as a primary condition for determining whether -to recheck the license status with the server before allowing the user access to -the application. </p> - -<h4>Retry period and maximum retry count</h4> - -<p>In some cases, system or network conditions can prevent an application's -license check from reaching the licensing server, or prevent the server's -response from reaching the Android Market client application. For example, the -user might launch an application when there is no cell network or data -connection available — such as when on an airplane — or when the -network connection is unstable or the cell signal is weak. </p> - -<p>When network problems prevent or interrupt a license check, the Android -Market client notifies the application by returning a "RETRY" response code to -the Policy's <code>processServerResponse()</code> method. In the case of system -problems, such as when the application is unable to bind with Android Market's -ILicensingService implementation, the LicenseChecker library itself calls the -Policy <code>processServerResonse()</code> method with a "RETRY" response code. -</p> - -<p>In general, the RETRY response code is a signal to the application that an -error has occurred that has prevented a license check from completing. - -<p>The Android Market server helps an application to manage licensing under -error conditions by setting a retry "grace period" and a recommended maximum -retries count. The server includes these values in all license check responses, -appending them as extras under the keys "GT" and "GR". </p> - -<p>The application Policy can extract the GT and GR extras and use them to -conditionally allow access to the application, as follows:</p> - -<ul> -<li>For a license check that results in a RETRY response, the Policy should -cache the RETRY response code and increment a count of RETRY responses.</li> -<li>The Policy should allow the user to access the application, provided that -either the retry grace period is still active or the maximum retries count has -not been reached.</li> -</ul> - -<p>The ServerManagedPolicy uses the server-supplied GT and GR values as -described above. The example below shows the conditional handling of the retry -responses in the <code>allow()</code> method. The count of RETRY responses is -maintained in the <code>processServerResponse()</code> method, not shown. </p> - - -<pre> public boolean allowAccess() { - long ts = System.currentTimeMillis(); - if (mLastResponse == LicenseResponse.LICENSED) { - // Check if the LICENSED response occurred within the validity timeout. - if (ts <= mValidityTimestamp) { - // Cached LICENSED response is still valid. - return true; - } - } else if (mLastResponse == LicenseResponse.RETRY && - ts < mLastResponseTime + MILLIS_PER_MINUTE) { - // Only allow access if we are within the retry period or we haven't used up our - // max retries. - return (ts <= mRetryUntil || mRetryCount <= mMaxRetries); - } - return false; - }</pre> - diff --git a/docs/html/guide/publishing/preparing.jd b/docs/html/guide/publishing/preparing.jd index 5ed55fe..fe56352 100644 --- a/docs/html/guide/publishing/preparing.jd +++ b/docs/html/guide/publishing/preparing.jd @@ -22,7 +22,7 @@ page.title=Preparing for Release <ol> <li><a href="{@docRoot}guide/publishing/publishing_overview.html">Publishing Overview</a></li> <li><a href="{@docRoot}guide/publishing/app-signing.html">Signing Your Applications</a></li> - <li><a href="{@docRoot}guide/publishing/publishing.html">Publishing on Android Market</a></li> + <li><a href="{@docRoot}guide/publishing/publishing.html">Publishing on Google Play</a></li> </ol> </div> </div> @@ -39,13 +39,13 @@ similar to the debug build process and can be done using JDK and Android SDK too tasks serve as a final check, ensuring that your application performs as expected under real-world conditions. When you are finished preparing your application for release you have a signed <code>.apk</code> file, which you can distribute directly to users or distribute through an -application marketplace such as Android Market.</p> +application marketplace such as Google Play.</p> <p>This document summarizes the main tasks you need to perform to prepare your application for release. The tasks that are described in this document apply to all Android applications regardless -how they are released or distributed to users. If you are releasing your application through Android -Market, you should also read <a href="{@docRoot}guide/publishing/publishing.html">Publishing on -Android Market</a> to be sure your release-ready application satisfies all Android Market +how they are released or distributed to users. If you are releasing your application through Google +Play, you should also read <a href="{@docRoot}guide/publishing/publishing.html">Publishing on +Google Play</a> to be sure your release-ready application satisfies all Google Play requirements.</p> <p class="note"><strong>Note:</strong> As a best practice, your application should meet all of your @@ -89,9 +89,9 @@ line.</p> <p>To prepare your application for release you typically perform five main tasks (see figure 2). Each main task may include one or more smaller tasks depending on how you are releasing your -application. For example, if you are releasing your application through Android Market you may want +application. For example, if you are releasing your application through Google Play 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 +release. Similarly, to meet Google Play publishing guidelines you may have to prepare screenshots and create promotional text while you are gathering materials for release.</p> <p>You usually perform the tasks listed in figure 2 after you have throroughly debugged and tested @@ -117,11 +117,14 @@ Android system allows you to sign your applications with a self-signed certifica certificate requirements, see <a href="{@docRoot}guide/publishing/app-signing.html#cert">Obtain a suitable private key</a>.</p> +<p class="caution"><strong>Important:</strong> Your application must be signed with a cryptographic +key whose validity period ends after 22 October 2033.</p> + <p>You may also have to obtain other release keys if your application accesses a service or uses a third-party library that requires you to use a key that is based on your private key. For example, if your application uses the <a -href="http://code.google.com/android/add-ons/google-apis/reference/com/google/android/maps/ MapView. -html">MapView</a> class, which is part of the <a +href="http://code.google.com/android/add-ons/google-apis/reference/com/google/android/maps/MapView.html">MapView</a> +class, which is part of the <a href="http://code.google.com/android/add-ons/google-apis/maps-overview.html">Google Maps external library</a>, you will need to register your application with the Google Maps service and obtain a Maps API key. For information about getting a Maps API key, see <a @@ -134,9 +137,9 @@ key</a>.</p> href="{@docRoot}guide/practices/ui_guidelines/icon_design_launcher.html">icon guidelines</a>. Your application's icon helps users identify your application on a device's Home screen and in the Launcher window. It also appears in Manage Applications, My Downloads, and -elsewhere. In addition, publishing services such as Android Market display your icon to users.</p> +elsewhere. In addition, publishing services such as Google Play display your icon to users.</p> -<p class="note"><strong>Note:</strong> If you are releasing your application on Android Market, you +<p class="note"><strong>Note:</strong> If you are releasing your application on Google Play, you need to create a high resolution version of your icon. See <a href="https://www.google.com/support/androidmarket/developer/bin/answer.py?answer=1078870">Graphic @@ -151,7 +154,7 @@ with your application.</p> <h4>Miscellaneous Materials</h4> <p>You might also have to prepare promotional and marketing materials to publicize your application. -For example, if you are releasing your application on Android Market you will need to prepare some +For example, if you are releasing your application on Google Play you will need to prepare some promotional text and you will need to create screenshots of your application. For more information, see <a href="https://www.google.com/support/androidmarket/developer/bin/answer.py?answer=1078870"> @@ -239,11 +242,11 @@ tasks:</p> </ul> <p>There are several additional manifest elements that you can set if you are releasing your -application on Android Market. For example, the <code>android:minSdkVersion</code> and +application on Google Play. For example, the <code>android:minSdkVersion</code> and <code>android:targetSdkVersion</code> attributes, which are located in the <a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html"> <uses-sdk></a> element. For more -information about these and other Android Market settings, see <a -href="{@docRoot}/guide//appendix/market-filters.html">Market Filters</a>.</p> +information about these and other Google Play settings, see <a +href="{@docRoot}/guide//appendix/market-filters.html">Filters on Google Play</a>.</p> <h4>Address compatibility issues</h4> @@ -280,15 +283,15 @@ doing the following:</p> <p>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.</p> -<h4>Implement Licensing (if you are releasing on Android Market)</h4> +<h4>Implement Licensing (if you are releasing on Google Play)</h4> -<p>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.</p> +<p>If you are releasing a paid application through Google Play, consider adding support for +Google Play Licensing. Licensing lets you control access to your application based on whether the +current user has purchased it. Using Google Play Licensing is optional even if you are +releasing your app through Google Play.</p> -<p>For more information about Android Market Licensing Service and how to use it in your -application, see <a href="{@docRoot}guide/publishing/licensing.html">Application Licensing</a>.</p> +<p>For more information about Google Play Licensing Service and how to use it in your +application, see <a href="{@docRoot}guide/market/licensing.html">Application Licensing</a>.</p> <h2 id="publishing-build">Building Your Application for Release</h2> @@ -349,7 +352,7 @@ a summary of common Android situations that you should consider when you are tes done testing and you are satisfied that the release version of your application behaves correctly, you can release your application to users. For more information, see <a href="{@docRoot}guide/publishing/publishing_overview.html#publishing-release">Releasing Your -Application to Users</a>. If you are publishing your application on Android Market, see -<a href="{@docRoot}guide/publishing/publishing.html">Publishing on Android Market</a>.</p> +Application to Users</a>. If you are publishing your application on Google Play, see +<a href="{@docRoot}guide/publishing/publishing.html">Publishing on Google Play</a>.</p> diff --git a/docs/html/guide/publishing/publishing.jd b/docs/html/guide/publishing/publishing.jd index fa677e6..b9513ab 100644 --- a/docs/html/guide/publishing/publishing.jd +++ b/docs/html/guide/publishing/publishing.jd @@ -1,4 +1,4 @@ -page.title=Publishing on Android Market +page.title=Publishing on Google Play @jd:body <div id="qv-wrapper"> @@ -7,111 +7,215 @@ page.title=Publishing on Android Market <h2>Quickview</h2> <ul> -<li>You can publish your application using a hosted service such as Android Market or through a web server.</li> -<li>Before you publish, make sure you have prepared your application properly.</li> -<li>Android Market makes it easy for users of Android-powered devices to see and download your application.</li> +<li>Learn how to publish and update apps on Google Play.</li> +<li>Find out how to create links to apps that are published on Google Play.</li> +<li>Learn about Google Play features.</li> </ul> <h2>In this document</h2> <ol> -<li><a href="#overview">About Android Market</a> -<li><a href="#marketupgrade">Publishing Updates on Android Market</a></li> -<li><a href="#marketLicensing">Using Android Market Licensing Service</a></li> -<li><a href="#marketintent">Linking to Your Apps on Android Market</a> +<li><a href="#overview">About Google Play</a> +<li><A href="#marketpublish">Publishing Apps on Google Play</a></li> +<li><a href="#marketupgrade">Publishing Updates on Google Play</a></li> +<li><a href="#marketLicensing">Using Google Play Licensing Service</a></li> +<li><a href="#marketinappbilling">Using Google Play In-app Billing</a></li> +<li><a href="#marketintent">Linking to Your Apps on Google Play</a> <ol> <li><a href="#OpeningDetails">Opening an app's details page</a></li> <li><a href="#PerformingSearch">Performing a search</a></li> - <li><a href="#BuildaButton">Build an Android Market button</a></li> + <li><a href="#BuildaButton">Build a Google Play button</a></li> <li><a href="#UriSummary">Summary of URI formats</a></li> - </ol> + </ol> </li> </ol> <h2>See also</h2> <ol> -<li><a href="{@docRoot}guide/publishing/licensing.html">Application Licensing</a></li> -<li><a href="{@docRoot}guide/publishing/preparing.html">Preparing to Publish</a></li> +<li><a href="{@docRoot}guide/publishing/publishing_overview.html">Publishing Overview</a></li> +<li><a href="{@docRoot}guide/publishing/preparing.html">Preparing for Release</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 5px;"> - <h2 style="color:#669999;">Interested in publishing your app on Android Market?</h2> - <p><a href="http://market.android.com/publish">Go to Android Market</a> to -create a developer account and upload your application. For more information about the -required assets, listing details, and options, see <a -href="http://market.android.com/support/bin/answer.py?answer=113469">Uploading -applications</a>.</p> + <img src="{@docRoot}assets/images/icon_play.png" style="float:left;margin:0;padding:0 5px;"> + <h2 style="color:#669999;">Already know about Google Play and want to get started?</h2> + <p>Go to <a href="http://play.google.com/apps/publish">Google Play</a>, create a developer +account, and upload your application. For more information about required assets, listing details, +and publishing options, see <a +href="http://market.android.com/support/bin/answer.py?answer=113469">Upload +Applications</a>.</p> </div> </div> </div> </div> -<p>If you've followed the steps outlined in <a -href="{@docRoot}guide/publishing/preparing.html">Preparing to Publish</a>, the result of the process -is a compiled {@code .apk} file that is signed with your private release key. Your application is -now ready to be published publicly so users can install it.</p> +<p>One of the most effective ways to get your application into users' hands is to +publish it on an application marketplace like Google Play. Publishing on Google Play is a +straightforward process that you can do in just a few simple steps—register, configure, +upload, and publish. Registration takes only a few minutes and needs to be done only once. +The configuration and publishing steps can all be done through the Google Play Android Developer Console +after you register as a Google Play developer.</p> -<p>You can publish your application and allow users to install it any way you choose, including -from your own web server. This document provides information about publishing your Android -application with Android Market.</p> +<p>To start publishing on Google Play, first read this topic and then go to the <a +href="https://play.google.com/apps/publish">Google Play Android Developer Console</a> and register as +a Google Play developer.</p> -<h2 id="overview">About Android Market</h2> +<h2 id="overview">About Google Play</h2> -<p>Android Market is a service that makes it easy for users to find and download Android -applications to their Android-powered devices, either from the Android Market application on their -device or from the Android Market web site (<a -href="http://market.android.com">market.android.com</a>). As a developer, you can use Android Market -to distribute your applications to users on all types of Android-powered devices, all around the -world.</p> +<p>Google Play 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 +Google Play 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, such as <a +href="{@docRoot}guide/market/billing/index.html">in-app billing</a> and +<a href="{@docRoot}guide/market/licensing/index.html">application licensing</a>.</p> -<p>To publish your application on Android Market, you first need to register -with the service using a Google account and agree to the terms of service. -Once you are registered, you can upload your application to the service whenever -you want, update it 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. </p> +<p>Before you can publish applications on Google Play, you need to <a +href="http://play.google.com/apps/publish">register</a> as a Google Play developer. During the +registration process you will need to create a developer profile, pay a registration fee, and agree +to the <a href="http://www.android.com/us/developer-distribution-agreement.html">Google Play +Developer Distribution Agreement</a>. After you register you can access the Developer +Console, where you can upload applications, configure publishing options, and monitor publishing +data. If you want to sell your applications or use the in-app billing feature, you will also need +to set up a Google Checkout merchant account. For more information about the registration process, +see <a href="https://support.google.com/androidmarket/developer/bin/answer.py?hl=en&answer=113468"> +Developer Registration</a>.</p> -<p>To register as an Android Market developer and get started with publishing, -visit the Android Market publisher site: </p> +<h2 id="marketpublish">Publishing Apps on Google Play</h2> -<p style="margin-left:3em;"><a -href="http://market.android.com/publish">http://market.android.com/publish</a> -</p> +<p>Publishing your application on Google Play is a simple process that involves three basic +tasks (see figure 1):</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> +<ul> + <li>Creating various graphical assets that +accompany your app on Google Play.</li> + <li>Using the Google Play <a +href="http://play.google.com/apps/publish">Developer Console</a> to configure publishing options, +specify listing details, and upload your app and graphical assets to Google Play.</li> + <li>Reviewing your publishing settings and changing the release +status of your app from Unpublished to Published.</li> +</ul> -<div class="special"> -<p>Requirements enforced by the Android Market server:</p> -<ol> -<li>Your application must be signed with a cryptographic private key whose -validity period ends after <span style="color:red">22 October 2033</span>. </li> -<li>Your application must define both an <code>android:versionCode</code> and an -<code>android:versionName</code> attribute in the -<a -href="{@docRoot}guide/topics/manifest/manifest-element.html"><code><manifest></code></a> -element of its manifest file. The server uses the <code>android:versionCode</code> as -the basis for identifying the application internally and handling updates, and -it displays the <code>android:versionName</code> to users as the application's -version.</li> -<li>Your application must define both an <code>android:icon</code> and an -<code>android:label</code> attribute in the <a -href="{@docRoot}guide/topics/manifest/application-element.html"><code><application></code></a> -element of its manifest file.</li> -</ol> -</div> +<img src="{@docRoot}images/publishing/publishing_android_market.png" + alt="Shows the three steps that are required to publish on Google Play" + height="168" + id="figure1" /> +<p class="img-caption"> + <strong>Figure 1.</strong> To publish apps on Google Play you must first <a +href="{@docRoot}guide/publishing/preparing.html">prepare your app for release</a> and then perform +three simple tasks. +</p> +<p class="caution"><strong>Important:</strong> You must <a +href="{@docRoot}guide/publishing/preparing.html">prepare your application for release</a> before you +can publish it on Google Play. When you prepare your application for release you configure it for +release and build it in release mode. Building in release mode signs your application's {@code .apk} +file with your private release key. You cannot publish an application on Google Play unless it is +signed with your own private release key.</p> + +<h3>Preparing promotional materials</h3> + +<p>To fully leverage the marketing and publicity capabilities of Google Play, you need to create +several graphical assets that accompany your app on Google Play, such as screenshots, videos, +promotional graphics, and promotional text. At a minimum you must provide two screenshots of your +application and a high resolution application icon. The screenshots are displayed on the details +page for your application on Google Play, and the high resolution application icon is displayed +in various locations throughout Google Play. The high resolution icon does not replace the +launcher icon for your application, rather, it serves as a supplemental icon and should look +the same as your launcher icon. Promotional video, +graphics, and text are optional, although we strongly recommended that you prepare these for your +app. For more information about the graphic assets that accompany your application, see <a +href="http://support.google.com/androidmarket/developer/bin/answer.py?hl=en&answer=1078870">Graphic +Assets for your Application</a>.</p> + +<h3>Configuring options and uploading assets</h3> + +<p>Google Play lets you target your application to a worldwide pool of users and devices. To +reach these users you can use the Developer Console to configure various publishing +options and listing details for your app. For example, you can choose the <a +href="http://support.google.com/androidmarket/developer/bin/answer.py?hl=en&answer=138294&topic= +2365624&ctx=topic">countries</a> you want to reach, the listing languages you want to use, and the +<a +href="http://support.google.com/androidmarket/developer/bin/answer.py?hl=en&answer=138412&topic= +15867&ctx=topic">price</a> you want to charge in each country. You can also configure listing +details such as the application type, <a +href="https://support.google.com/androidmarket/developer/bin/answer.py?hl=en&answer=113475&topic= +2365760&ctx=topic">category</a>, and <a +href="http://support.google.com/androidmarket/developer/bin/answer.py?hl=en&answer=188189&topic= +2364761&ctx=topic">content rating</a>. In addition, if you want to sell items within your app using +the in-app billing feature, you can use the Developer Console to <a +href="http://grendel.sea.corp.google.com:48014/guide/market/billing/billing_admin.html#billing-list +- setup">create a product list</a> and control which items are available for purchase in your +app.</p> + +<p>When you are finished setting publishing options and listing details, you can upload your assets +and your application to Google Play. You can also upload your application as a draft +(unpublished) application, which lets you do final testing before you publish it for final +release.</p> + +<p>To learn more about Google Play publishing settings, see the following resources:</p> -<h2 id="marketupgrade">Publishing Updates on Android Market</h2> +<ul> + <li><a +href="http://support.google.com/androidmarket/developer/bin/answer.py?hl=en&answer=113469&topic= +236562&ctx=topic">Upload Applications</a>—provides a summary of the publishing settings +you can configure for an app.</li> + <li><a +href="http://support.google.com/androidmarket/developer/bin/topic.py?hl=en&topic=15867">Selling +Your Apps</a>—provides guidance about pricing, supported currencies, tax rates, and many +other topics related to selling apps.</li> + <li><a +href="https://support.google.com/androidmarket/developer/bin/answer.py?hl=en&answer=1169947&topic= +15867&ctx=topic">Selling Apps in Multiple Currencies</a>—provides a description of how +pricing, payouts, and exchange rates work.</li> +</ul> -<p>At any time after publishing an application on Android Market, you can upload +<h3>Publishing your application</h3> + +<p>When you are satisfied that your publishing settings are correctly configured and your uploaded +application is ready to be released to the public, you can simply click <strong>Publish</strong> in +the Developer Console to make your app available for download +around the world. Keep in mind, it can take several hours for your app to appear on Google +Play after you click <strong>Publish</strong> in the Developer Console.</p> + +<h3>Controlling Distribution to Devices</h3> + +<p>If your application targets different device configurations, you can control which Android-powered +devices have access to your application on Google Play by +using Google Play filters. Filtering compares device configurations that you declare in your +app's manifest file to the configuration defined by a device. For example, if you declare the camera +filter in your manifest, only those devices that have a camera will see your app on Google +Play. Filters must be configured in your application's manifest file when you are <a +href="{@docRoot}guide/publishing/preparing.html">preparing your app for release</a> (that is, before +you upload your app to Google Play). For more information, see <a +href="{@docRoot}guide/appendix/market-filters.html">Filters on Google Play</a>.</p> + +<p>You can also use the multiple APK feature to distribute different {@code .apk} files under the same +application listing and the same package name; however, you should use this option only as a last +resort. Android applications usually run on most compatible devices with a single APK, by supplying +alternative resources for different configurations (for example, different layouts for different screen +sizes) and the Android system selects the appropriate resources for the device at runtime. In a +few cases, however, a single APK is unable to support all device configurations, because alternative +resources make the APK file too big (greater than 50MB) or other technical challenges prevent a +single APK from working on all devices. Although we encourage you to develop and publish a single +APK that supports as many device configurations as possible, doing so is sometimes +not possible. To help you publish your application for as many devices as possible, Google Play +allows you to publish multiple APKs under the same application listing. Google Play then supplies +each APK to the appropriate devices based on configuration support you've declared in the manifest +file of each APK. To use this feature, you need to build your separate {@code .apk} files when you are <a +href="{@docRoot}guide/publishing/preparing.html">preparing your app for release</a> (that is, before +you upload your app to Google Play). For more information, see <a +href="{@docRoot}guide/market/publishing/multiple-apks.html">Multiple APK Support</a>.</p> + +<h2 id="marketupgrade">Publishing Updates on Google Play</h2> + +<p>At any time after publishing an application on Google Play, you can upload and publish an update to the same application package. When you publish an update to an application, users who have already installed the application may receive a notification that an update is @@ -124,85 +228,113 @@ attributes in the <a href="{@docRoot}guide/topics/manifest/manifest-element.html"><code><manifest></code></a> element of the manifest file. Also, the package name must be the same as the existing version and the {@code .apk} file must be signed with the same private key. If the package name and signing -certificate do <em>not</em> match those of the existing version, Market will +certificate do <em>not</em> match those of the existing version, Google Play will consider it a new application, publish it as such, and will not offer it to existing users as an update.</p> +<p>If you plan to publish your application on Google Play, you must make sure + that it meets the requirements listed below, which are enforced by Google Play + when you upload the application.</p> -<h2 id="marketLicensing">Using Android Market Licensing Service</h2> +<h2 id="marketLicensing">Using Google Play Licensing Service</h2> -<p>Android Market offers a licensing service that lets you enforce licensing -policies for paid applications that you publish through Android Market. With -Android Market Licensing, your applications can query Android Market at runtime +<p>Google Play offers a licensing service that lets you enforce licensing +policies for paid applications that you publish through Google Play. With +Google Play Licensing, your applications can query Google Play at runtime to obtain the licensing status for the current user, then allow or disallow further use of the application as appropriate. Using the service, you can apply a flexible -licensing policy on an application-by-application basis—each +licensing policy on an application-by-application basis—each application can enforce its licensing status in the way most appropriate for it. </p> -<p>Any application that you publish through Android Market can use the Android -Market Licensing Service. The service uses no dedicated framework APIs, so you can +<p>Any application that you publish through Google Play can use the Google +Play Licensing Service. The service uses no dedicated framework APIs, so you can add licensing to any application that uses a minimum API Level of 3 or higher.</p> -<p>For complete information about Android Market Licensing Service and how to +<p>For complete information about Google Play Licensing Service and how to use it in your application, read <a -href="{@docRoot}guide/publishing/licensing.html">Application Licensing</a>.</p> +href="{@docRoot}guide/market/licensing/index.html">Application Licensing</a>.</p> + +<h2 id="marketinappbilling">Using Google Play In-app Billing</h2> + +<p><a href="{@docRoot}guide/market/billing/billing_overview.html">Google Play In-app Billing</a> +is a Google Play service that lets you sell digital content in your applications. You can use +the service to sell a wide range of content, including downloadable content such as media files or +photos, and virtual content such as game levels or potions.</p> +<p>When you use Google Play's in-app billing service to sell an item, Google Play handles all +billing details so your application never has to directly process any financial transactions. +Google Play uses the same checkout service that is used for application purchases, so your users +experience a consistent and familiar purchase flow (see figure 1). Also, the transaction fee for +in-app purchases is the same as the transaction fee for application purchases (30%).</p> +<p>Any application that you publish through Google Play can implement in-app billing. No special +account or registration is required other than a Google Play publisher account and a Google +Checkout Merchant account. Also, because the service uses no dedicated framework APIs, you can add +in-app billing to any application that uses a minimum API level of 4 or higher.</p> -<h2 id="marketintent">Linking to Your Apps on Android Market</h2> +<p>To help you integrate in-app billing into your application, the Android SDK provides a <a +href="{@docRoot}guide/market/billing/billing_integrate.html#billing-download">sample application</a> +that demonstrates a simple implementation of in-app billing. The sample application contains +examples of billing-related classes you can use to implement in-app billing in your application. It +also contains examples of the database, user interface, and business logic you might use to +implement in-app billing. For more information about the in-app billing feature, see the +<a href="{@docRoot}guide/market/billing/index.html">In-app Billing documentation</a>.</p> -<p>To help users discover your published applications, you can use two special Android Market URIs +<h2 id="marketintent">Linking to Your Apps on Google Play</h2> + +<p>To help users discover your published applications, you can use two special Google Play URIs that direct users to your application's details page or perform a search for all of your published -applications in Android Market. You can use these URIs to create a button in your application or a +applications on Google Play. You can use these URIs to create a button in your application or a link on a web page that:</p> <ul> - <li>Opens your application's details page in the Android Market application or web site.</li> - <li>Searches for all your published applications in the Android Market application or web + <li>Opens your application's details page in the Google Play application or web site.</li> + <li>Searches for all your published applications in the Google Play application or web site.</li> </ul> -<p>You can launch the Android Market application or web site in the following ways:</p> +<p>You can launch the Google Play application or web site in the following ways:</p> <ul> <li>Initiate an {@link android.content.Intent} from your application that launches the -Android Market application on the user's device.</li> - <li>Provide a link on a web page that opens the Android Market web site (but will also -open the Android Market application if clicked from a device).</li> +Google Play application on the user's device.</li> + <li>Provide a link on a web page that opens the Google Play web site (but will also +open the Google Play application if clicked from a device).</li> </ul> <p>In both cases, whether you want to initiate the action from your application or from a web page, the URIs are quite similar. The only difference is the URI prefix.</p> -<p>To open the Android Market application from your application, the prefix for the intent's data +<p>To open the Google Play application from your application, the prefix for the intent's data URI is:</p> <p style="margin-left:2em"><code>market://</code></p> -<p>To open Android Market from your web site, the prefix for the link URI is:</p> +<p>To open Google Play store from your web site, the prefix for the link URI is:</p> -<p style="margin-left:2em"><code>http://market.android.com/</code></p> +<p style="margin-left:2em"><code>http://play.google.com/store/</code></p> <p>The following sections describe how to create a complete URI for each action.</p> -<p class="note"><strong>Note:</strong> If you create a link to open Android Market from your web -site and the user selects it from an Android-powered device, the device's Market application will -resolve the link so the user can use the Market application instead of opening the web -site. As such, you should always use {@code http://market.android.com/} URIs when creating a link on +<p class="note"><strong>Note:</strong> If you create a link to open Google Play from your web +site and the user selects it from an Android-powered device, the device's Google Play application will +resolve the link so the user can use the Google Play application on the device instead of opening the web +site. As such, you should always use {@code http://play.google.com/store/apps/...} URIs when +creating a link on a web page. When pointing to your apps from within your Android app, use the -{@code market://} URIs in an intent, so that the Market application always opens.</p> +{@code market://} URIs in an intent, so that the Google Play application always opens.</p> <h3 id="OpeningDetails">Opening an app's details page</h3> <p>As described above, you can open the details page for a specific application either on the -Android Market application or the Android Market web site. The details page allows the user to see +Google Play application or the Google Play web site. The details page allows the user to see the application description, screenshots, reviews and more, and choose to install it.</p> <p>The format for the URI that opens the details page is:</p> -<p style="margin-left:2em"><code><URI_prefix><b>details?id=</b><package_name></code></p> +<p style="margin-left:2em"><code><URI_prefix><b>apps/details?id=</b><package_name></code></p> <p>The <code><package_name></code> is a placeholder for the target application's fully-qualified package name, as declared in the <a @@ -210,26 +342,28 @@ href="{@docRoot}guide/topics/manifest/manifest-element.html#package">{@code package}</a> attribute of the <a href="{@docRoot}guide/topics/manifest/manifest-element.html">{@code <manifest>}</a> element.</p> +<p>For example: <code>http://play.google.com/store/apps/details?id=com.example.myapp</code></p> + <h4>Opening the app details page from your Android app</h4> -<p>To open the Android Market details page from your application, +<p>To open the Google Play details page from your application, create an intent with the {@link android.content.Intent#ACTION_VIEW} action and include a data URI in this format:</p> <p style="margin-left:2em"><code>market://details?id=<package_name></code></p> <p>For example, here's how you can create an intent and open an application's details page in -Android Market:</p> +Google Play:</p> <pre> Intent intent = new Intent(Intent.ACTION_VIEW); -intent.setData(Uri.parse("market://details?id=com.android.example")); +intent.setData(Uri.parse("market://details?id=com.example.android")); startActivity(intent); </pre> -<p>This will open the Android Market application on the device to view the {@code -com.android.example} application.</p> +<p>This will open the Google Play application on the device to view the {@code +com.example.android} application.</p> <h4>Opening the app details page from a web site</h4> @@ -238,32 +372,32 @@ com.android.example} application.</p> format:</p> <p style="margin-left:2em"> - <code>http://market.android.com/details?id=<package_name></code> + <code>http://play.google.com/store/apps/details?id=<package_name></code> </p> -<p>For example, here's a link that opens an application's details page on Android Market:</p> +<p>For example, here's a link that opens an application's details page on Google Play:</p> <pre> -<a href="http://market.android.com/details?id=com.android.example">App Link</a> +<a href="http://play.google.com/store/apps/details?id=com.example.android">App Link</a> </pre> -<p>When clicked from a desktop web browser, this opens the Android Market web site to view the -{@code com.android.example} application. When clicked from an Android-powered device, users are -given the option to use either their web browser or the Android Market application to view the +<p>When clicked from a desktop web browser, this opens the Google Play web site to view the +{@code com.example.android} application. When clicked from an Android-powered device, users are +given the option to use either their web browser or the Google Play application to view the application.</p> <h3 id="PerformingSearch">Performing a search</h3> -<p>To initiate a search in Android Market, the format for the URI is:</p> +<p>To initiate a search on Google Play, the format for the URI is:</p> <p style="margin-left:2em"> <code><URI_prefix><b>search?q=</b><query></code> </p> -<p>The <code><query></code> is a placeholder for the search query to execute in Android -Market. The query can be a raw text string or you can include a parameter that performs a search +<p>The <code><query></code> is a placeholder for the search query to execute in Google +Play. The query can be a raw text string or you can include a parameter that performs a search based on the publisher name:</p> <ul> @@ -279,14 +413,14 @@ by the publisher name: <h4>Searching from your Android app</h4> -<p>To initiate a search on Android Market from your application, create an intent with the +<p>To initiate a search on Google Play from your application, create an intent with the {@link android.content.Intent#ACTION_VIEW} action and include a data URI in this format:</p> <p style="margin-left:2em"><code>market://search?q=<query></code></p> <p>The query may include the {@code pub:} parameter described above.</p> -<p>For example, here's how you can initiate a search in the Android Market application, based on the +<p>For example, here's how you can initiate a search in the Google Play application, based on the publisher name:</p> <pre> @@ -295,49 +429,49 @@ intent.setData(Uri.parse("market://search?q=pub:Your Publisher Name")); startActivity(intent); </pre> -<p>This opens the Android Market application to perform the search. The search result shows all +<p>This opens the Google Play application to perform the search. The search result shows all applications published by the publisher that are compatible with the current device.</p> <h4>Searching from a web site</h4> -<p>To initiate a search on Android Market from your web site, create a link with a URI in this +<p>To initiate a search on Google Play from your web site, create a link with a URI in this format:</p> <p style="margin-left:2em"> - <code>http://market.android.com/search?q=<query></code> + <code>http://play.google.com/store/search?q=<query></code> </p> <p>The query may include the {@code pub:} parameter described above.</p> -<p>For example, here's a link that initiates a search on Android Market, based on the +<p>For example, here's a link that initiates a search on Google Play, based on the publisher name:</p> <pre> -<a href="http://market.android.com/search?q=pub:Your Publisher Name">Search Link</a> +<a href="http://play.google.com/store/search?q=pub:Your Publisher Name">Search Link</a> </pre> -<p>When clicked from a desktop web browser, this opens the Android Market web site and performs the +<p>When clicked from a desktop web browser, this opens the Google Play web site and performs the search. When clicked from an Android-powered device, users are given the option to use either their -web browser or the Android Market application to perform the search.</p> +web browser or the Google Play application to perform the search.</p> -<h3 id="BuildaButton">Build an Android Market button</h3> +<h3 id="BuildaButton">Build a Google Play button</h3> -<p>Use the following form to generate an "Available in Android Market" button that you can use on -your web site. Input either your application's package name or publisher name and the button will -take users to Android Market to either view your application's information or view a list of -your published apps. If users click the button while on an Android-powered device, the Android -Market application will respond to show users your application(s).</p> +<p>Use the following form to create a button for your web site that takes users to your application +on Google Play. Input either your application's package name or your publisher name and the button +will take users to Google Play to either view your application's information or view a list of your +published apps. If users click the button while on an Android-powered device, the Google Play +application will respond to show users your application(s).</p> -<p>This form offers four versions of the official "Available in Android Market" button at -recommended sizes. If you want to create a different size, you can download an EPS file for -the button images from the <a href="http://www.android.com/branding.html">Android Brand -Guidelines</a>.</p> +<p>This form offers two styles of the official brand badge each at recommended sizes. You can pick +between either "Get it on Google Play" or "Android app on Google Play." You should not modify the +badge images in any way. For more usage guidelines, +see the <a href="http://www.android.com/branding.html">Android Brand Guidelines</a>.</p> <style type="text/css"> - + form.button-form { margin-top:2em; } @@ -376,33 +510,44 @@ div.button-row input { // variables for creating 'try it out' demo button var imagePath = "http://www.android.com/images/brand/" -var linkStart = "<a href=\"http://market.android.com/"; +var linkStart = "<a href=\"http://play.google.com/store/"; var imageStart = "\">\n" - + " <img src=\"" + imagePath; -var imageEnd = ".png\"\n" - + " alt=\"Available in Android Market\" />\n</a>"; + + " <img alt=\""; + // leaves opening for the alt text value +var imageSrc = "\"\n src=\"" + imagePath; + // leaves opening for the image file name +var imageEnd = ".png\" />\n</a>"; // variables for creating code snippet -var linkStartCode = "<a href=\"http://market.android.com/"; +var linkStartCode = "<a href=\"http://play.google.com/store/"; var imageStartCode = "\">\n" - + " <img src=\"" + imagePath; -var imageEndCode = ".png\"\n" - + " alt=\"Available in Android Market\" />\n</a>"; + + " <img alt=\""; + // leaves opening for the alt text value +var imageSrcCode = "\"\n src=\"" + imagePath; + // leaves opening for the image file name +var imageEndCode = ".png\" />\n</a>"; /** Generate the HTML snippet and demo based on form values */ function buildButton(form) { - if (form["package"].value != "com.android.example") { + var selectedValue = $('form input[type=radio]:checked').val(); + var altText = selectedValue.indexOf("get_it") != -1 ? "Get it on Google Play" : "Android app on Google Play"; + + if (form["package"].value != "com.example.android") { $("#preview").show(); - $("#snippet").show().html(linkStartCode + "details?id=" + form["package"].value - + imageStartCode + $('form input[type=radio]:checked').val() + imageEndCode); - $("#button-preview").html(linkStart + "details?id=" + form["package"].value - + imageStart + $('form input[type=radio]:checked').val() + imageEnd); + $("#snippet").show().html(linkStartCode + "apps/details?id=" + form["package"].value + + imageStartCode + altText + imageSrcCode + + selectedValue + imageEndCode); + $("#button-preview").html(linkStart + "apps/details?id=" + form["package"].value + + imageStart + altText + imageSrc + + selectedValue + imageEnd); } else if (form["publisher"].value != "Example, Inc.") { $("#preview").show(); $("#snippet").show().html(linkStartCode + "search?q=pub:" + form["publisher"].value - + imageStartCode + $('form input[type=radio]:checked').val() + imageEndCode); - $("#button-preview").html(linkStart + "search?q=pub:" + form["publisher"].value + imageStart + - $('form input[type=radio]:checked').val() + imageEnd); + + imageStartCode + altText + imageSrcCode + + selectedValue + imageEndCode); + $("#button-preview").html(linkStart + "search?q=pub:" + form["publisher"].value + + imageStart + altText + imageSrc + + selectedValue + imageEnd); } else { alert("Please enter your package name or publisher name"); } @@ -466,13 +611,13 @@ $(document).ready(function() { <form class="button-form"> <label class="block" for="package">Package name:</label> <input class="text" type="text" id="package" name="package" - value="com.android.example" - default="com.android.example" - onfocus="onInputFocus(this, 'com.android.example')" - onblur="onInputBlur(this, 'com.android.example')" + value="com.example.android" + default="com.example.android" + onfocus="onInputFocus(this, 'com.example.android')" + onblur="onInputBlur(this, 'com.example.android')" onkeyup="return onTextEntered(event, this.parentNode, this)"/> <a id="package-clear" style="display:none" href="#" - onclick="return clearLabel('package','com.android.example');">clear</a> + onclick="return clearLabel('package','com.example.android');">clear</a> <p style="clear:both;margin:0"> <em>or</em></p> <label class="block" style="margin-top:5px" for="publisher">Publisher name:</label> <input class="text" type="text" id="publisher" name="publisher" @@ -486,23 +631,23 @@ $(document).ready(function() { <br/><br/> <div class="button-row"> - <input type="radio" name="buttonStyle" value="45_avail_market_logo1" id="ns" checked="checked" /> - <label for="ns"><img src="http://www.android.com/images/brand/45_avail_market_logo1.png" -alt="narrow and small logo" /></label> + <input type="radio" name="buttonStyle" value="get_it_on_play_logo_small" id="ns" checked="checked" /> + <label for="ns"><img src="http://www.android.com/images/brand/get_it_on_play_logo_small.png" +alt="Get it on Google Play (small)" /></label> - <input type="radio" name="buttonStyle" value="60_avail_market_logo1" id="nm" /> - <label for="nm"><img src="http://www.android.com/images/brand/60_avail_market_logo1.png" -alt="narrow and large logo" /></label> + <input type="radio" name="buttonStyle" value="get_it_on_play_logo_large" id="nm" /> + <label for="nm"><img src="http://www.android.com/images/brand/get_it_on_play_logo_large.png" +alt="Get it on Google Play (large)" /></label> </div> <div class="button-row"> - <input type="radio" name="buttonStyle" value="45_avail_market_logo2" id="ws" /> - <label for="ws"><img src="http://www.android.com/images/brand/45_avail_market_logo2.png" -alt="wide and small logo" /></label> + <input type="radio" name="buttonStyle" value="android_app_on_play_logo_small" id="ws" /> + <label for="ws"><img src="http://www.android.com/images/brand/android_app_on_play_logo_small.png" +alt="Android app on Google Play (small)" /></label> - <input type="radio" name="buttonStyle" value="60_avail_market_logo2" id="wm" /> - <label for="wm"><img src="http://www.android.com/images/brand/60_avail_market_logo2.png" -alt="wide and large logo" /></label> + <input type="radio" name="buttonStyle" value="android_app_on_play_logo_large" id="wm" /> + <label for="wm"><img src="http://www.android.com/images/brand/android_app_on_play_logo_large.png" +alt="Android app on Google Play (large)" /></label> </div> <input type="button" onclick="return buildButton(this.parentNode)" value="Build my button" @@ -512,7 +657,7 @@ style="padding:5px" /> <div id="preview" style="display:none"> <p>Copy and paste this HTML into your web site:</p> - <textarea id="snippet" cols="80" rows="4" onclick="this.select()" + <textarea id="snippet" cols="100" rows="5" onclick="this.select()" style="font-family:monospace;background-color:#efefef;padding:5px;display:none;margin-bottom:1em"> </textarea > @@ -527,7 +672,7 @@ style="font-family:monospace;background-color:#efefef;padding:5px;display:none;m <h3 id="UriSummary">Summary of URI formats</h3> -<p>The table below provides a summary of the URIs currently supported by the Android Market (both on +<p>The table below provides a summary of the URIs currently supported by the Google Play (both on the web and in the Android application), as discussed in the previous sections.</p> <table> @@ -539,19 +684,19 @@ the web and in the Android application), as discussed in the previous sections.< <tr> <td>Display the details screen for a specific application</td> -<td><code>http://market.android.com/details?id=<package_name></code> +<td><code>http://play.google.com/store/apps/details?id=<package_name></code> <td><code>market://details?id=<package_name></code></td> </tr> <tr> <td>Search for applications using a general string query.</td> -<td><code>http://market.android.com/search?q=<query></code></td> +<td><code>http://play.google.com/store/search?q=<query></code></td> <td><code>market://search?q=<query></code></td> </tr> <tr> <td>Search for applications by publisher name</td> -<td><nobr><code>http://market.android.com/search?q=pub:<publisher_name></code></nobr></td> +<td><nobr><code>http://play.google.com/store/search?q=pub:<publisher_name></code></nobr></td> <td><nobr><code>market://search?q=pub:<publisher_name></code></nobr></td> </tr> diff --git a/docs/html/guide/publishing/publishing_overview.jd b/docs/html/guide/publishing/publishing_overview.jd index a0f6ae3..6fb77e1 100755 --- a/docs/html/guide/publishing/publishing_overview.jd +++ b/docs/html/guide/publishing/publishing_overview.jd @@ -14,16 +14,16 @@ page.title=Publishing Overview <li><a href="#publishing-prepare">Preparing Your Application for Release</a></li> <li><a href="#publishing-release">Releasing Your Application to Users</a> <ol> - <li><a href="#publishing-market">Releasing on Android Market</a></li> + <li><a href="#publishing-market">Releasing on Google Play</a></li> <li><a href="#publishing-website">Releasing on your own website</a></li> <li><a href="#publishing-email">Releasing through email</a></li> </ol> </ol> <h2>See also</h2> <ol> - <li><a href="{@docRoot}guide/publishing/publishing_preparing.html">Preparing for + <li><a href="{@docRoot}guide/publishing/preparing.html">Preparing for Release</a></li> - <li><a href="{@docRoot}guide/publishing/publishing.html">Publishing on Android Market</a></li> + <li><a href="{@docRoot}guide/publishing/publishing.html">Publishing on Google Play</a></li> </ol> </div> </div> @@ -42,7 +42,7 @@ publish an Android application you perform two main tasks:</p> </li> </ul> -<p>Usually, you release your application through an application marketplace, such as Android Market. +<p>Usually, you release your application through an application marketplace, such as Google Play. However, you can also release applications by sending them directly to users or by letting users download them from your own website.</p> @@ -73,7 +73,7 @@ tasks:</p> <code>android:versionCode</code> and <code>android:versionName</code> attributes, which are located in the <a href="{@docRoot}guide/topics/manifest/manifest-element.html"><manifest></a> - element. You may also have to configure several other settings to meet Android Market + element. You may also have to configure several other settings to meet Google Play requirements or accomodate whatever method you're using to release your application.</p> </li> <li>Building and signing a release version of your application. @@ -114,27 +114,27 @@ application.</p> <h2 id="publishing-release">Releasing Your Application to Users</h2> <p>You can release your Android applications several ways. Usually, you release applications -through an application marketplace, such as Android Market, but you can also release applications -on your own website or by sending an application directly to a user. Android Market is the +through an application marketplace, such as Google Play, but you can also release applications +on your own website or by sending an application directly to a user. Google Play 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.</p> -<h3 id="publishing-market">Releasing Your Applications on Android Market</h3> +<h3 id="publishing-market">Releasing Your Applications on Google Play</h3> -<p>Android Market is a robust publishing platform that helps you publicize, sell, and distribute +<p>Google Play 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, +Google Play you have access to a suite of developer tools that let you analyze your sales, identify market trends, and control who your applications are being distributed to. You also have access to several revenue-enhancing features that are not available anywhere else, such as <a href="{@docRoot}guide/market/billing/index.html">in-app billing</a> and <a -href="{@docRoot}guide/publishing/licensing.html">application licensing</a>. This rich array of tools -and features, coupled with numerous end-user community features, makes Android Market the premier +href="{@docRoot}guide/market/licensing.html">application licensing</a>. This rich array of tools +and features, coupled with numerous end-user community features, makes Google Play the premier marketplace for selling and buying Android applications.</p> -<p>Releasing your application on Android Market is a simple process that involves four basic +<p>Releasing your application on Google Play is a simple process that involves three basic steps:</p> <div class="figure" style="width:275px"> @@ -143,52 +143,47 @@ marketplace for selling and buying Android applications.</p> to be installed" /> <p class="img-caption"> <strong>Figure 2.</strong> The <strong>Unknown sources</strong> setting lets you install - applications that are not published on Android Market . + applications that are not published on Google Play . </p> </div> <ul> <li>Preparing promotional materials. - <p>To fully leverage the marketing and publicity capabilities of Android Market, you need to + <p>To fully leverage the marketing and publicity capabilities of Google Play, you need to create promotional materials for your application, such as screenshots, videos, graphics, and promotional text.</p> </li> - <li>Planning publishing options. - <p>Android Market lets you target your application to a worldwide pool of users and devices. - Using various Android Market tools, you can choose the countries you want to reach, the - price you want to charge in each country, and the devices you want to target. You can also - use Android Market's filtering settings to target specific device features and capabilities.</p> - </li> - <li>Configuring publishing options and uploading assets. - <p>After you create your promotional materials and determine which publishing options are - suitable for your application, you can use the Android Market developer console to configure - those options and upload the promotional materials. You can also use the developer console to - upload your application as a draft (unpublished) application, which lets you do final - testing before you publish it for final release.</p> + <li>Configuring options and uploading assets. + <p>Google Play lets you target your application to a worldwide pool of users and devices. + By configuring various Google Play settings, you can choose the countries you want to + reach, the listing languages you want to use, and the price you want to charge in each + country. You can also configure listing details such as the application type, category, and + content rating. When you are done configuring options you can upload your promotional materials + and your application as a draft (unpublished) application.</p> </li> <li>Publishing the release version of your application. - <p>When you are satisfied that your publishing settings are correctly configured and your + <p>If you are satisfied that your publishing settings are correctly configured and your uploaded application is ready to be released to the public, you can simply click <strong>Publish</strong > in the developer console and within minutes your application will be live and available for download around the world.</p> </li> </ul> -<p>For information about Android Market, see <a -href="{@docRoot}guide/publishing/publishing.html#market">Publishing on Android Market</a>. This -topic provides an introduction to Android Market features and provides a step-by-step guide for -distributing your applications on Android Market.</p> +<p>For information about Google Play, see <a +href="{@docRoot}guide/publishing/publishing.html#market">Publishing on Google Play</a>. This +topic provides an introduction to Google Play features and provides a step-by-step guide for +distributing your applications on Google Play.</p> <h3 id="publishing-website">Releasing your application on your own website</h3> -<p>If you do not want to release your application on an application marketplace like Android Market, +<p>If you do not want to release your application on an application marketplace like Google Play, 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 +only if the user has configured their device to allow the installation of non-Google Play applications.</p> <div class="figure" style="width:275px"> @@ -202,7 +197,7 @@ applications.</p> </div> <p>By default, Android-powered devices allow users to install applications only if the applications -have been downloaded from Android Market. To allow the installation of applications from other +have been downloaded from Google Play. To allow the installation of applications from other sources, users need to enable the <strong>Unknown sources</strong> setting on their devices, and they need to make this configuration change before they download your application to their device (see figure 2).</p> @@ -213,7 +208,7 @@ applications from unknown sources.</p> <p>Although it is relatively easy to release your application on your own website, it can be inefficient and cumbersome. For example, if you want to monetize your application you will have to process and track all financial transactions yourself and you will not be able to use -Android Market's in-app billing feature to sell in-app products. In addition, you will not be +Google Play's in-app billing feature to sell in-app products. In addition, you will not be able to use the licensing feature to help prevent unauthorized installation and use of your application.</p> @@ -227,10 +222,10 @@ button in the email message (see figure 3). Users can install your application b button.</p> <p class="note"><strong>Note:</strong> The <strong>Install Now</strong> button appears only if a -user has configured their device to allow the installation of non-Android Market applications and +user has configured their device to allow the installation of non-Google Play applications and they open your email with the native Gmail application.</p> <p>Releasing applications through email is convenient if you are sending your application to only a few trusted users, but it provides few protections from piracy and unauthorized distribution; that is, anyone you send your application to can simply forward it to someone else. -else.
\ No newline at end of file +else. diff --git a/docs/html/guide/publishing/versioning.jd b/docs/html/guide/publishing/versioning.jd index 79ebf96..da57e3e 100644 --- a/docs/html/guide/publishing/versioning.jd +++ b/docs/html/guide/publishing/versioning.jd @@ -25,7 +25,7 @@ page.title=Versioning Your Applications <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/publishing/publishing.html#market">Publishing On Google Play</a></li> <li><a href="{@docRoot}guide/topics/manifest/manifest-intro.html">The AndroidManifest.xml File</a></li> </ol> |