1 page.title=Subscriptions 2 parent.title=In-app Billing 3 parent.link=index.html 4 @jd:body 5 6 <div id="qv-wrapper"> 7 <div id="qv"> 8 <h2>In this document</h2> 9 <ol> 10 <li><a href="#overview">Overview of Subscriptions</a> 11 <!--<ol> 12 <li><a href="#publishing">Subscription publishing and unpublishing</a></li> 13 <li><a href="#pricing">Subscription pricing</a></li> 14 <li><a href="#user-billing">User billing</a></li> 15 <li><a href="#cancellation">Subscription cancellation</a></li> 16 <li><a href="#uninstallation">App uninstallation</a></li> 17 <li><a href="#refunds">Refunds</a></li> 18 <li><a href="#payment">Payment processing and policies</a></li> 19 <li><a href="#requirements">System requirements for subscriptions</a></li> 20 <li><a href="#compatibility">Compatibility considerations</a></li> 21 </ol> --> 22 </li> 23 <li><a href="#implementing">Implementing Subscriptions</a> 24 <!-- <ol> 25 <li><a href="#sample">Sample application</a></li> 26 <li><a href="#model">Application model</a></li> 27 <li><a href="#token">Purchase token</a></li> 28 <li><a href="#version">Checking the In-app Billing API version</a></li> 29 <li><a href="purchase">Requesting purchase of a subscription</a></li> 30 <li><a href="#restore">Restoring transactions</a></li> 31 <li><a href="#validity">Checking subscription validity</a></li> 32 <li><a href="#viewstatus">Launching your product page to let the user cancel or view status</a></li> 33 <li><a href="#purchase-state-changes">Recurring billing and changes in purchase state</a></li> 34 <li><a href="modifying">Modifying your app for subscriptions</a></li> 35 </ol> --> 36 </li> 37 <li><a href="#administering">Administering Subscriptions</a></li> 38 39 <li><a href="#play-dev-api">Google Play Android Developer API</a> 40 <!-- <ol> 41 <li><a href="#using">Using the API</a></li> 42 <li><a href="#quota">Quota</a></li> 43 <li><a href="#auth">Authorization</a></li> 44 <li><a href="#practices">Using the API efficiently</a></li> 45 </ol> --> 46 </li> 47 </ol> 48 <h2>Downloads</h2> 49 <ol> 50 <li><a href="{@docRoot}guide/google/play/billing/billing_integrate.html#billing-download">Sample Application</a></li> 51 </ol> 52 <h2>See also</h2> 53 <ol> 54 <li><a href="{@docRoot}guide/google/play/billing/billing_overview.html">Overview of In-app 55 Billing</a></li> 56 <li><a href="{@docRoot}guide/google/play/billing/billing_best_practices.html">Security and 57 Design</a></li> 58 <li><a href="{@docRoot}guide/google/play/billing/billing_testing.html">Testing In-app 59 Billing</a></li> 60 <li><a href="{@docRoot}guide/google/play/billing/billing_admin.html">Administering In-app 61 Billing</a></li> 62 <li><a href="{@docRoot}guide/google/play/billing/billing_reference.html">In-app Billing 63 Reference</a></li> 64 </ol> 65 </div> 66 </div> 67 68 <p>Subscriptions let you sell content, services, or features in your app with 69 automated, recurring billing. Adding support for subscriptions is 70 straightforward and you can easily adapt an existing In-app Billing 71 implementation to sell subscriptions. </p> 72 73 <p>If you have already implemented In-app Billing for one-time purchase 74 products, you will find that you can add support for subscriptions with minimal 75 impact on your code. If you are new to In-app Billing, you can implement 76 subscriptions using the standard communication model, data structures, and user 77 interactions as for other in-app products.subscriptions. Because the 78 implementation of subscriptions follows the same path as for other in-app 79 products, details are provided outside of this document, starting with the <a 80 href="{@docRoot}guide/google/play/billing/billing_overview.html">In-app Billing 81 Overview</a>. </p> 82 83 <p>This document is focused on highlighting implementation details that are 84 specific to subscriptions, along with some strategies for the associated billing 85 and business models.</p> 86 87 <h2 id="overview">Overview of Subscriptions</h2> 88 89 <p>A <em>subscription</em> is a new product type offered in In-app Billing that lets you 90 sell content, services, or features to users from inside your app with recurring 91 monthly or annual billing. You can sell subscriptions to almost any type of 92 digital content, from any type of app or game.</p> 93 94 <p>As with other in-app products, you configure and publish subscriptions using 95 the Developer Console and then sell them from inside apps installed on an 96 Android-powered devices. In the Developer console, you create subscription 97 products and add them to a product list, setting a price for each, choosing a 98 billing interval of monthly or annually, and then publishing. In your apps, its 99 straightforward to add support for subscription purchases. The implementation 100 extends the standard In-app Billing API to support a new product type but uses 101 the same communication model, data structures, and user interactions as for 102 other in-app products.</p> 103 104 <p>When users purchase subscriptions in your apps, Google Play handles all 105 checkout details so your apps never have to directly process any financial 106 transactions. Google Play processes all payments for subscriptions through 107 Google Wallet, just as it does for standard in-app products and app purchases. 108 This ensures a consistent and familiar purchase flow for your users.</p> 109 110 <img src="{@docRoot}images/billing_subscription_flow.png" style="border:4px solid ddd;"> 111 112 113 <p>After users have purchase subscriptions, they can view the subscriptions and 114 cancel them, if necessary, from the My Apps screen in the Play Store app or 115 from the app's product details page in the Play Store app.</p> 116 117 <!--<img src="{@docRoot}images/billing_subscription_cancel.png" style="border:4px solid ddd;">--> 118 119 <p>Once users have purchased a subscription through In-app Billing, you can 120 easily give them extended access to additional content on your web site (or 121 other service) through the use of a server-side API provided for In-app Billing. 122 The server-side API lets you validate the status of a subscription when users 123 sign into your other services. For more information about the API, see <a 124 href="#play-dev-api">Google Play Android Developer API</a>, below. </p> 125 126 <p>You can also build on your existing external subscriber base from inside your 127 Android apps. If you sell subscriptions on a web site, for example, you can add 128 your own business logic to your Android app to determine whether the user has 129 already purchased a subscription elsewhere, then allow access to your content if 130 so or offer a subscription purchase from Google Play if not.</p> 131 132 <p>With the flexibility of In-app Billing, you can even implement your own 133 solution for sharing subscriptions across as many different apps or products as 134 you want. For example, you could sell a subscription that gives a subscriber 135 access to an entire collection of apps, games, or other content for a monthly or 136 annual fee. To implement this solution, you could add your own business logic to 137 your app to determine whether the user has already purchased a given 138 subscription and if so, allow access to your content. </p> 139 140 <div class="sidebox-wrapper"> 141 <div class="sidebox"> 142 <h2>Subscriptions at a glance</h2> 143 <ul> 144 <li>Subscriptions let you sell products with automated, recurring billing</li> 145 <li>You can set up subscriptions with either monthly or annual billing</li> 146 <li>You can sell multiple subscription items in an app with various billing 147 intervals or prices, such as for promotions</li> 148 <li>Users purchase your subscriptions from inside your apps, rather than 149 directly from Google Play</li> 150 <li>Users manage their purchased subscriptions from the My Apps screen in 151 the Play Store app</li> 152 <li>Google Play uses the original form of payment for recurring billing</li> 153 <li>If a user cancels a subscription, Google Play considers the subscription valid 154 until the end of the current billing cycle. The user continues to enjoy the content 155 for the rest of the cycle and is not granted a refund.</li> 156 </ul> 157 </div> 158 </div> 159 160 <p>In general the same basic policies and terms apply to subscriptions as to 161 standard in-app products, however there are some differences. For complete 162 information about the current policies and terms, please read the <a 163 href="http://support.google.com/googleplay/android-developer/bin/answer.py?hl=en 164 &answer=140504">policies document</a>.</p> 165 166 167 <h3 id="publishing">Subscription publishing and unpublishing</h3> 168 169 <p>To sell a subscription in an app, you use the tools in the Developer Console 170 to set up a product list for the app and then create and configure a new 171 subscription. In the subscription, you set the price and billing interval and 172 define a subscription ID, title, and description. When you are ready, you can 173 then publish the subscription in the app product list.</p> 174 175 <p>In the product list, you can add subscriptions, in-app products, or both. You 176 can add multiple subscriptions that give access to different content or 177 services, or you can add multiple subscriptions that give access to the same 178 content but for different intervals or different prices, such as for a 179 promotion. For example, a news outlet might decide to offer both monthly and 180 annual subscriptions to the same content, with annual having a discount. You can 181 also offer in-app purchase equivalents for subscription products, to ensure that 182 your content is available to users of older devices that do not support 183 subscriptions.</p> 184 185 <p>After you add a subscription or in-app product to the product list, you must 186 publish the product before Google Play can make it available for purchase. Note 187 that you must also publish the app itself before Google Play will make the 188 products available for purchase inside the app. </p> 189 190 <p class="caution"><strong>Important:</strong> At this time, the capability to 191 unpublish a subscription is not available. Support for unpublishing a 192 subscription is coming to the Developer Console in the weeks ahead, so this is a 193 temporary limitation. In the short term, instead of unpublishing, 194 you can remove the subscription product from the product list offered in your 195 app to prevent users from seeing or purchasing it.</p> 196 197 <h3 id="pricing">Subscription pricing</h3> 198 199 <p>When you create a subscription in the Developer Console, you can set a price 200 for it in any available currencies. Each subscription must have a non-zero 201 price. You can price multiple subscriptions for the same content differently 202 — for example you could offer a discount on an annual subscription 203 relative to the monthly equivalent. </p> 204 205 <p class="caution"><strong>Important:</strong> At this time, once you publish a 206 subscription product, you cannot change its price in any currency. Support for 207 changing the price of published subscriptions is coming to the Developer Console 208 in the weeks ahead. In the short term, you can work around this limitation by 209 publishing a new subscription product ID at a new price, then offer it in your 210 app instead of the original product. Users who have already purchased will 211 continue to be charged at the original price, but new users will be charged at 212 the new price.</p> 213 214 <h3 id="user-billing">User billing</h3> 215 216 <p>You can sell subscription products with automated recurring billing at 217 either of two intervals:</p> 218 219 <ul> 220 <li>Monthly — Google Play bills the customers Google Wallet account at 221 the time of purchase and monthly subsequent to the purchase date (exact billing 222 intervals can vary slightly over time)</li> 223 <li>Annually — Google Play bills the customer's Google Wallet account at 224 the time of purchase and again on the same date in subsequent years.</li> 225 </ul> 226 227 <p>Billing continues indefinitely at the interval and price specified for the 228 subscription. At each subscription renewal, Google Play charges the user account 229 automatically, then notifies the user of the charges afterward by email. Billing 230 cycles will always match subscription cycles, based on the purchase date.</p> 231 232 <p>Over the life of a subscription, the form of payment billed remains the same 233 — Google Play always bills the same form of payment (such as credit card, 234 Direct Carrier Billing) that was originally used to purchase the 235 subscription.</p> 236 237 <p>When the subscription payment is approved by Google Wallet, Google Play 238 provides a purchase token back to the purchasing app through the In-app Billing 239 API. For details, see <a href="#token">Purchase token</a>, below. Your apps can 240 store the token locally or pass it to your backend servers, which can then use 241 it to validate or cancel the subscription remotely using the <a 242 href="#play-dev-api">Google Play Android Developer API</a>.</p> 243 244 <p>In the case of billing errors, such as could happen if the customers credit 245 card becomes invalid, Google Play notifies your app of the change in purchase 246 state.</p> 247 248 <p>As a best practice, we recommend that your app includes business logic to 249 notify your backend servers of subscription purchases, tokens, and any billing 250 errors that may occur. Your backend servers can use the server-side API to query 251 and update your records and follow up with customers directly, if needed.</p> 252 253 <h3 id="cancellation">Subscription cancellation</h3> 254 255 <p>Users can view the status of all of their subscriptions and cancel them if 256 necessary from the My Apps screen in the Play Store app. Currently, the In-app 257 Billing API does not provide support for canceling subscriptions direct from 258 inside the purchasing app, although your app can broadcast an Intent to launch 259 the Play Store app directly to the My Apps screen.</p> 260 261 <p>When the user cancels a subscription, Google Play does not offer a refund for 262 the current billing cycle. Instead, it allows the user to have access to the 263 cancelled subscription until the end of the current billing cycle, at which time 264 it terminates the subscription. For example, if a user purchases a monthly 265 subscription and cancels it on the 15th day of the cycle, Google Play will 266 consider the subscription valid until the end of the 30th day (or other day, 267 depending on the month).</p> 268 269 <p>In some cases, the user may contact you directly to request cancellation of a 270 subscription. In this and similar cases, you can use the server-side API to 271 query and directly cancel the users subscription from your servers. 272 273 <p class="caution"><strong>Important:</strong> In all cases, you must continue 274 to offer the content that your subscribers have purchased through their 275 subscriptions, for as long any users are able to access it. That is, you must 276 not remove any subscribers content while any user still has an active 277 subscription to it, even if that subscription will terminate at the end of the 278 current billing cycle. Removing content that a subscriber is entitled to access 279 will result in penalties. Please see the <a 280 href="http://support.google.com/googleplay/android-developer/bin/answer.py?hl=en&answer=140504">policies document</a> for more information. </p> 281 282 <h3 id="uninstall">App uninstallation</h3> 283 284 <p>When the user uninstalls an app that includes purchased subscriptions, the Play Store app will notify the user that there are active subscriptions. If the user chooses to continue with the uninstalltion, the app is removed and the subscriptions remain active and recurring billing continues. The user can return to cancel the associated subscriptions at any time in the My Apps screen of the Play Store app. If the user chooses to cancel the uninstallation, the app and subscriptions remain as they were.</p> 285 286 <h3 id="refunds">Refunds</h3> 287 288 <p>As with other in-app products, Google Play does not provide a refund window 289 for subscription purchases. For example, users who purchase an app can ask for a 290 refund from Google Play within a 15-minute window. With subscriptions, Google 291 Play does not provide a refund window, so users will need to contact you 292 directly to request a refund. 293 294 <p>If you receive requests for refunds, you can use the server-side API to 295 cancel the subscription or verify that it is already cancelled. However, keep in 296 mind that Google Play considers cancelled subscriptions valid until the end of 297 their current billing cycles, so even if you grant a refund and cancel the 298 subscription, the user will still have access to the content. 299 300 <p class="note"><strong>Note:</strong> Partial refunds for canceled 301 subscriptions are not available at this time.</p> 302 303 <h3 id="payment">Payment processing and policies</h3> 304 305 <p>In general, the terms of Google Play allow you to sell in-app subscriptions 306 only through the standard payment processor, Google Wallet. For purchases of any 307 subscription products, just as for other in-app products and apps, the 308 transaction fee for subscriptions, just as for other in-app purchases, is the 309 same as the transaction fee for application purchases (30%).</p> 310 311 <p>Apps published on Google Play that are selling subscriptions must use In-app 312 Billing to handle the transaction and may not provide links to a purchase flow 313 outside of the app and Google Play (such as to a web site).</p> 314 315 <p>For complete details about terms and policies, see the <a 316 href="http://support.google.com/googleplay/android-developer/bin/answer.py?hl=en&answer=140504">policies 317 document</a>.</p> 318 319 <h3 id="requirements">System requirements for subscriptions</h3> 320 321 <p>In-app purchases of subscriptions are supported only on devices that meet 322 these minimum requirements:</p> 323 324 <ul> 325 <li>Must run Android 2.2 or higher</li> 326 <li>Google Play Store app, version 3.5 or higher, must be installed</li> 327 </ul> 328 329 <p>Google Play 3.5 and later versions include support for the In-app Billing 330 v2 API or higher, which is needed to support handling of subscription 331 products.</p> 332 333 <h3 id="compatibility">Compatibility considerations</h3> 334 335 <p>As noted in the previous section, support for subscriptions is available only 336 on devices that meet the system requirements. Not all devices will receive or 337 install Google Play 3.5, so not all users who install your apps will have access 338 to the In-app Billing API and subscriptions.</p> 339 340 <p>If you are targeting older devices that run Android 2.1 or earlier, we 341 recommend that you offer those users an alternative way buy the content that is 342 available through subscriptions. For example, you could create standard in-app 343 products (one-time purchases) that give access to similar content as your 344 subscriptions, possibly for a longer interval such as a year. </p> 345 346 347 <h2 id="implementing">Implementing Subscriptions</h2> 348 349 <p>Subscriptions are a standard In-app Billing product type. If you have already 350 implemented In-app Billing for one-time purchase products, you will find that 351 adding support for subscriptions is straightforward, with minimal impact on your 352 code. If you are new to In-app Billing, you can implement subscriptions using 353 the standard communication model, data structures, and user interactions as for 354 other in-app products.subscriptions. </p> 355 356 <p>The full implementation details for In-app Billing are provided outside of 357 this document, starting with the <a 358 href="{@docRoot}guide/google/play/billing/billing_overview.html">In-app Billing 359 Overview</a>. This document is focused on highlighting implementation details 360 that are specific to subscriptions, along with some strategies for the 361 associated billing and business models.</p> 362 363 364 <h3 id="sample">Sample application</h3> 365 366 <p>To help you get started with your In-app Billing implementation and 367 subscriptions, an updated version of the In-app Billing sample app is available. 368 You can download the sample app from the Android SDK repository using the 369 Android SDK Manager. For details, see <a 370 href="{@docRoot}guide/google/play/billing/billing_integrate.html#billing-download"> 371 Downloading the Sample Application</a>.</p> 372 373 <h3 id="model">Application model</h3> 374 375 <p>With subscriptions, your app uses the standard In-app Billing application 376 model, sending billing requests to the Play Store application over interprocess 377 communication (IPC) and receiving purchase responses from the Play Store app in 378 the form of asynchronous broadcast intents. Your application does not manage any 379 network connections between itself and the Google Play server or use any special 380 APIs from the Android platform.</p> 381 382 <p>Your app also uses the standard In-app Billing components — a billing 383 Service for sending requests, a BroadcastReceiver for receiving the responses, 384 and a security component for verifying that the response was sent by Google 385 Play. Also recommended are a response Handler for processing notifications, 386 errors, and status messages, and an observer for sending callbacks to your 387 application as needed. All of these components and their interactions are 388 described in full in the <a 389 href="{@docRoot}guide/google/play/billing/billing_overview.html">In-app Billing 390 Overview</a> and related documents.</p> 391 392 <p>To initiate different types of billing communication with Google Play, your 393 app will use the standard set of in-app billing requests and receive the same 394 responses. Inside the requests and responses are two new fields described below. 395 </p> 396 397 <h3 id="token">Purchase token</h3> 398 399 <p>Central to the end-to-end architecture for subscriptions is the purchase 400 token, a string value that uniquely identifies (and associates) a user ID and a 401 subscription ID. Google Play generates the purchase token when the user 402 completes the purchase of a subscription product (and payment is approved by 403 Google Wallet) and then sends it to the purchasing app on the device through the 404 In-app Billing API. </p> 405 406 <p>At the conclusion of a <code>PURCHASE_REQUEST</code> message flow, your app 407 can retrieve the purchase token and other transaction details by initiating a 408 <code>GET_PURCHASE_INFORMATION</code> request. The Bundle returned by the call 409 contains an JSON array of order objects. In the order corresponding to the 410 subscription purchase, the token is available in the <code>purchaseToken</code> 411 field. </p> 412 413 <p>An example of a JSON order object that includes a subscription purchase token 414 is shown below. </p> 415 416 <pre class="no-pretty-print" style="color:black">{ "nonce" : 1836535032137741465, 417 "orders" : 418 [{ "notificationId" : "android.test.purchased", 419 "orderId" : "transactionId.android.test.purchased", 420 "packageName" : "com.example.dungeons", 421 "productId" : "android.test.purchased", 422 "developerPayload" : "bGoa+V7g/yqDXvKRqq+JTFn4uQZbPiQJo4pf9RzJ", 423 "purchaseTime" : 1290114783411, 424 "purchaseState" : 0, 425 "purchaseToken" : "rojeslcdyyiapnqcynkjyyjh" }] 426 } 427 </pre> 428 429 <p>After receiving a purchase token, your apps can store the token locally or 430 pass it to your backend servers, which can then use it to query the billing 431 status or cancel the subscription remotely. If your app will store the token 432 locally, please read the <a 433 href="{@docRoot}guide/google/play/billing/billing_best_practices.html">Security and 434 Design</a> document for best practices for maintaining the security of your 435 data.</p> 436 437 <h3 id="version">Checking the In-app Billing API version</h3> 438 439 <p>Subscriptions support is available only in versions of Google Play that 440 support the In-app Billing v2 API (Google Play 3.5 and higher). For your app, 441 an essential first step at launch is to check whether the version of Google Play 442 installed on the device supports the In-app Billing v2 API and 443 subscriptions.</p> 444 445 <p>To do this, create a CHECK_BILLING_SUPPORTED request Bundle that includes the 446 required key-value pairs, together with</p> 447 448 <ul> 449 <li>The <code>API_VERSION</code> key, assigning a value of 2.</li> 450 <li>The <code>BILLING_REQUEST_ITEM_TYPE</code> key, assigning a value of subs</li> 451 </ul> 452 453 <p>Send the request using <code>sendBillingRequest(Bundle)</code> and receive 454 the response Bundle. You can extract the response from the 455 <code>BILLING_RESPONSE_RESPONSE_CODE</code> key of the response. RESULT_OK 456 indicates that subscriptions are supported.</p> 457 458 <p>The sample app declares constants for the accepted 459 <code>BILLING_REQUEST_ITEM_TYPE</code> values (from Consts.java):</p> 460 461 <pre class="pretty-print"> // These are the types supported in the IAB v2 462 public static final String ITEM_TYPE_INAPP = "inapp"; 463 public static final String ITEM_TYPE_SUBSCRIPTION = "subs"; 464 </pre> 465 466 <p>It sets up a convenience method for building the request bundle (from BillingService.java):</p> 467 468 <pre class="pretty-print"> protected Bundle makeRequestBundle(String method) { 469 Bundle request = new Bundle(); 470 request.putString(Consts.BILLING_REQUEST_METHOD, method); 471 request.putInt(Consts.BILLING_REQUEST_<code>API_VERSION</code>, 2); 472 request.putString(Consts.BILLING_REQUEST_PACKAGE_NAME, getPackageName()); 473 return request; 474 } 475 </pre> 476 477 <p>Heres an example of how to test support for In-App Billing v2 and subscriptions 478 (from BillingService.java):</p> 479 480 <pre class="pretty-print"> /** 481 * Wrapper class that checks if in-app billing is supported. 482 */ 483 class CheckBillingSupported extends BillingRequest { 484 public String mProductType = null; 485 public CheckBillingSupported() { 486 // This object is never created as a side effect of starting this 487 // service so we pass -1 as the startId to indicate that we should 488 // not stop this service after executing this request. 489 super(-1); 490 } 491 492 public CheckBillingSupported(String type) { 493 super(-1); 494 mProductType = type; 495 } 496 497 @Override 498 protected long run() throws RemoteException { 499 Bundle request = makeRequestBundle("CHECK_BILLING_SUPPORTED"); 500 if (mProductType != null) { 501 request.putString(Consts.<code>BILLING_REQUEST_ITEM_TYPE</code>, mProductType); 502 } 503 Bundle response = mService.sendBillingRequest(request); 504 int responseCode = response.getInt(Consts.<code>BILLING_RESPONSE_RESPONSE_CODE</code>); 505 if (Consts.DEBUG) { 506 Log.i(TAG, "CheckBillingSupported response code: " + 507 ResponseCode.valueOf(responseCode)); 508 } 509 boolean billingSupported = (responseCode == ResponseCode.RESULT_OK.ordinal()); 510 ResponseHandler.checkBillingSupportedResponse(billingSupported, mProductType); 511 return Consts.BILLING_RESPONSE_INVALID_REQUEST_ID; 512 } 513 } 514 </pre> 515 516 <h3 id="purchase">Requesting a subscription purchase</h3> 517 518 <p>Once youve checked the API version as described above and determined that 519 subscriptions are supported, you can present subscription products to the user 520 for purchase. When the user has selected a subscription product and initiated a 521 purchase, your app handles the purchase just as it would for other in-app 522 products — by sending a REQUEST_PURCHASE request. You can then launch 523 Google Play to display the checkout user interface and handle the financial 524 transaction.. 525 526 <p>The REQUEST_PURCHASE includes a Bundle containing the item details, as 527 described in the <a 528 href="{@docRoot}guide/google/play/billing/billing_overview.html">In-app Billing 529 Overview</a>. For a subscription, the Bundle must also specify:</p> 530 531 <ul> 532 <li>The <code>ITEM_ID</code> key, with a value that specifies a valid, published 533 subscription product.</li> 534 <li>The <code>ITEM_TYPE</code> key, with a value of subs 535 (<code>ITEM_TYPE_SUBSCRIPTION</code> in the sample app). If the request does not 536 specify the subscription's <code>ITEM_TYPE</code>, Google Play attempts to 537 handle the request as a standard in-app purchase (one-time purchase).</li> 538 </ul> 539 540 <p>Google Play synchronously returns a response bundle that includes 541 <code>RESPONSE_CODE</code>, <code>PURCHASE_INTENT</code>, and 542 <code>REQUEST_ID</code>. Your app uses the <code>PURCHASE_INTENT</code> to 543 launch the checkout UI and the message flow proceeds exactly as described in <a 544 href="{@docRoot}guide/google/play/billing/billing_overview.html#billing-message- 545 sequence">Messaging sequence</a>.</p> 546 547 <p>Heres how the sample app initiates a purchase for a subscription, where 548 <code>mProductType</code> is <code>ITEM_TYPE_SUBSCRIPTION</code> (from 549 BillingService.java).</p> 550 551 <pre class="pretty-print"> /** 552 * Wrapper class that requests a purchase. 553 */ 554 class RequestPurchase extends BillingRequest { 555 public final String mProductId; 556 public final String mDeveloperPayload; 557 public final String mProductType; 558 559 . . . 560 561 @Override 562 protected long run() throws RemoteException { 563 Bundle request = makeRequestBundle("REQUEST_PURCHASE"); 564 request.putString(Consts.BILLING_REQUEST_ITEM_ID, mProductId); 565 request.putString(Consts.<code>BILLING_REQUEST_ITEM_TYPE</code>, mProductType); 566 // Note that the developer payload is optional. 567 if (mDeveloperPayload != null) { 568 request.putString(Consts.BILLING_REQUEST_DEVELOPER_PAYLOAD, mDeveloperPayload); 569 } 570 Bundle response = mService.sendBillingRequest(request); 571 PendingIntent pendingIntent 572 = response.getParcelable(Consts.BILLING_RESPONSE_PURCHASE_INTENT); 573 if (pendingIntent == null) { 574 Log.e(TAG, "Error with requestPurchase"); 575 return Consts.BILLING_RESPONSE_INVALID_REQUEST_ID; 576 } 577 578 Intent intent = new Intent(); 579 ResponseHandler.buyPageIntentResponse(pendingIntent, intent); 580 return response.getLong(Consts.BILLING_RESPONSE_REQUEST_ID, 581 Consts.BILLING_RESPONSE_INVALID_REQUEST_ID); 582 } 583 584 @Override 585 protected void responseCodeReceived(ResponseCode responseCode) { 586 ResponseHandler.responseCodeReceived(BillingService.this, this, responseCode); 587 } 588 } 589 </pre> 590 591 <h3 id="restoring">Restoring transactions</h3> 592 593 <p>Subscriptions always use the <em>managed by user account</em> purchase type, 594 so that you can restore a record of subscription transactions on the device when 595 needed. When a user installs your app onto a new device, or when the user 596 uninstalls/reinstalls the app on the original device, your app should restore 597 the subscriptions that the user has purchased.</p> 598 599 <p>The process for restoring subscriptions transactions is the same as described 600 in <a 601 href="{@docRoot}guide/google/play/billing/billing_overview.html#billing-message- 602 sequence">Messaging sequence</a>. Your app sends a 603 <code>RESTORE_TRANSACTIONS</code> request to Google Play. Google Play sends two 604 broadcast intents as asynchronous responses — a <code>RESPONSE_CODE</code> 605 intent and a <code>PURCHASE_STATE_CHANGED</code> intent.</p> 606 607 <p>The <code>PURCHASE_STATE_CHANGED</code> intent contains a notification ID 608 that your app can use to retrieve the purchase details, including the purchase 609 token, by sending a standard <code>GET_PURCHASE_INFORMATION</code> request. The 610 <code>Bundle</code> returned in the call includes an JSON array of order objects 611 corresponding to subscription (and in-app product) purchases that you can 612 restore locally.</p> 613 614 <p>Your app can store the restored purchase state and other transaction details 615 in the way that best meets your needs. Your app can use it later to check the 616 subscription validity, although please read the <a 617 href="{@docRoot}guide/google/play/billing/billing_best_practices.html">Security and 618 Design</a> document for best practices for maintaining the security of your 619 data.</p> 620 621 <h3 id="validity">Checking subscription validity</h3> 622 623 <p>Subscriptions are time-bound purchases that require successful billing 624 recurrences over time to remain valid. Your app should check the validity of 625 purchased subscriptions at launch or prior to granting access to subscriber 626 content.</p> 627 628 <p>With In-app Billing, you validate a subscription by keeping track of its 629 purchase state, such as purchased or cancelled, and then checking the state 630 whenever needed. Google Play provides two ways to let you know when the purchase 631 state of a subscription changes:</p> 632 633 <ul> 634 <li><em>In-app Billing Notifications</em>. Google Play pushes a notification 635 to your app whenever the purchase state of a subscription changes. Your app can 636 store the most recent purchase state for a given purchase token and then check 637 that state at run time, as needed.</li> 638 <li><em>Google Play Android Developer API</em>. You can use this HTTP-based 639 API to poll Google Play for the current purchase state of a subscription. You 640 can store the purchased state for each <code>purchaseToken</code> on your 641 backend servers. For more information, see <a href="#play-dev-api">Google Play 642 Android Developer API</a>, below.</li> 643 </ul> 644 645 <p>For most use-cases, especially those where backend servers are already keeping 646 track of subscribed users, implementing a combination of both methods is the 647 recommended approach. A typical implementation might work like this:</p> 648 649 <ul> 650 <li>When the user successfully purchases a new subscription, your app notifies a 651 backend server, which stores the purchase token, user name, and other 652 information in a secure location.</li> 653 <li>Since your app cannot know the expiration date, your server can poll Google 654 Play to get the expiration and store it with the purchase token and other 655 data.</li> 656 <li>Because your server now knows the expiration date, it does not need to poll 657 Google Play again until after the expiration date, at which time it can confirm 658 that the subscription was not cancelled.</li> 659 <li>On the client side, your app can continue to update the server whenever the 660 purchase state changes, storing the state locally.</li> 661 </ul> 662 663 <p>If you are using both notifications and the Google Play Android Developer API to validate subscriptions, we recommend the following:</p> 664 665 <ul> 666 <li>If your app wants to check validity but you cant reach your server (or 667 you dont have a server), use the latest purchase state received by 668 notification.</li> 669 <li>If you have a server and its reachable, always give preference to the 670 purchase state obtained from your server over the state received in 671 notifications.</li> 672 </ul> 673 674 <p>If necessary, you can also use a <code>RESTORE_TRANSACTIONS</code> request to retrieve a record of all managed and in-app products purchased by the user, which you can then store locally. However, using <code>RESTORE_TRANSACTIONS</code> on a regular basis is not recommended because of performance impacts.</p> 675 676 <p>Regardless of the approach you choose, your app should check subscriptions 677 and validity at launch, such as prior to accessing subscriber content, game 678 levels, and so on.</p> 679 680 <p class="table-caption"><strong>Table 1.</strong> Summary of purchaseState 681 values for subscription purchases, as received with a 682 <code>PURCHASE_STATE_CHANGED</code> intent.</p> 683 684 <table> 685 <tr> 686 <th>State</th><th>purchaseState Value</th><th>Comments</th> 687 </tr> 688 <tr> 689 <td>Purchased successfully</td><td><code>0</code></td><td>Sent at original purchase only (not at recurring billing cycles).</td></tr> 690 <td>Cancelled</td><td><code>1</code></td><td>Sent at original purchase only if the purchase has failed for some reason. </td></tr> 691 <td>Refunded</td><td><code>2</code></td><td>The purchase was refunded.</code></td></tr> 692 <td>Subscription expired</td><td><code>3</code></td><td>Sent if a subscription expires because of non-payment or user cancelation.</td></tr> 693 </table> 694 695 696 <h3 id="viewstatus">Launching your product page to let the user cancel or view subscriptions</h3> 697 698 <p>In-app Billing does not currently provide an API to let users directly view or cancel 699 subscriptions from within the purchasing app. Instead, users can launch the Play 700 Store app on their devices and go to the My Apps screen to manage subscriptions. In My Apps, 701 users can see a list of their subscriptions organized by application. Tapping one of the 702 subscriptions loads the app's product page, from which users can see active subscriptions 703 and billing status and cancel subscriptions as needed.</p> 704 705 <p>To make it easier for users to find and manage their subscriptions from inside your app, 706 we recommend that you offer a "View My Subscriptions" or "Manage Subscriptions" option in 707 your UI that directly loads your app's product page in the Play Store app.</p> 708 709 <p>To do this, create an intent with the <a 710 href="{@docRoot}reference/android/content/Intent.html#ACTION_VIEW">ACTION_VIEW</a> 711 action and include the <code>market://</code> URI (rather than the <code>http://</code> 712 URI) of your app's details page. Heres an example:</p> 713 714 <pre style="pretty-print">Intent intent = new Intent(Intent.ACTION_VIEW); 715 intent.setData(Uri.parse("market://details?id=com.example.app")); 716 startActivity(intent);</pre> 717 718 <p>For more information, see 719 <a href="{@docRoot}distribute/googleplay/promote/linking.html">Linking to Your Products</a>.</p> 720 721 <h3 id="purchase-state-changes">Recurring billing and changes in purchase state</h3> 722 723 <p>Google Play notifies your app when the user completes the purchase of a 724 subscription, but the purchase state does not change over time, provided that 725 recurring billing takes place successfully. Google Play does not notify your app 726 of a purchase state change <em>until the subscription expires because of 727 non-payment or user cancellation</em>. </p> 728 729 <p>Over the life of a subscription, your app does not need to initiate any 730 recurring billing events — those are all handled by Google Play and they 731 are transparent to your application if billing is successful.</p> 732 733 <h3 id="modifying">Modifying your app for subscriptions</h3> 734 735 <p>For subscriptions, you make the same types of modifications to your app as 736 are described in <a 737 href="{@docRoot}guide/google/play/billing/billing_integrate.html#billing-implement"> 738 Modifying your Application Code</a>.</p> 739 740 <p>Note that, in your UI that lets users view and select subscriptions for 741 purchase, you should add logic to check for purchased subscriptions and validate 742 them. Your UI should not present subscriptions if the user has already purchased 743 them.</p> 744 745 <h2 id="administering">Administering Subscriptions</h2> 746 747 <p>To create and manage subscriptions, you use the tools in the Developer 748 Console, just as for other in-app products.</p> 749 750 <p>At the Developer Console, you can configure these attributes for each 751 subscription product:</p> 752 753 <ul> 754 <li>Purchase Type: always set to subscription</li> 755 <li>Subscription ID: An identifier for the subscription</li> 756 <li>Publishing State: Unpublished/Published</li> 757 <li>Language: The default language for displaying the subscription</li> 758 <li>Title: The title of the subscription product</li> 759 <li>Description: Details that tell the user about the subscription</li> 760 <li>Price: USD price of subscription per recurrence</li> 761 <li>Recurrence: monthly or yearly</li> 762 <li>Additional currency pricing (can be auto-filled)</li> 763 </ul> 764 765 <p>For details, please see <a href="{@docRoot}guide/google/play/billing/billing_admin.html">Administering 766 In-app Billing</a>.</p> 767 768 769 <h2 id="play-dev-api">Google Play Android Developer API</h2> 770 771 <p>Google Play offers an HTTP-based API that you can use to remotely query the 772 validity of a specific subscription at any time or cancel a subscription. The 773 API is designed to be used from your backend servers as a way of securely 774 managing subscriptions, as well as extending and integrating subscriptions with 775 other services.</p> 776 777 <h3 id="using">Using the API</h3> 778 779 <p>To use the API, you must first register a project at the <a 780 href="https://code.google.com/apis/console">Google APIs Console</a> and receive 781 a Client ID and shared secret that your app will present when calling the 782 Google Play Android Developer API. All calls to the API are authenticated with 783 OAuth 2.0.</p> 784 785 <p>Once your app is registered, you can access the API directly, using standard 786 HTTP methods to retrieve and manipulate resources, or you can use the Google 787 APIs Client Libraries, which are extended to support the API.</p> 788 789 <p>The Google Play Android Developer API is built on a RESTful design that uses 790 HTTP and JSON, so any standard web stack can send requests and parse the 791 responses. However, if you dont want to send HTTP requests and parse responses 792 manually, you can access the API using the client libraries, which provide 793 better language integration, improved security, and support for making calls 794 that require user authorization.</p> 795 796 <p>For more information about the API and how to access it through the Google 797 APIs Client Libraries, see the documentation at:</p> 798 799 <p style="margin-left:1.5em;"><a 800 href="https://developers.google.com/android-publisher/v1/">https://developers. 801 google.com/android-publisher/v1/</a></p> 802 803 <h3 id="quota">Quota</h3> 804 805 <p>Applications using the Google Play Android Developer API are limited to an 806 initial courtesy usage quota of <strong>15000 requests per day</strong> (per 807 application). This should provide enough access for normal 808 subscription-validation needs, assuming that you follow the recommendation in 809 this section.</p> 810 811 <p>If you need to request a higher limit for your application, please use the 812 Request more link in the <a 813 href="https://code.google.com/apis/console/#:quotas">Google APIs Console</a>. 814 Also, please read the section below on design best practices for minimizing your 815 use of the API.</p> 816 817 <h3 id="auth">Authorization</h3> 818 819 <p>Calls to the Google Play Android Developer API require authorization. Google 820 uses the OAuth 2.0 protocol to allow authorized applications to access user 821 data. To learn more, see <a 822 href="https://developers.google.com/android-publisher/authorization">Authorization</a> 823 in the Google Play Android Developer API documentation.</p> 824 825 <h3 id="practices">Using the API efficiently</h3> 826 827 <p>Access to the Google Play Android Developer API is regulated to help ensure a 828 high-performance environment for all applications that use it. While you can 829 request a higher daily quota for your application, we highly recommend that you 830 minimize your access using the technique(s) below. </p> 831 832 <ul> 833 <li><em>Store subscription expiry on your servers</em> — your servers 834 should use the Google Play Android Developer API to query the expiration date 835 for new subscription tokens, then store the expiration date locally. This allows 836 you to check the status of subscriptions only at or after the expiration (see 837 below). </li> 838 <li><em>Cache expiration and purchaseState</em> — If your app contacts 839 your backend servers at runtime to verify subscription validity, your server 840 should cache the expiration and purchaseState to ensure the fastest possible 841 response (and best experience) for the user.</li> 842 <li><em>Query for subscription status only at expiration</em> — Once your 843 server has retrieved the expiration date of subscription tokens, it should not 844 query the Google Play servers for the subscription status again until the 845 subscription is reaching or has passed the expiration date. Typically, your 846 servers would run a batch query each day to check the status of 847 <em>expiring</em> subscriptions, then update the database. Note that: 848 <ul> 849 <li>Your servers should not query all subscriptions every day</li> 850 <li>Your servers should never query subscription status dynamically, based on 851 individual requests from your Android application. </li> 852 </ul> 853 </li> 854 </ul> 855 856 <p>By following those general guidelines, your implementation will offer the 857 best possible performance for users and minimize use of the Google Play Android 858 Developer API.</p> 859 860