| page.title=Adding Licensing to Your App |
| parent.title=Application Licensing |
| parent.link=index.html |
| @jd:body |
| |
| |
| |
| <div id="qv-wrapper"> |
| <div id="qv"> |
| |
| <h2>In this document</h2> |
| <ol> |
| <li><a href="#manifest-permission">Adding the Licensing Permission</a></li> |
| <li><a href="#impl-Policy">Implementing a Policy</a> |
| <ol> |
| <li><a href="#custom-policies">Guidelines for custom policies</a></li> |
| <li><a href="#ServerManagedPolicy">ServerManagedPolicy</a></li> |
| <li><a href="#StrictPolicy">StrictPolicy</a></li> |
| </ol> |
| </li> |
| <li><a href="#impl-Obfuscator">Implementing an Obfuscator</a> |
| <ol> |
| <li><a href="#AESObfuscator">AESObfuscator</a></li> |
| </ol> |
| </li> |
| <li><a href="#impl-lc">Checking the License from an Activity</a> |
| <ol> |
| <li><a href="#lc-overview">Overview of license check and response</a></li> |
| <li><a href="#imports">Add imports</a></li> |
| <li><a href="#lc-impl">Implement LicenseCheckerCallback as a private inner class</a></li> |
| <li><a href="#thread-handler">Create a Handler for posting from LicenseCheckerCallback |
| to the UI thread</a></li> |
| <li><a href="#lc-lcc">Instantiate LicenseChecker and LicenseCheckerCallback</a></li> |
| <li><a href="#check-access">Call checkAccess() to initiate the license check</a></li> |
| <li><a href="#account-key">Embed your public key for licensing</a></li> |
| <li><a href="#handler-cleanup">Call your LicenseChecker's onDestroy() method |
| to close IPC connections</a></li> |
| </ol> |
| </li> |
| <li><a href="#impl-DeviceLimiter">Implementing a DeviceLimiter</a></li> |
| <li><a href="#app-obfuscation">Obfuscating Your Code</a></li> |
| <li><a href="#app-publishing">Publishing a Licensed Application</a> |
| <ol> |
| <li><a href="#">Removing Copy Protection</a></li> |
| </ol> |
| </li> |
| <li><a href="#support">Where to Get Support</a></li> |
| </ol> |
| |
| </div> |
| </div> |
| |
| |
| |
| <p>After you've set up a publisher account and development environment (see <a |
| href="setting-up.html">Setting Up for Licensing</a>), you are ready to add license verification to |
| your app with the License Verification Library (LVL).</p> |
| |
| <p>Adding license verification with the LVL 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 {@code 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="{@docRoot}guide/market/licensing/setting-up.html#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="{@docRoot}guide/market/licensing/licensing-reference.html#lvl-summary">Summary of LVL Classes |
| and Interfaces</a>.</p> |
| |
| |
| <h2 id="manifest-permission">Adding the Licensing Permission</h2> |
| |
| <p>To use the Google Play 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 Google Play 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> |
| |
| |
| <h2 id="impl-Policy">Implementing a Policy</h2> |
| |
| <div class="sidebox-wrapper"> |
| <div class="sidebox"> |
| <h2>ServerManagedPolicy</h2> |
| |
| <p>The LVL includes a complete {@code Policy} implementation called ServerManagedPolicy |
| that makes use of license-management settings provided by the Google Play |
| 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>Google Play 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 {@code 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 {@code Policy}. </p> |
| |
| <p>The {@code Policy} interface declares two methods, <code>allowAccess()</code> and |
| <code>processServerResponse()</code>, which are called by a {@code 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 {@code 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.</p> |
| |
| <p>When storing response data locally, the {@code 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 {@code Policy} should be designed, the LVL includes |
| two full {@code Policy} implementations that you can use without modification or |
| adapt to your needs:</p> |
| |
| <ul> |
| <li><a href="#ServerManagedPolicy">ServerManagedPolicy</a>, a flexible {@code 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> |
| |
| |
| <h3 id="custom-policies">Guidelines for custom policies</h3> |
| |
| <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 {@code 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="{@docRoot}guide/market/licensing/licensing-reference.html#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 Google Play client automatically retries failed |
| requests, so in most cases there is no need for your {@code 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 {@code 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 {@code 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="{@docRoot}guide/market/licensing/licensing-reference.html#extras">Server Response |
| Extras</a>.</p> |
| |
| <h3 id="ServerManagedPolicy">ServerManagedPolicy</h3> |
| |
| <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="{@docRoot}guide/market/licensing/licensing-reference.html#extras">Server Response Extras</a> |
| for |
| a list of settings and <code>ServerManagedPolicy.java</code> for information |
| about how a {@code Policy} can use the extras.</p> |
| |
| </div> |
| </div> |
| |
| <p>The LVL includes a full and recommended implementation of the {@code Policy} |
| interface called ServerManagedPolicy. The implementation is integrated with the |
| LVL classes and serves as the default {@code 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 {@code 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 Google Play 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="{@docRoot}guide/market/licensing/licensing-reference.html#extras">Server Response |
| Extras</a>.</p> |
| |
| <p>For convenience, best performance, and the benefit of using license settings |
| from the Google Play server, <strong>using ServerManagedPolicy as your |
| licensing {@code Policy} is strongly recommended</strong>. </p> |
| |
| <p>If you are concerned about the security of license response data that is |
| stored locally in {@link android.content.SharedPreferences}, you can use a stronger obfuscation |
| algorithm or design a stricter {@code Policy} that does not store license data. The LVL |
| includes an example of such a {@code 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 |
| {@code LicenseChecker}. See <a href="#lc-lcc">Instantiate LicenseChecker and |
| LicenseCheckerCallback</a> for more information. </p> |
| |
| <h3 id="StrictPolicy">StrictPolicy</h3> |
| |
| <p>The LVL includes an alternative full implementation of the {@code 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 {@code 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 {@code 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 {@code Policy}.</p> |
| |
| <p>To use StrictPolicy, simply import it to your Activity, create an instance, |
| and pass a reference to it when constructing your {@code LicenseChecker}. See |
| <a href="#lc-lcc">Instantiate LicenseChecker and LicenseCheckerCallback</a> |
| for more information. </p> |
| |
| <h2 id="impl-Obfuscator">Implementing an Obfuscator</h2> |
| |
| <div class="sidebox-wrapper"> |
| <div class="sidebox"> |
| <h2>AESObfuscator</h2> |
| |
| <p>The LVL includes a full {@code Obfuscator} implementation in the |
| <code>AESObfuscator.java</code> file. The {@code Obfuscator} uses AES encryption to |
| obfuscate/unobfuscate data. If you are using a {@code Policy} (such as |
| ServerManagedPolicy) that caches license response data, using AESObfuscator as |
| basis for your {@code Obfuscator} implementation is highly recommended. </p> |
| |
| </div> |
| </div> |
| |
| <p>A typical {@code 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 {@code 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 {@code 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 {@code 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 {@code 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 {@code 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 {@code Obfuscator} class and reading and writing the obfuscated data in a |
| {@link android.content.SharedPreferences} instance. </p> |
| |
| <p>The LVL provides a full {@code 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> |
| |
| |
| <h3 id="AESObfuscator">AESObfuscator</h3> |
| |
| <p>The LVL includes a full and recommended implementation of the {@code Obfuscator} |
| interface called AESObfuscator. The implementation is integrated with the |
| LVL sample application and serves as the default {@code 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 {@code 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 {@code Obfuscator}, consider |
| how doing so might affect your application or its filtering on Google Play |
| (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 {@code Policy} and {@code 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> |
| |
| |
| <h2 id="impl-lc">Checking the License from an Activity</h2> |
| |
| <p>Once you've implemented a {@code 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> |
| |
| <h3 id="lc-overview">Overview of license check and response</h3> |
| |
| <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 {@link android.app.Activity#onCreate onCreate()} 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 {@code 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 these 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 {@code Policy} implementation. Rather, these |
| methods simply provide the application behaviors for <em>how</em> to allow and |
| disallow access (and handle application errors). |
| <p>The <code>allow()</code> and <code>dontAllow()</code> methods do provide a "reason" |
| for their response, which can be one of the {@code Policy} values, {@code LICENSED}, |
| {@code NOT_LICENSED}, or {@code RETRY}. In particular, you should handle the case in which |
| the method receives the {@code RETRY} response for {@code dontAllow()} and provide the user with an |
| "Retry" button, which might have happened because the service was unavailable during the |
| request.</p></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 {@code LicenseCheckerCallback} |
| and {@code LicenseChecker} objects. When constructing {@code LicenseChecker}, the code passes in |
| {@link android.content.Context}, a {@code 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 |
| {@code LicenseChecker} object. The method implementation calls the {@code 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 {@code 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, {@code LicenseChecker} creates a LicenseValidator that |
| verifies the signed license data and extracts the fields of the response, then |
| passes them to your {@code Policy} for further evaluation. |
| <ul> |
| <li>If the license is valid, the {@code Policy} caches the response in |
| {@link android.content.SharedPreferences} and notifies the validator, which then calls the |
| <code>allow()</code> method on the {@code LicenseCheckerCallback} object. </li> |
| <li>If the license not valid, the {@code Policy} notifies the validator, which calls |
| the <code>dontAllow()</code> method on {@code 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, {@code LicenseChecker} passes a {@code RETRY} response to |
| your {@code Policy} object's <code>processServerResponse()</code> method. |
| <p>Also, both the {@code allow()} and {@code dontAllow()} callback methods receive a |
| <code>reason</code> argument. The {@code allow()} method's reason is usually {@code |
| Policy.LICENSED} or {@code Policy.RETRY} and the {@code dontAllow()} reason is usually {@code |
| Policy.NOT_LICENSED} or {@code Policy.RETRY}. These response values are useful so you can show |
| an appropriate response for the user, such as by providing a "Retry" button when {@code |
| dontAllow()} responds with {@code Policy.RETRY}, which might have been because the service was |
| unavailable.</p></li> |
| <li>In case of a application error, such as when the application attempts to |
| check the license of an invalid package name, {@code 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 {@code Policy} |
| stores response data (such as ServerManagedPolicy), an <a |
| href="#impl-Obfuscator">Obfuscator</a> implementation. </p> |
| |
| |
| <h3 id="imports">Add imports</h3> |
| |
| <p>First, open the class file of the application's main Activity and import |
| {@code LicenseChecker} and {@code 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 {@code Policy} implementation provided with the LVL, |
| ServerManagedPolicy, import it also, together with the AESObfuscator. If you are |
| using a custom {@code Policy} or {@code Obfuscator}, import those instead. </p> |
| |
| <pre> import com.android.vending.licensing.ServerManagedPolicy; |
| import com.android.vending.licensing.AESObfuscator;</pre> |
| |
| <h3 id="lc-impl">Implement LicenseCheckerCallback as a private inner class</h3> |
| |
| <p>{@code LicenseCheckerCallback} is an interface provided by the LVL for handling |
| result of a license check. To support licensing using the LVL, you must |
| implement {@code 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 |
| {@code LicenseCheckerCallback} methods, made based on the validation of the response |
| payload, the server response code itself, and any additional processing provided |
| by your {@code 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 {@code Policy}, rather than |
| putting it in the {@code LicenseCheckerCallback} methods. </p> |
| |
| <p>In most cases, you should declare your implementation of |
| {@code 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 if the <code>reason</code> supplied is {@code Policy.RETRY}. </li> |
| <li>Display a "Purchase this application" dialog, including a button that |
| deep-links the user to the application's details page on Google Play, 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">Linking to your apps |
| on Google Play</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 |
| {@code LicenseCheckerCallback}, with methods that display the license check result in a |
| dialog. </p> |
| |
| <pre> |
| private class MyLicenseCheckerCallback implements LicenseCheckerCallback { |
| public void allow(int reason) { |
| if (isFinishing()) { |
| // Don't update UI if Activity is finishing. |
| return; |
| } |
| // Should allow user access. |
| displayResult(getString(R.string.allow)); |
| } |
| |
| public void dontAllow(int reason) { |
| if (isFinishing()) { |
| // Don't update UI if Activity is finishing. |
| return; |
| } |
| displayResult(getString(R.string.dont_allow)); |
| |
| if (reason == Policy.RETRY) { |
| // If the reason received from the policy is RETRY, it was probably |
| // due to a loss of connection with the service, so we should give the |
| // user a chance to retry. So show a dialog to retry. |
| showDialog(DIALOG_RETRY); |
| } else { |
| // Otherwise, the user is not licensed to use this app. |
| // Your response should always inform the user that the application |
| // is not licensed, but your behavior at that point can vary. You might |
| // provide the user a limited access version of your app or you can |
| // take them to Google Play to purchase the app. |
| showDialog(DIALOG_GOTOMARKET); |
| } |
| } |
| } |
| </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="{@docRoot}guide/market/licensing/licensing-reference.html#server-response-codes">Server |
| Response Codes</a> in the <a |
| href="guide/market/licensing/licensing-reference.html">Licensing Reference</a>. 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> |
| |
| <h3 id="thread-handler">Create a Handler for posting from LicenseCheckerCallback |
| to the UI thread</h3> |
| |
| <p>During a license check, the LVL passes the request to the Google Play |
| 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 Google Play 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 {@code LicenseChecker} class manages your application's IPC communication with |
| the Google Play application, including the call that sends the request and |
| the callback that receives the response. {@code 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, {@code 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 |
| {@code LicenseCheckerCallback} methods from the background thread. </p> |
| |
| <p>To your application, this means that:</p> |
| |
| <ol> |
| <li>Your {@code 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 {@code 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 |
| {@code 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 {@code 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> |
| |
| <h3 id="lc-lcc">Instantiate LicenseChecker and LicenseCheckerCallback</h3> |
| |
| <p>In the main Activity's |
| {@link android.app.Activity#onCreate(android.os.Bundle) onCreate()} method, |
| create private instances of LicenseCheckerCallback and {@code LicenseChecker}. You must |
| instantiate {@code LicenseCheckerCallback} first, because you need to pass a reference |
| to that instance when you call the constructor for {@code LicenseChecker}. </p> |
| |
| <p>When you instantiate {@code LicenseChecker}, you need to pass in these parameters:</p> |
| |
| <ul> |
| <li>The application {@link android.content.Context}</li> |
| <li>A reference to the {@code Policy} implementation to use for the license check. In |
| most cases, you would use the default {@code 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 {@code 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 {@code LicenseChecker} and |
| {@code 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 {@code LicenseChecker} calls the {@code 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> |
| |
| |
| <h3 id="check-access">Call checkAccess() to initiate the license check</h3> |
| |
| <p>In your main Activity, add a call to the <code>checkAccess()</code> method of the |
| {@code LicenseChecker} instance. In the call, pass a reference to your |
| {@code 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> |
| |
| |
| <h3 id="account-key">Embed your public key for licensing</h3> |
| |
| <p>For each publisher account, the Google Play 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 Google Play 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 Google Play <a |
| href="http://play.google.com/apps/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> |
| |
| <h3 id="handler-cleanup">Call your LicenseChecker's onDestroy() method |
| to close IPC connections</h3> |
| |
| <p>Finally, to let the LVL clean up before your application |
| {@link android.content.Context} changes, add a call to the {@code LicenseChecker}'s |
| <code>onDestroy()</code> method from your Activity's |
| {@link android.app.Activity#onDestroy()} implementation. The call causes the |
| {@code LicenseChecker} to properly close any open IPC connection to the Google Play |
| application's ILicensingService and removes any local references to the service |
| and handler.</p> |
| |
| <p>Failing to call the {@code 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 {@code 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 |
| {@code 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 {@code LicenseChecker} instance:</p> |
| |
| <pre> @Override |
| protected void onDestroy() { |
| super.onDestroy(); |
| mChecker.onDestroy(); |
| ... |
| } |
| </pre> |
| |
| <p>If you are extending or modifying {@code LicenseChecker}, you might also need to call |
| the {@code LicenseChecker}'s <code>finishCheck()</code> method, to clean up any open IPC |
| connections.</p> |
| |
| <h2 id="impl-DeviceLimiter">Implementing a DeviceLimiter</h2> |
| |
| <p>In some cases, you might want your {@code 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 {@code 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="app-obfuscation">Obfuscating Your Code</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 Google |
| Play 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 Google Play. 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> |
| |
| <h3>Removing Copy Protection</h3> |
| |
| <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> |
| |
| |
| <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 Google Play 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, {@code Policy} |
| questions, user experience ideas, handling of responses, {@code 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">Google Play |
| 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> |
| |
| |