1 page.title=In-app Billing API 2 parent.title=In-app Billing 3 parent.link=index.html 4 page.tags="billing, inapp, iap" 5 @jd:body 6 7 <div id="qv-wrapper"> 8 <div id="qv"> 9 10 <h2>Topics</h2> 11 <ol> 12 <li><a href="#producttypes">Product Types</a> 13 <ol> 14 <li><a href="#managed">Managed In-app Products</a></li> 15 <li><a href="#subs">Subscriptions</a></li> 16 </ol> 17 </li> 18 <li><a href="#purchase">Purchasing Items</a></li> 19 <li><a href="#consume">Consuming In-app Products</a> 20 <ol> 21 <li><a href="#consumetypes">Non-consumable and Consumable In-app Products</a></li> 22 <li><a href="#managingconsumables">Managing Consumable Purchases</a></li> 23 </ol> 24 </li> 25 <li><a href="#caching">Local Caching</a></li> 26 </ol> 27 28 <h2>Reference</h2> 29 <ol> 30 <li><a href="{@docRoot}google/play/billing/billing_reference.html">In-app Billing 31 Reference (V3)</a></li> 32 </ol> 33 34 <h2>See also</h2> 35 <ol> 36 <li><a href="{@docRoot}training/in-app-billing/index.html">Selling In-app Products</a></li> 37 </ol> 38 </div> 39 </div> 40 41 <p> 42 The In-app Billing Version 3 API makes it easier for you to integrate In-app 43 Billing into your applications. The features in this version include improved 44 synchronous purchase flow, APIs to let you easily track ownership of 45 consumable goods, and local caching of in-app purchase data. 46 </p> 47 48 <h2 id="producttypes">Product Types</h2> 49 50 <p> 51 You define your products using the Google Play Developer Console, including 52 product type, SKU, price, description, and so on. For more information, see 53 <a href="{@docRoot}google/play/billing/billing_admin.html">Administering 54 In-app Billing</a>. The Version 3 API supports managed in-app products and 55 subscriptions. 56 </p> 57 58 <h3 id="managed">Managed In-app Products</h3> 59 60 <p> 61 Managed in-app products are items that have their ownership information 62 tracked and managed by Google Play. When a user purchases a managed in-app 63 item, Google Play stores the purchase information for each item on a per-user 64 basis. This enables you to later query Google Play at any time to restore the 65 state of the items a specific user has purchased. This information is 66 persistent on the Google Play servers even if the user uninstalls the 67 application or if they change devices. 68 </p> 69 70 <p> 71 If you are using the Version 3 API, you can also consume managed items within 72 your application. You would typically implement consumption for items that 73 can be purchased multiple times (such as in-game currency, fuel, or magic 74 spells). Once purchased, a managed item cannot be purchased again until you 75 consume the item, by sending a consumption request to Google Play. To learn 76 more about in-app product consumption, see <a href="#consume">Consuming 77 Items</a>. 78 </p> 79 80 <h3 id="subs">Subscriptions</h3> 81 82 <p> 83 A subscription is a product type offered in In-app Billing that lets you sell 84 content, services, or features to users from inside your app with recurring 85 monthly or annual billing. You can sell subscriptions to almost any type of 86 digital content, from any type of app or game. To understand how 87 subscriptions work, see <a href= 88 "{@docRoot}google/play/billing/billing_subscriptions.html">In-app Billing 89 Subscriptions</a>. 90 </p> 91 92 <p> 93 With the Version 3 API, you can use the same purchase flow for buying 94 subscriptions and retrieving subscription purchase information as with in-app 95 products. For a code example, see <a href= 96 "{@docRoot}google/play/billing/billing_integrate.html#Subs">Implementing 97 Subscriptions</a>. 98 </p> 99 100 <p class="caution"> 101 <strong>Important</strong>: Unlike in-app products, subscriptions cannot be 102 consumed. 103 </p> 104 105 <h2 id="purchase">Purchasing Items</h2> 106 107 <div class="figure" style="width:430px"> 108 <img src="{@docRoot}images/in-app-billing/v3/iab_v3_purchase_flow.png" id="figure1" height="530"/> 109 <p class="img-caption"> 110 <strong>Figure 1.</strong> The basic sequence for a purchase request. 111 </p> 112 </div> 113 114 <p>A typical purchase flow with the Version 3 API is as follows:</p> 115 116 <ol> 117 <li>Your application sends a {@code isBillingSupported} request to Google 118 Play to determine that the target version of the In-app Billing API that you 119 are using is supported. 120 </li> 121 122 <li>When your application starts or user logs in, it's good practice to check 123 with Google Play to determine what items are owned by the user. To query the 124 user's in-app purchases, send a {@code getPurchases} request. If the request 125 is successful, Google Play returns a {@code Bundle} containing a list of 126 product IDs of the purchased items, a list of the individual purchase 127 details, and a list of the signatures for the purchases. 128 </li> 129 130 <li>Usually, you'll want to inform the user of the products that are 131 available for purchase. To query the details of the in-app products that you 132 defined in Google Play, your application can send a {@code getSkuDetails} 133 request. You must specify a list of product IDs in the query request. If the 134 request is successful, Google Play returns a {@code Bundle} containing 135 product details including the products price, title, description, and the 136 purchase type. 137 </li> 138 139 <li>If an in-app product is not owned by the user, you can initiate a 140 purchase for it. To start a purchase request, your application sends a {@code 141 getBuyIntent} request, specifying the product ID of the item to purchase, 142 along with other parameters. You should record the product ID when you create 143 a new in-app product in the Developer Console. 144 <ol type="a"> 145 <li>Google Play returns a {@code Bundle} that contains a {@code 146 PendingIntent} which your application uses to start the checkout UI for 147 the purchase. 148 </li> 149 150 <li>Your application launches the pending intent by calling the {@code 151 startIntentSenderForResult} method. 152 </li> 153 154 <li>When the checkout flow finishes (that is, the user successfully 155 purchases the item or cancels the purchase), Google Play sends a response 156 {@code Intent} to your {@code onActivityResult} method. The result code 157 of the {@code onActivityResult} has a result code that indicates whether 158 the purchase was successful or canceled. The response {@code Intent} 159 contains information about the purchased item, including a {@code 160 purchaseToken} String that is generated by Google Play to uniquely 161 identify this purchase transaction. The {@code Intent} also contains the 162 signature of the purchase, signed with your private developer key. 163 </li> 164 </ol> 165 </li> 166 </ol> 167 168 <p> 169 To learn more about the Version 3 API calls and server responses, see 170 <a href="{@docRoot}google/play/billing/billing_reference.html">In-app Billing 171 Reference</a>. 172 </p> 173 174 <h2 id="consume">Consuming In-app Products</h2> 175 176 <p> 177 You can use the consumption mechanism to track the user's ownership of in-app 178 products. 179 </p> 180 181 <p> 182 In Version 3, all in-app products are managed. This means that the user's 183 ownership of all in-app item purchases is maintained by Google Play, and your 184 application can query the user's purchase information when needed. When the 185 user successfully purchases an in-app product, that purchase is recorded in 186 Google Play. Once an in-app product is purchased, it is considered to be 187 "owned". In-app products in the "owned" state cannot be purchased from Google 188 Play. You must send a consumption request for the "owned" in-app product 189 before Google Play makes it available for purchase again. Consuming the 190 in-app product reverts it to the "unowned" state, and discards the previous 191 purchase data. 192 </p> 193 194 <div class="figure" style="width:420px"> 195 <img src="{@docRoot}images/in-app-billing/v3/iab_v3_consumption_flow.png" 196 id="figure2" height="300"/> 197 <p class="img-caption"> 198 <strong>Figure 2.</strong> The basic sequence for a consumption request. 199 </p> 200 </div> 201 202 <p> 203 To retrieve the list of product's owned by the user, your application sends a 204 {@code getPurchases} call to Google Play. Your application can make a 205 consumption request by sending a {@code consumePurchase} call. In the request 206 argument, you must specify the in-app product's unique {@code purchaseToken} 207 String that you obtained from Google Play when it was purchased. Google Play 208 returns a status code indicating if the consumption was recorded 209 successfully. 210 </p> 211 212 <h3 id="consumetypes">Non-consumable and Consumable In-app Products</h3> 213 214 <p> 215 It's up to you to decide if you want to handle your in-app products as 216 non-consumable or consumable items. 217 </p> 218 219 <dl> 220 <dt> 221 Non-consumable Items 222 </dt> 223 224 <dd> 225 Typically, you would not implement consumption for in-app products that can 226 only be purchased once in your application and provide a permanent benefit. 227 Once purchased, these items will be permanently associated to the user's 228 Google account. An example of a non-consumable in-app product is a premium 229 upgrade or a level pack. 230 </dd> 231 232 <dt> 233 Consumable items 234 </dt> 235 236 <dd> 237 In contrast, you can implement consumption for items that can be made 238 available for purchase multiple times. Typically, these items provide 239 certain temporary effects. For example, the user's in-game character might 240 gain life points or gain extra gold coins in their inventory. Dispensing 241 the benefits or effects of the purchased item in your application is called 242 <em>provisioning</em> the in-app product. You are responsible for 243 controlling and tracking how in-app products are provisioned to the users. 244 <p class="note"> 245 <strong>Important:</strong> Before provisioning the consumable in-app 246 product in your application, you must send a consumption request to 247 Google Play and receive a successful response indicating that the 248 consumption was recorded. 249 </p> 250 </dd> 251 </dl> 252 253 <h3 id="managingconsumables">Managing consumable purchases in your application</h3> 254 <p>Here is the basic flow for purchasing a consumable in-app product:</p> 255 256 <ol> 257 <li>Launch a purchase flow with a {@code getBuyIntent} call 258 </li> 259 260 <li>Get a response {@code Bundle}from Google Play indicating if the purchase 261 completed successfully. 262 </li> 263 264 <li>If the purchase was successful, consume the purchase by making a {@code 265 consumePurchase} call. 266 </li> 267 268 <li>Get a response code from Google Play indicating if the consumption 269 completed successfully. 270 </li> 271 272 <li>If the consumption was successful, provision the product in your 273 application. 274 </li> 275 </ol> 276 277 <p> 278 Subsequently, when the user starts up or logs in to your application, you 279 should check if the user owns any outstanding consumable in-app products; if 280 so, make sure to consume and provision those items. Here's the recommended 281 application startup flow if you implement consumable in-app products in your 282 application: 283 </p> 284 285 <ol> 286 <li>Send a {@code getPurchases} request to query the owned in-app products 287 for the user. 288 </li> 289 290 <li>If there are any consumable in-app products, consume the items by calling 291 {@code consumePurchase}. This step is necessary because the application might 292 have completed the purchase order for the consumable item, but stopped or got 293 disconnected before the application had the chance to send a consumption 294 request. 295 </li> 296 297 <li>Get a response code from Google Play indicating if the consumption 298 completed successfully. 299 </li> 300 301 <li>If the consumption was successful, provision the product in your 302 application. 303 </li> 304 </ol> 305 306 <h2 id="caching">Local Caching</h2> 307 308 <p> 309 Because the Google Play client now caches In-app Billing information locally 310 on the device, you can use the Version 3 API to query for this information 311 more frequently, for example through a {@code getPurchases} call. Unlike with 312 previous versions of the API, many Version 3 API calls will be serviced 313 through cache lookups instead of through a network connection to Google Play, 314 which significantly speeds up the API's response time. 315 </p> 316
