1 page.title=Adding Licensing to Your App 2 parent.title=Application Licensing 3 parent.link=index.html 4 @jd:body 5 6 7 8 <div id="qv-wrapper"> 9 <div id="qv"> 10 11 <h2>In this document</h2> 12 <ol> 13 <li><a href="#manifest-permission">Adding the Licensing Permission</a></li> 14 <li><a href="#impl-Policy">Implementing a Policy</a> 15 <ol> 16 <li><a href="#custom-policies">Guidelines for custom policies</a></li> 17 <li><a href="#ServerManagedPolicy">ServerManagedPolicy</a></li> 18 <li><a href="#StrictPolicy">StrictPolicy</a></li> 19 </ol> 20 </li> 21 <li><a href="#impl-Obfuscator">Implementing an Obfuscator</a> 22 <ol> 23 <li><a href="#AESObfuscator">AESObfuscator</a></li> 24 </ol> 25 </li> 26 <li><a href="#impl-lc">Checking the License from an Activity</a> 27 <ol> 28 <li><a href="#lc-overview">Overview of license check and response</a></li> 29 <li><a href="#imports">Add imports</a></li> 30 <li><a href="#lc-impl">Implement LicenseCheckerCallback as a private inner class</a></li> 31 <li><a href="#thread-handler">Create a Handler for posting from LicenseCheckerCallback 32 to the UI thread</a></li> 33 <li><a href="#lc-lcc">Instantiate LicenseChecker and LicenseCheckerCallback</a></li> 34 <li><a href="#check-access">Call checkAccess() to initiate the license check</a></li> 35 <li><a href="#account-key">Embed your public key for licensing</a></li> 36 <li><a href="#handler-cleanup">Call your LicenseChecker's onDestroy() method 37 to close IPC connections</a></li> 38 </ol> 39 </li> 40 <li><a href="#impl-DeviceLimiter">Implementing a DeviceLimiter</a></li> 41 <li><a href="#app-obfuscation">Obfuscating Your Code</a></li> 42 <li><a href="#app-publishing">Publishing a Licensed Application</a> 43 <ol> 44 <li><a href="#">Removing Copy Protection</a></li> 45 </ol> 46 </li> 47 <li><a href="#support">Where to Get Support</a></li> 48 </ol> 49 50 </div> 51 </div> 52 53 54 55 <p>After you've set up a publisher account and development environment (see <a 56 href="setting-up.html">Setting Up for Licensing</a>), you are ready to add license verification to 57 your app with the License Verification Library (LVL).</p> 58 59 <p>Adding license verification with the LVL involves these tasks:</p> 60 61 <ol> 62 <li><a href="#manifest-permission">Adding the licensing permission</a> your application's manifest.</li> 63 <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> 64 <li><a href="#impl-Obfuscator">Implementing an Obfuscator</a>, if your {@code Policy} will cache any 65 license response data. </li> 66 <li><a href="#impl-lc">Adding code to check the license</a> in your application's main 67 Activity.</li> 68 <li><a href="#impl-DeviceLimiter">Implementing a DeviceLimiter</a> (optional and not recommended for 69 most applications).</li> 70 </ol> 71 72 <p>The sections below describe these tasks. When you are done with the 73 integration, you should be able to compile your application successfully and you 74 can begin testing, as described in <a 75 href="{@docRoot}guide/google/play/licensing/setting-up.html#test-env">Setting Up the Test 76 Environment</a>.</p> 77 78 <p>For an overview of the full set of source files included in the LVL, see <a 79 href="{@docRoot}guide/google/play/licensing/licensing-reference.html#lvl-summary">Summary of LVL Classes 80 and Interfaces</a>.</p> 81 82 83 <h2 id="manifest-permission">Adding the Licensing Permission</h2> 84 85 <p>To use the Google Play application for sending a license check to the 86 server, your application must request the proper permission, 87 <code>com.android.vending.CHECK_LICENSE</code>. If your application does 88 not declare the licensing permission but attempts to initiate a license check, 89 the LVL throws a security exception.</p> 90 91 <p>To request the licensing permission in your application, declare a <a 92 href="{@docRoot}guide/topics/manifest/uses-permission-element.html"><code><uses-permission></code></a> 93 element as a child of <code><manifest></code>, as follows: </p> 94 95 <p style="margin-left:2em;"><code><uses-permission 96 android:name="com.android.vending.CHECK_LICENSE"></code></p> 97 98 <p>For example, here's how the LVL sample application declares the permission: 99 </p> 100 101 <pre><?xml version="1.0" encoding="utf-8"?> 102 103 <manifest xmlns:android="http://schemas.android.com/apk/res/android" ..."> 104 <!-- Devices >= 3 have version of Google Play that supports licensing. --> 105 <uses-sdk android:minSdkVersion="3" /> 106 <!-- Required permission to check licensing. --> 107 <uses-permission android:name="com.android.vending.CHECK_LICENSE" /> 108 ... 109 </manifest> 110 </pre> 111 112 <p class="note"><strong>Note:</strong> Currently, you cannot declare the 113 <code>CHECK_LICENSE</code> permission in the LVL library project's manifest, 114 because the SDK Tools will not merge it into the manifests of dependent 115 applications. Instead, you must declare the permission in each dependent 116 application's manifest. </p> 117 118 119 <h2 id="impl-Policy">Implementing a Policy</h2> 120 121 <div class="sidebox-wrapper"> 122 <div class="sidebox"> 123 <h2>ServerManagedPolicy</h2> 124 125 <p>The LVL includes a complete {@code Policy} implementation called ServerManagedPolicy 126 that makes use of license-management settings provided by the Google Play 127 server. </p> 128 129 <p style="margin-top:.5em;">Use of ServerManagedPolicy as the basis for your 130 Policy is strongly recommended. For more information, see <a 131 href="#ServerManagedPolicy">ServerManagedPolicy</a> section, below.</p> 132 133 </div> 134 </div> 135 136 <p>Google Play licensing service does not itself determine whether a 137 given user with a given license should be granted access to your application. 138 Rather, that responsibility is left to a {@code Policy} implementation that you provide 139 in your application.</p> 140 141 <p>Policy is an interface declared by the LVL that is designed to hold your 142 application's logic for allowing or disallowing user access, based on the result 143 of a license check. To use the LVL, your application <em>must</em> provide an 144 implementation of {@code Policy}. </p> 145 146 <p>The {@code Policy} interface declares two methods, <code>allowAccess()</code> and 147 <code>processServerResponse()</code>, which are called by a {@code LicenseChecker} 148 instance when processing a response from the license server. It also declares an 149 enum called <code>LicenseResponse</code>, which specifies the license response 150 value passed in calls to <code>processServerResponse()</code>. </p> 151 152 <ul> 153 <li><code>processServerResponse()</code> lets you preprocess the raw response 154 data received from the licensing server, prior to determining whether to grant 155 access. 156 157 <p>A typical implementation would extract some or all fields from the license 158 response and store the data locally to a persistent store, such as through 159 {@link android.content.SharedPreferences} storage, to ensure that the data is 160 accessible across application invocations and device power cycles. For example, 161 a {@code Policy} would maintain the timestamp of the last successful license check, the 162 retry count, the license validity period, and similar information in a 163 persistent store, rather than resetting the values each time the application is 164 launched.</p> 165 166 <p>When storing response data locally, the {@code Policy} must ensure that the data is 167 obfuscated (see <a href="#impl-Obfuscator">Implementing an Obfuscator</a>, 168 below).</p></li> 169 170 <li><code>allowAccess()</code> determines whether to grant the user access to 171 your application, based on any available license response data (from the 172 licensing server or from cache) or other application-specific information. For 173 example, your implementation of <code>allowAccess()</code> could take into 174 account additional criteria, such as usage or other data retrieved from a 175 backend server. In all cases, an implementation of <code>allowAccess()</code> 176 should only return <code>true</code> if the user is licensed to use the 177 application, as determined by the licensing server, or if there is a transient 178 network or system problem that prevents the license check from completing. In 179 such cases, your implementation can maintain a count of retry responses and 180 provisionally allow access until the next license check is complete.</li> 181 182 </ul> 183 184 <p>To simplify the process of adding licensing to your application and to 185 provide an illustration of how a {@code Policy} should be designed, the LVL includes 186 two full {@code Policy} implementations that you can use without modification or 187 adapt to your needs:</p> 188 189 <ul> 190 <li><a href="#ServerManagedPolicy">ServerManagedPolicy</a>, a flexible {@code Policy} 191 that uses server-provided settings and cached responses to manage access across 192 varied network conditions, and</li> 193 <li><a href="#StrictPolicy">StrictPolicy</a>, which does not cache any response 194 data and allows access <em>only</em> if the server returns a licensed 195 response.</li> 196 </ul> 197 198 <p>For most applications, the use of ServerManagedPolicy is highly 199 recommended. ServerManagedPolicy is the LVL default and is integrated with 200 the LVL sample application.</p> 201 202 203 <h3 id="custom-policies">Guidelines for custom policies</h3> 204 205 <p>In your licensing implementation, you can use one of the complete policies 206 provided in the LVL (ServerManagedPolicy or StrictPolicy) or you can create a 207 custom policy. For any type of custom policy, there are several important design 208 points to understand and account for in your implementation.</p> 209 210 <p>The licensing server applies general request limits to guard against overuse 211 of resources that could result in denial of service. When an application exceeds 212 the request limit, the licensing server returns a 503 response, which gets 213 passed through to your application as a general server error. This means that no 214 license response will be available to the user until the limit is reset, which 215 can affect the user for an indefinite period.</p> 216 217 <p>If you are designing a custom policy, we recommend that the {@code Policy}: 218 <ol> 219 <!-- <li>Limits the number of points at which your app calls for a license check 220 to the minimum. </li> --> 221 <li>Caches (and properly obfuscates) the most recent successful license response 222 in local persistent storage.</li> 223 <li>Returns the cached response for all license checks, for as long as the 224 cached response is valid, rather than making a request to the licensing server. 225 Setting the response validity according to the server-provided <code>VT</code> 226 extra is highly recommended. See <a 227 href="{@docRoot}guide/google/play/licensing/licensing-reference.html#extras">Server Response Extras</a> 228 for more information.</li> 229 <li>Uses an exponential backoff period, if retrying any requests the result in 230 errors. Note that the Google Play client automatically retries failed 231 requests, so in most cases there is no need for your {@code Policy} to retry them.</li> 232 <li>Provides for a "grace period" that allows the user to access your 233 application for a limited time or number of uses, while a license check is being 234 retried. The grace period benefits the user by allowing access until the next 235 license check can be completed successfully and it benefits you by placing a 236 hard limit on access to your application when there is no valid license response 237 available.</li> 238 </ol> 239 240 <p>Designing your {@code Policy} according to the guidelines listed above is critical, 241 because it ensures the best possible experience for users while giving you 242 effective control over your application even in error conditions. </p> 243 244 <p>Note that any {@code Policy} can use settings provided by the licensing server to 245 help manage validity and caching, retry grace period, and more. Extracting the 246 server-provided settings is straightforward and making use of them is highly 247 recommended. See the ServerManagedPolicy implementation for an example of how to 248 extract and use the extras. For a list of server settings and information about 249 how to use them, see <a 250 href="{@docRoot}guide/google/play/licensing/licensing-reference.html#extras">Server Response 251 Extras</a>.</p> 252 253 <h3 id="ServerManagedPolicy">ServerManagedPolicy</h3> 254 255 <div class="sidebox-wrapper"> 256 <div class="sidebox"> 257 <h2>Server Response Extras</h2> 258 259 <p>For certain types of licensing responses, the licensing server appends extra 260 settings to the responses, to help the application manage licensing effectively. 261 </p> 262 263 <p style="margin-top:.5em;">See <a 264 href="{@docRoot}guide/google/play/licensing/licensing-reference.html#extras">Server Response Extras</a> 265 for 266 a list of settings and <code>ServerManagedPolicy.java</code> for information 267 about how a {@code Policy} can use the extras.</p> 268 269 </div> 270 </div> 271 272 <p>The LVL includes a full and recommended implementation of the {@code Policy} 273 interface called ServerManagedPolicy. The implementation is integrated with the 274 LVL classes and serves as the default {@code Policy} in the library. </p> 275 276 <p>ServerManagedPolicy provides all of the handling for license and retry 277 responses. It caches all of the response data locally in a 278 {@link android.content.SharedPreferences} file, obfuscating it with the 279 application's {@code Obfuscator} implementation. This ensures that the license response 280 data is secure and persists across device power cycles. ServerManagedPolicy 281 provides concrete implementations of the interface methods 282 <code>processServerResponse()</code> and <code>allowAccess()</code> and also 283 includes a set of supporting methods and types for managing license 284 responses.</p> 285 286 <p>Importantly, a key feature of ServerMangedPolicy is its use of 287 server-provided settings as the basis for managing licensing across an 288 application's refund period and through varying network and error conditions. 289 When an application contacts the Google Play server for a license check, the 290 server appends several settings as key-value pairs in the extras field of certain 291 license response types. For example, the server provides recommended values for the 292 application's license validity period, retry grace period, and maximum allowable 293 retry count, among others. ServerManagedPolicy extracts the values from the 294 license response in its <code>processServerResponse()</code> method and checks 295 them in its <code>allowAccess()</code> method. For a list of the server-provided 296 settings used by ServerManagedPolicy, see <a 297 href="{@docRoot}guide/google/play/licensing/licensing-reference.html#extras">Server Response 298 Extras</a>.</p> 299 300 <p>For convenience, best performance, and the benefit of using license settings 301 from the Google Play server, <strong>using ServerManagedPolicy as your 302 licensing {@code Policy} is strongly recommended</strong>. </p> 303 304 <p>If you are concerned about the security of license response data that is 305 stored locally in {@link android.content.SharedPreferences}, you can use a stronger obfuscation 306 algorithm or design a stricter {@code Policy} that does not store license data. The LVL 307 includes an example of such a {@code Policy} — see <a 308 href="#StrictPolicy">StrictPolicy</a> for more information.</p> 309 310 <p>To use ServerManagedPolicy, simply import it to your Activity, create an 311 instance, and pass a reference to the instance when constructing your 312 {@code LicenseChecker}. See <a href="#lc-lcc">Instantiate LicenseChecker and 313 LicenseCheckerCallback</a> for more information. </p> 314 315 <h3 id="StrictPolicy">StrictPolicy</h3> 316 317 <p>The LVL includes an alternative full implementation of the {@code Policy} interface 318 called StrictPolicy. The StrictPolicy implementation provides a more restrictive 319 Policy than ServerManagedPolicy, in that it does not allow the user to access 320 the application unless a license response is received from the server at the 321 time of access that indicates that the user is licensed.</p> 322 323 <p>The principal feature of StrictPolicy is that it does not store <em>any</em> 324 license response data locally, in a persistent store. Because no data is stored, 325 retry requests are not tracked and cached responses can not be used to fulfill 326 license checks. The {@code Policy} allows access only if:</p> 327 328 <ul> 329 <li>The license response is received from the licensing server, and </li> 330 <li>The license response indicates that the user is licensed to access the 331 application. </li> 332 </ul> 333 334 <p>Using StrictPolicy is appropriate if your primary concern is to ensure that, 335 in all possible cases, no user will be allowed to access the application unless 336 the user is confirmed to be licensed at the time of use. Additionally, the 337 Policy offers slightly more security than ServerManagedPolicy — since 338 there is no data cached locally, there is no way a malicious user could tamper 339 with the cached data and obtain access to the application.</p> 340 341 <p>At the same time, this {@code Policy} presents a challenge for normal users, since it 342 means that they won't be able to access the application when there is no network 343 (cell or Wi-Fi) connection available. Another side-effect is that your 344 application will send more license check requests to the server, since using a 345 cached response is not possible.</p> 346 347 <p>Overall, this policy represents a tradeoff of some degree of user convenience 348 for absolute security and control over access. Consider the tradeoff carefully 349 before using this {@code Policy}.</p> 350 351 <p>To use StrictPolicy, simply import it to your Activity, create an instance, 352 and pass a reference to it when constructing your {@code LicenseChecker}. See 353 <a href="#lc-lcc">Instantiate LicenseChecker and LicenseCheckerCallback</a> 354 for more information. </p> 355 356 <h2 id="impl-Obfuscator">Implementing an Obfuscator</h2> 357 358 <div class="sidebox-wrapper"> 359 <div class="sidebox"> 360 <h2>AESObfuscator</h2> 361 362 <p>The LVL includes a full {@code Obfuscator} implementation in the 363 <code>AESObfuscator.java</code> file. The {@code Obfuscator} uses AES encryption to 364 obfuscate/unobfuscate data. If you are using a {@code Policy} (such as 365 ServerManagedPolicy) that caches license response data, using AESObfuscator as 366 basis for your {@code Obfuscator} implementation is highly recommended. </p> 367 368 </div> 369 </div> 370 371 <p>A typical {@code Policy} implementation needs to save the license response data for 372 an application to a persistent store, so that it is accessible across 373 application invocations and device power cycles. For example, a {@code Policy} would 374 maintain the timestamp of the last successful license check, the retry count, 375 the license validity period, and similar information in a persistent store, 376 rather than resetting the values each time the application is launched. The 377 default {@code Policy} included in the LVL, ServerManagedPolicy, stores license response 378 data in a {@link android.content.SharedPreferences} instance, to ensure that the 379 data is persistent. </p> 380 381 <p>Because the {@code Policy} will use stored license response data to determine whether 382 to allow or disallow access to the application, it <em>must</em> ensure that any 383 stored data is secure and cannot be reused or manipulated by a root user on a 384 device. Specifically, the {@code Policy} must always obfuscate the data before storing 385 it, using a key that is unique for the application and device. Obfuscating using 386 a key that is both application-specific and device-specific is critical, because 387 it prevents the obfuscated data from being shared among applications and 388 devices.</p> 389 390 <p>The LVL assists the application with storing its license response data in a 391 secure, persistent manner. First, it provides an {@code Obfuscator} 392 interface that lets your application supply the obfuscation algorithm of its 393 choice for stored data. Building on that, the LVL provides the helper class 394 PreferenceObfuscator, which handles most of the work of calling the 395 application's {@code Obfuscator} class and reading and writing the obfuscated data in a 396 {@link android.content.SharedPreferences} instance. </p> 397 398 <p>The LVL provides a full {@code Obfuscator} implementation called 399 AESObfuscator that uses AES encryption to obfuscate data. You can 400 use AESObfuscator in your application without modification or you 401 can adapt it to your needs. For more information, see the next section.</p> 402 403 404 <h3 id="AESObfuscator">AESObfuscator</h3> 405 406 <p>The LVL includes a full and recommended implementation of the {@code Obfuscator} 407 interface called AESObfuscator. The implementation is integrated with the 408 LVL sample application and serves as the default {@code Obfuscator} in the library. </p> 409 410 <p>AESObfuscator provides secure obfuscation of data by using AES to 411 encrypt and decrypt the data as it is written to or read from storage. 412 The {@code Obfuscator} seeds the encryption using three data fields provided 413 by the application: </p> 414 415 <ol> 416 <li>A salt — an array of random bytes to use for each (un)obfuscation. </li> 417 <li>An application identifier string, typically the package name of the application.</li> 418 <li>A device identifier string, derived from as many device-specific sources 419 as possible, so as to make it as unique.</li> 420 </ol> 421 422 <p>To use AESObfuscator, first import it to your Activity. Declare a private 423 static final array to hold the salt bytes and initialize it to 20 randomly 424 generated bytes.</p> 425 426 <pre> ... 427 // Generate 20 random bytes, and put them here. 428 private static final byte[] SALT = new byte[] { 429 -46, 65, 30, -128, -103, -57, 74, -64, 51, 88, -95, 430 -45, 77, -117, -36, -113, -11, 32, -64, 89 431 }; 432 ... 433 </pre> 434 435 <p>Next, declare a variable to hold a device identifier and generate a value for 436 it in any way needed. For example, the sample application included in the LVL 437 queries the system settings for the 438 <code>android.Settings.Secure.ANDROID_ID</code>, which is unique to each device. 439 </p> 440 441 <p>Note that, depending on the APIs you use, your application might need to 442 request additional permissions in order to acquire device-specific information. 443 For example, to query the {@link android.telephony.TelephonyManager} to obtain 444 the device IMEI or related data, the application will also need to request the 445 <code>android.permission.READ_PHONE_STATE</code> permission in its manifest.</p> 446 447 <p>Before requesting new permissions for the <em>sole purpose</em> of acquiring 448 device-specific information for use in your {@code Obfuscator}, consider 449 how doing so might affect your application or its filtering on Google Play 450 (since some permissions can cause the SDK build tools to add 451 the associated <code><uses-feature></code>).</p> 452 453 <p>Finally, construct an instance of AESObfuscator, passing the salt, 454 application identifier, and device identifier. You can construct the instance 455 directly, while constructing your {@code Policy} and {@code LicenseChecker}. For example:</p> 456 457 <pre> ... 458 // Construct the LicenseChecker with a Policy. 459 mChecker = new LicenseChecker( 460 this, new ServerManagedPolicy(this, 461 new AESObfuscator(SALT, getPackageName(), deviceId)), 462 BASE64_PUBLIC_KEY // Your public licensing key. 463 ); 464 ... 465 </pre> 466 467 <p>For a complete example, see MainActivity in the LVL sample application.</p> 468 469 470 <h2 id="impl-lc">Checking the License from an Activity</h2> 471 472 <p>Once you've implemented a {@code Policy} for managing access to your application, the 473 next step is to add a license check to your application, which initiates a query 474 to the licensing server if needed and manages access to the application based on 475 the license response. All of the work of adding the license check and handling 476 the response takes place in your main {@link android.app.Activity} source file. 477 </p> 478 479 <p>To add the license check and handle the response, you must:</p> 480 481 <ol> 482 <li><a href="#imports">Add imports</a></li> 483 <li><a href="#lc-impl">Implement LicenseCheckerCallback</a> as a private inner class</li> 484 <li><a href="#thread-handler">Create a Handler</a> for posting from LicenseCheckerCallback to the UI thread</li> 485 <li><a href="#lc-lcc">Instantiate LicenseChecker</a> and LicenseCheckerCallback</li> 486 <li><a href="#check-access">Call checkAccess()</a> to initiate the license check</li> 487 <li><a href="#account-key">Embed your public key</a> for licensing</li> 488 <li><a href="#handler-cleanup">Call your LicenseChecker's onDestroy() method</a> to close IPC connections.</li> 489 </ol> 490 491 <p>The sections below describe these tasks. </p> 492 493 <h3 id="lc-overview">Overview of license check and response</h3> 494 495 <div class="sidebox-wrapper"> 496 <div class="sidebox"> 497 <h2>Example: MainActivity</h2> 498 499 <p>The sample application included with the LVL provides a full example of how 500 to initiate a license check and handle the result, in the 501 <code>MainActivity.java</code> file.</p> 502 503 </div> 504 </div> 505 506 <p>In most cases, you should add the license check to your application's main 507 {@link android.app.Activity}, in the {@link android.app.Activity#onCreate onCreate()} method. This 508 ensures that when the user launches your application directly, the license check 509 will be invoked immediately. In some cases, you can add license checks in other 510 locations as well. For example, if your application includes multiple Activity 511 components that other applications can start by {@link android.content.Intent}, 512 you could add license checks in those Activities.</p> 513 514 <p>A license check consists of two main actions: </p> 515 516 <ul> 517 <li>A call to a method to initiate the license check — in the LVL, this is 518 a call to the <code>checkAccess()</code> method of a {@code LicenseChecker} object that 519 you construct.</li> 520 <li>A callback that returns the result of the license check. In the LVL, this is 521 a <code>LicenseCheckerCallback</code> interface that you implement. The 522 interface declares two methods, <code>allow()</code> and 523 <code>dontAllow()</code>, which are invoked by the library based on to the 524 result of the license check. You implement these two methods with whatever logic 525 you need, to allow or disallow the user access to your application. Note that 526 these methods do not determine <em>whether</em> to allow access — that 527 determination is the responsibility of your {@code Policy} implementation. Rather, these 528 methods simply provide the application behaviors for <em>how</em> to allow and 529 disallow access (and handle application errors). 530 <p>The <code>allow()</code> and <code>dontAllow()</code> methods do provide a "reason" 531 for their response, which can be one of the {@code Policy} values, {@code LICENSED}, 532 {@code NOT_LICENSED}, or {@code RETRY}. In particular, you should handle the case in which 533 the method receives the {@code RETRY} response for {@code dontAllow()} and provide the user with an 534 "Retry" button, which might have happened because the service was unavailable during the 535 request.</p></li> 536 </ul> 537 538 <div style="margin-bottom:2em;"> 539 540 <img src="{@docRoot}images/licensing_flow.png" style="text-align:left;margin-bottom:0;margin-left:3em;" /> 541 <div style="margin:.5em 0 1.5em 2em;padding:0"><strong>Figure 6.</strong> Overview of a 542 typical license check interaction.</div> 543 </div> 544 545 <p>The diagram above illustrates how a typical license check takes place: </p> 546 547 <ol> 548 <li>Code in the application's main Activity instantiates {@code LicenseCheckerCallback} 549 and {@code LicenseChecker} objects. When constructing {@code LicenseChecker}, the code passes in 550 {@link android.content.Context}, a {@code Policy} implementation to use, and the 551 publisher account's public key for licensing as parameters. </li> 552 <li>The code then calls the <code>checkAccess()</code> method on the 553 {@code LicenseChecker} object. The method implementation calls the {@code Policy} to determine 554 whether there is a valid license response cached locally, in 555 {@link android.content.SharedPreferences}. 556 <ul> 557 <li>If so, the <code>checkAccess()</code> implementation calls 558 <code>allow()</code>.</li> 559 <li>Otherwise, the {@code LicenseChecker} initiates a license check request that is sent 560 to the licensing server.</li> 561 </ul> 562 563 <p class="note"><strong>Note:</strong> The licensing server always returns 564 <code>LICENSED</code> when you perform a license check of a draft application.</p> 565 </li> 566 <li>When a response is received, {@code LicenseChecker} creates a LicenseValidator that 567 verifies the signed license data and extracts the fields of the response, then 568 passes them to your {@code Policy} for further evaluation. 569 <ul> 570 <li>If the license is valid, the {@code Policy} caches the response in 571 {@link android.content.SharedPreferences} and notifies the validator, which then calls the 572 <code>allow()</code> method on the {@code LicenseCheckerCallback} object. </li> 573 <li>If the license not valid, the {@code Policy} notifies the validator, which calls 574 the <code>dontAllow()</code> method on {@code LicenseCheckerCallback}. </li> 575 </ul> 576 </li> 577 <li>In case of a recoverable local or server error, such as when the network is 578 not available to send the request, {@code LicenseChecker} passes a {@code RETRY} response to 579 your {@code Policy} object's <code>processServerResponse()</code> method. 580 <p>Also, both the {@code allow()} and {@code dontAllow()} callback methods receive a 581 <code>reason</code> argument. The {@code allow()} method's reason is usually {@code 582 Policy.LICENSED} or {@code Policy.RETRY} and the {@code dontAllow()} reason is usually {@code 583 Policy.NOT_LICENSED} or {@code Policy.RETRY}. These response values are useful so you can show 584 an appropriate response for the user, such as by providing a "Retry" button when {@code 585 dontAllow()} responds with {@code Policy.RETRY}, which might have been because the service was 586 unavailable.</p></li> 587 <li>In case of a application error, such as when the application attempts to 588 check the license of an invalid package name, {@code LicenseChecker} passes an error 589 response to the LicenseCheckerCallback's <code>applicationError()</code> 590 method. </li> 591 </ol> 592 593 <p>Note that, in addition to initiating the license check and handling the 594 result, which are described in the sections below, your application also needs 595 to provide a <a href="#impl-Policy">Policy implementation</a> and, if the {@code Policy} 596 stores response data (such as ServerManagedPolicy), an <a 597 href="#impl-Obfuscator">Obfuscator</a> implementation. </p> 598 599 600 <h3 id="imports">Add imports</h3> 601 602 <p>First, open the class file of the application's main Activity and import 603 {@code LicenseChecker} and {@code LicenseCheckerCallback} from the LVL package.</p> 604 605 <pre> import com.android.vending.licensing.LicenseChecker; 606 import com.android.vending.licensing.LicenseCheckerCallback;</pre> 607 608 <p>If you are using the default {@code Policy} implementation provided with the LVL, 609 ServerManagedPolicy, import it also, together with the AESObfuscator. If you are 610 using a custom {@code Policy} or {@code Obfuscator}, import those instead. </p> 611 612 <pre> import com.android.vending.licensing.ServerManagedPolicy; 613 import com.android.vending.licensing.AESObfuscator;</pre> 614 615 <h3 id="lc-impl">Implement LicenseCheckerCallback as a private inner class</h3> 616 617 <p>{@code LicenseCheckerCallback} is an interface provided by the LVL for handling 618 result of a license check. To support licensing using the LVL, you must 619 implement {@code LicenseCheckerCallback} and 620 its methods to allow or disallow access to the application.</p> 621 622 <p>The result of a license check is always a call to one of the 623 {@code LicenseCheckerCallback} methods, made based on the validation of the response 624 payload, the server response code itself, and any additional processing provided 625 by your {@code Policy}. Your application can implement the methods in any way needed. In 626 general, it's best to keep the methods simple, limiting them to managing UI 627 state and application access. If you want to add further processing of license 628 responses, such as by contacting a backend server or applying custom constraints, 629 you should consider incorporating that code into your {@code Policy}, rather than 630 putting it in the {@code LicenseCheckerCallback} methods. </p> 631 632 <p>In most cases, you should declare your implementation of 633 {@code LicenseCheckerCallback} as a private class inside your application's main 634 Activity class. </p> 635 636 <p>Implement the <code>allow()</code> and <code>dontAllow()</code> methods as 637 needed. To start with, you can use simple result-handling behaviors in the 638 methods, such as displaying the license result in a dialog. This helps you get 639 your application running sooner and can assist with debugging. Later, after you 640 have determined the exact behaviors you want, you can add more complex handling. 641 </p> 642 643 <p>Some suggestions for handling unlicensed responses in 644 <code>dontAllow()</code> include: </p> 645 646 <ul> 647 <li>Display a "Try again" dialog to the user, including a button to initiate a 648 new license check if the <code>reason</code> supplied is {@code Policy.RETRY}. </li> 649 <li>Display a "Purchase this application" dialog, including a button that 650 deep-links the user to the application's details page on Google Play, from which the 651 use can purchase the application. For more information on how to set up such 652 links, see <a 653 href="{@docRoot}distribute/googleplay/promote/linking.html">Linking to Your Products</a>. </li> 654 <li>Display a Toast notification that indicates that the features of the 655 application are limited because it is not licensed. </li> 656 </ul> 657 658 <p>The example below shows how the LVL sample application implements 659 {@code LicenseCheckerCallback}, with methods that display the license check result in a 660 dialog. </p> 661 662 <pre> 663 private class MyLicenseCheckerCallback implements LicenseCheckerCallback { 664 public void allow(int reason) { 665 if (isFinishing()) { 666 // Don't update UI if Activity is finishing. 667 return; 668 } 669 // Should allow user access. 670 displayResult(getString(R.string.allow)); 671 } 672 673 public void dontAllow(int reason) { 674 if (isFinishing()) { 675 // Don't update UI if Activity is finishing. 676 return; 677 } 678 displayResult(getString(R.string.dont_allow)); 679 680 if (reason == Policy.RETRY) { 681 // If the reason received from the policy is RETRY, it was probably 682 // due to a loss of connection with the service, so we should give the 683 // user a chance to retry. So show a dialog to retry. 684 showDialog(DIALOG_RETRY); 685 } else { 686 // Otherwise, the user is not licensed to use this app. 687 // Your response should always inform the user that the application 688 // is not licensed, but your behavior at that point can vary. You might 689 // provide the user a limited access version of your app or you can 690 // take them to Google Play to purchase the app. 691 showDialog(DIALOG_GOTOMARKET); 692 } 693 } 694 } 695 </pre> 696 697 <p>Additionally, you should implement the <code>applicationError()</code> 698 method, which the LVL calls to let your application handle errors that are not 699 retryable. For a list of such errors, see <a 700 href="{@docRoot}guide/google/play/licensing/licensing-reference.html#server-response-codes">Server 701 Response Codes</a> in the <a 702 href="guide/google/play/licensing/licensing-reference.html">Licensing Reference</a>. You can implement 703 the method in any way needed. In most cases, the 704 method should log the error code and call <code>dontAllow()</code>.</p> 705 706 <h3 id="thread-handler">Create a Handler for posting from LicenseCheckerCallback 707 to the UI thread</h3> 708 709 <p>During a license check, the LVL passes the request to the Google Play 710 application, which handles communication with the licensing server. The LVL 711 passes the request over asynchronous IPC (using {@link android.os.Binder}) so 712 the actual processing and network communication do not take place on a thread 713 managed by your application. Similarly, when the Google Play application 714 receives the result, it invokes a callback method over IPC, which in turn 715 executes in an IPC thread pool in your application's process.</p> 716 717 <p>The {@code LicenseChecker} class manages your application's IPC communication with 718 the Google Play application, including the call that sends the request and 719 the callback that receives the response. {@code LicenseChecker} also tracks open license 720 requests and manages their timeouts. </p> 721 722 <p>So that it can handle timeouts properly and also process incoming responses 723 without affecting your application's UI thread, {@code LicenseChecker} spawns a 724 background thread at instantiation. In the thread it does all processing of 725 license check results, whether the result is a response received from the server 726 or a timeout error. At the conclusion of processing, the LVL calls your 727 {@code LicenseCheckerCallback} methods from the background thread. </p> 728 729 <p>To your application, this means that:</p> 730 731 <ol> 732 <li>Your {@code LicenseCheckerCallback} methods will be invoked, in many cases, from a 733 background thread.</li> 734 <li>Those methods won't be able to update state or invoke any processing in the 735 UI thread, unless you create a Handler in the UI thread and have your callback 736 methods post to the Handler.</li> 737 </ol> 738 739 <p>If you want your {@code LicenseCheckerCallback} methods to update the UI thread, 740 instantiate a {@link android.os.Handler} in the main Activity's 741 {@link android.app.Activity#onCreate(android.os.Bundle) onCreate()} method, 742 as shown below. In this example, the LVL sample application's 743 {@code LicenseCheckerCallback} methods (see above) call <code>displayResult()</code> to 744 update the UI thread through the Handler's 745 {@link android.os.Handler#post(java.lang.Runnable) post()} method.</p> 746 747 <pre>private Handler mHandler; 748 749 @Override 750 public void onCreate(Bundle savedInstanceState) { 751 ... 752 mHandler = new Handler(); 753 } 754 </pre> 755 756 <p>Then, in your {@code LicenseCheckerCallback} methods, you can use Handler methods to 757 post Runnable or Message objects to the Handler. Here's how the sample 758 application included in the LVL posts a Runnable to a Handler in the UI thread 759 to display the license status.</p> 760 761 <pre> private void displayResult(final String result) { 762 mHandler.post(new Runnable() { 763 public void run() { 764 mStatusText.setText(result); 765 setProgressBarIndeterminateVisibility(false); 766 mCheckLicenseButton.setEnabled(true); 767 } 768 }); 769 } 770 </pre> 771 772 <h3 id="lc-lcc">Instantiate LicenseChecker and LicenseCheckerCallback</h3> 773 774 <p>In the main Activity's 775 {@link android.app.Activity#onCreate(android.os.Bundle) onCreate()} method, 776 create private instances of LicenseCheckerCallback and {@code LicenseChecker}. You must 777 instantiate {@code LicenseCheckerCallback} first, because you need to pass a reference 778 to that instance when you call the constructor for {@code LicenseChecker}. </p> 779 780 <p>When you instantiate {@code LicenseChecker}, you need to pass in these parameters:</p> 781 782 <ul> 783 <li>The application {@link android.content.Context}</li> 784 <li>A reference to the {@code Policy} implementation to use for the license check. In 785 most cases, you would use the default {@code Policy} implementation provided by the LVL, 786 ServerManagedPolicy. </li> 787 <li>The String variable holding your publisher account's public key for 788 licensing. </li> 789 </ul> 790 791 <p>If you are using ServerManagedPolicy, you won't need to access the class 792 directly, so you can instantiate it in the {@code LicenseChecker} constructor, 793 as shown in the example below. Note that you need to pass a reference to a new 794 Obfuscator instance when you construct ServerManagedPolicy.</p> 795 796 <p>The example below shows the instantiation of {@code LicenseChecker} and 797 {@code LicenseCheckerCallback} from the <code>onCreate()</code> method of an Activity 798 class. </p> 799 800 <pre>public class MainActivity extends Activity { 801 ... 802 private LicenseCheckerCallback mLicenseCheckerCallback; 803 private LicenseChecker mChecker; 804 805 @Override 806 public void onCreate(Bundle savedInstanceState) { 807 super.onCreate(savedInstanceState); 808 ... 809 // Construct the LicenseCheckerCallback. The library calls this when done. 810 mLicenseCheckerCallback = new MyLicenseCheckerCallback(); 811 812 // Construct the LicenseChecker with a Policy. 813 mChecker = new LicenseChecker( 814 this, new ServerManagedPolicy(this, 815 new AESObfuscator(SALT, getPackageName(), deviceId)), 816 BASE64_PUBLIC_KEY // Your public licensing key. 817 ); 818 ... 819 } 820 } 821 </pre> 822 823 824 <p>Note that {@code LicenseChecker} calls the {@code LicenseCheckerCallback} methods from the UI 825 thread <em>only</em> if there is valid license response cached locally. If the 826 license check is sent to the server, the callbacks always originate from the 827 background thread, even for network errors. </p> 828 829 830 <h3 id="check-access">Call checkAccess() to initiate the license check</h3> 831 832 <p>In your main Activity, add a call to the <code>checkAccess()</code> method of the 833 {@code LicenseChecker} instance. In the call, pass a reference to your 834 {@code LicenseCheckerCallback} instance as a parameter. If you need to handle any 835 special UI effects or state management before the call, you might find it useful 836 to call <code>checkAccess()</code> from a wrapper method. For example, the LVL 837 sample application calls <code>checkAccess()</code> from a 838 <code>doCheck()</code> wrapper method:</p> 839 840 <pre> @Override 841 public void onCreate(Bundle savedInstanceState) { 842 super.onCreate(savedInstanceState); 843 ... 844 // Call a wrapper method that initiates the license check 845 doCheck(); 846 ... 847 } 848 ... 849 private void doCheck() { 850 mCheckLicenseButton.setEnabled(false); 851 setProgressBarIndeterminateVisibility(true); 852 mStatusText.setText(R.string.checking_license); 853 mChecker.checkAccess(mLicenseCheckerCallback); 854 } 855 </pre> 856 857 858 <h3 id="account-key">Embed your public key for licensing</h3> 859 860 <p>For each publisher account, the Google Play service automatically 861 generates a 2048-bit RSA public/private key pair that is used exclusively for 862 licensing. The key pair is uniquely associated with the publisher account and is 863 shared across all applications that are published through the account. Although 864 associated with a publisher account, the key pair is <em>not</em> the same as 865 the key that you use to sign your applications (or derived from it).</p> 866 867 <p>The Google Play publisher site exposes the public key for licensing to any 868 developer signed in to the publisher account, but it keeps the private key 869 hidden from all users in a secure location. When an application requests a 870 license check for an application published in your account, the licensing server 871 signs the license response using the private key of your account's key pair. 872 When the LVL receives the response, it uses the public key provided by the 873 application to verify the signature of the license response. </p> 874 875 <p>To add licensing to an application, you must obtain your publisher account's 876 public key for licensing and copy it into your application. Here's how to find 877 your account's public key for licensing:</p> 878 879 <ol> 880 <li>Go to the Google Play <a 881 href="http://play.google.com/apps/publish">publisher site</a> and sign in. 882 Make sure that you sign in to the account from which the application you are 883 licensing is published (or will be published). </li> 884 <li>In the account home page, locate the "Edit profile" link and click it. </li> 885 <li>In the Edit Profile page, locate the "Licensing" pane, shown below. Your 886 public key for licensing is given in the "Public key" text box. </li> 887 </ol> 888 889 <p>To add the public key to your application, simply copy/paste the key string 890 from the text box into your application as the value of the String variable 891 <code>BASE64_PUBLIC_KEY</code>. When you are copying, make sure that you have 892 selected the entire key string, without omitting any characters. </p> 893 894 <p>Here's an example from the LVL sample application:</p> 895 896 <pre> public class MainActivity extends Activity { 897 private static final String BASE64_PUBLIC_KEY = "MIIBIjANBgkqhkiG ... "; //truncated for this example 898 ... 899 } 900 </pre> 901 902 <h3 id="handler-cleanup">Call your LicenseChecker's onDestroy() method 903 to close IPC connections</h3> 904 905 <p>Finally, to let the LVL clean up before your application 906 {@link android.content.Context} changes, add a call to the {@code LicenseChecker}'s 907 <code>onDestroy()</code> method from your Activity's 908 {@link android.app.Activity#onDestroy()} implementation. The call causes the 909 {@code LicenseChecker} to properly close any open IPC connection to the Google Play 910 application's ILicensingService and removes any local references to the service 911 and handler.</p> 912 913 <p>Failing to call the {@code LicenseChecker}'s <code>onDestroy()</code> method 914 can lead to problems over the lifecycle of your application. For example, if the 915 user changes screen orientation while a license check is active, the application 916 {@link android.content.Context} is destroyed. If your application does not 917 properly close the {@code LicenseChecker}'s IPC connection, your application will crash 918 when the response is received. Similarly, if the user exits your application 919 while a license check is in progress, your application will crash when the 920 response is received, unless it has properly called the 921 {@code LicenseChecker}'s <code>onDestroy()</code> method to disconnect from the service. 922 </p> 923 924 <p>Here's an example from the sample application included in the LVL, where 925 <code>mChecker</code> is the {@code LicenseChecker} instance:</p> 926 927 <pre> @Override 928 protected void onDestroy() { 929 super.onDestroy(); 930 mChecker.onDestroy(); 931 ... 932 } 933 </pre> 934 935 <p>If you are extending or modifying {@code LicenseChecker}, you might also need to call 936 the {@code LicenseChecker}'s <code>finishCheck()</code> method, to clean up any open IPC 937 connections.</p> 938 939 <h2 id="impl-DeviceLimiter">Implementing a DeviceLimiter</h2> 940 941 <p>In some cases, you might want your {@code Policy} to limit the number of actual 942 devices that are permitted to use a single license. This would prevent a user 943 from moving a licensed application onto a number of devices and using the 944 application on those devices under the same account ID. It would also prevent a 945 user from "sharing" the application by providing the account information 946 associated with the license to other individuals, who could then sign in to that 947 account on their devices and access the license to the application. </p> 948 949 <p>The LVL supports per-device licensing by providing a 950 <code>DeviceLimiter</code> interface, which declares a single method, 951 <code>allowDeviceAccess()</code>. When a LicenseValidator is handling a response 952 from the licensing server, it calls <code>allowDeviceAccess()</code>, passing a 953 user ID string extracted from the response.</p> 954 955 <p>If you do not want to support device limitation, <strong>no work is 956 required</strong> — the {@code LicenseChecker} class automatically uses a default 957 implementation called NullDeviceLimiter. As the name suggests, NullDeviceLimiter 958 is a "no-op" class whose <code>allowDeviceAccess()</code> method simply returns 959 a <code>LICENSED</code> response for all users and devices. </p> 960 961 <div style="border-left:4px solid #FFCF00;margin:1em;padding: 0 0 0 .5em"> 962 <p><strong>Caution:</strong> Per-device licensing is <em>not recommended for 963 most applications</em> because:</p> 964 <ul> 965 <li>It requires that you provide a backend server to manage a users and devices 966 mapping, and </li> 967 <li>It could inadvertently result in a user being denied access to an 968 application that they have legitimately purchased on another device.</li> 969 </ul> 970 </div> 971 972 973 974 975 976 977 978 979 980 981 982 <h2 id="app-obfuscation">Obfuscating Your Code</h2> 983 984 <p>To ensure the security of your application, particularly for a paid 985 application that uses licensing and/or custom constraints and protections, it's 986 very important to obfuscate your application code. Properly obfuscating your 987 code makes it more difficult for a malicious user to decompile the application's 988 bytecode, modify it — such as by removing the license check — 989 and then recompile it.</p> 990 991 <p>Several obfuscator programs are available for Android applications, including 992 <a href="http://proguard.sourceforge.net/">ProGuard</a>, which also offers 993 code-optimization features. The use of ProGuard or a similar program to obfuscate 994 your code is <em>strongly recommended</em> for all applications that use Google 995 Play Licensing. </p> 996 997 <h2 id="app-publishing">Publishing a Licensed Application</h2> 998 999 <p>When you are finished testing your license implementation, you are ready to 1000 publish the application on Google Play. Follow the normal steps to <a 1001 href="{@docRoot}tools/publishing/preparing.html">prepare</a>, <a 1002 href="{@docRoot}tools/publishing/app-signing.html">sign</a>, and then <a 1003 href="{@docRoot}distribute/googleplay/publish/preparing.html">publish the application</a>. 1004 </p> 1005 1006 <h3>Removing Copy Protection</h3> 1007 1008 <p>After uploading your licensed application, remember to remove copy protection 1009 from the application, if it is currently used. To check and remove copy 1010 protection, sign in to the publisher site and go the application's upload 1011 details page. In the Publishing options section, make sure that the Copy 1012 Protection radio button selection is "Off".</p> 1013 1014 1015 <h2 id="support">Where to Get Support</h2> 1016 1017 <p>If you have questions or encounter problems while implementing or deploying 1018 publishing in your applications, please use the support resources listed in the 1019 table below. By directing your queries to the correct forum, you can get the 1020 support you need more quickly. </p> 1021 1022 <p class="table-caption"><strong>Table 2.</strong> Developer support resources 1023 for Google Play Licensing Service.</p> 1024 1025 <table> 1026 1027 <tr> 1028 <th>Support Type</th> 1029 <th>Resource</th> 1030 <th>Range of Topics</th> 1031 </tr> 1032 <tr> 1033 <td rowspan="2">Development and testing issues</td> 1034 <td>Google Groups: <a 1035 href="http://groups.google.com/group/android-developers">android-developers</a> 1036 </td> 1037 <td rowspan="2">LVL download and integration, library projects, {@code Policy} 1038 questions, user experience ideas, handling of responses, {@code Obfuscator}, IPC, test 1039 environment setup</td> 1040 </tr> 1041 <tr> 1042 <td>Stack Overflow: <a 1043 href="http://stackoverflow.com/questions/tagged/android">http://stackoverflow.com/questions/tagged/android</a></td> 1044 </tr> 1045 <tr> 1046 <td rowspan="2">Accounts, publishing, and deployment issues</td> 1047 <td><a href="http://www.google.com/support/forum/p/Android+Market">Google Play 1048 Help Forum</a></td> 1049 <td rowspan="2">Publisher accounts, licensing key pair, test accounts, server 1050 responses, test responses, application deployment and results</td> 1051 </tr> 1052 <tr> 1053 <td><a 1054 href="http://market.android.com/support/bin/answer.py?answer=186113">Market 1055 Licensing Support FAQ</a></td> 1056 </tr> 1057 <tr> 1058 <td>LVL issue tracker</td> 1059 <td><a href="http://code.google.com/p/marketlicensing/issues/">Marketlicensing 1060 project issue tracker</a></td> 1061 <td>Bug and issue reports related specifically to the LVL source code classes 1062 and interface implementations</td> 1063 </tr> 1064 1065 </table> 1066 1067 <p>For general information about how to post to the groups listed above, see <a 1068 href="{@docRoot}resources/community-groups.html">Developer Forums</a> document 1069 in the Resources tab.</p> 1070 1071 1072