Quddus Chong | 768dba6 | 2012-12-08 17:06:30 -0800 | [diff] [blame] | 1 | page.title=In-app Billing Version 2 |
| 2 | @jd:body |
| 3 | |
| 4 | <div style="background-color:#fffdeb;width:100%;margin-bottom:1em;padding:.5em;">In-app Billing Version 2 is superseded. Please <a href="{@docRoot}google/play/billing/billing_overview.html#migration">migrate to Version 3</a> at your earliest convenience.</div> |
| 5 | <div id="qv-wrapper" style="margin-top:0;"> |
| 6 | <div id="qv"> |
| 7 | |
| 8 | <h2>In this document</h2> |
| 9 | <ol> |
| 10 | <li><a href="#billing-types">Product and Purchase Types</a></li> |
| 11 | <li><a href="#billing-arch">Service Architecture</a></li> |
| 12 | <li><a href="#billing-msgs">Service Messages</a></li> |
| 13 | <ol> |
| 14 | <li><a href="#billing-request">Request messages</a></li> |
| 15 | <li><a href="#billing-response">Broadcast intents</a></li> |
| 16 | <li><a href="#billing-message-sequence">Messaging sequence</a></li> |
| 17 | <li><a href="#billing-action-notify">Handling IN_APP_NOTIFY messages</a></li> |
| 18 | </ol> |
| 19 | <li><a href="#billing-security">Security Controls</a></li> |
| 20 | <li><a href="#billing-limitations">Requirements and Limitations</a></li> |
| 21 | </ol> |
| 22 | </div> |
| 23 | </div> |
| 24 | |
| 25 | <p>In-app Billing version 2 is the legacy version of the Google Play In-app |
| 26 | Billing. Like Version 3, it lets you interact with the Google Play purchase flow |
| 27 | and payments system indirectly, by means of IPC communication with the Play |
| 28 | Store app installed on the device. </p> |
| 29 | |
| 30 | <p>Unlike Version 3, the Version 2 API is |
| 31 | asynchronous and uses service messages sent as broadcast intents, so |
| 32 | it is more complicated than Version 3. </p> |
| 33 | |
| 34 | <p>Version 2 supports both unmanaged and managed products, as well as supports |
| 35 | subscriptions, where Version 3 does not yet offer support for subscriptions. If |
| 36 | you want to sell subscriptions in your app, you should implement In-app Billing |
| 37 | Version 2, rather than Version 3. </p> |
| 38 | |
| 39 | <p>If you do not need to sell subscriptions, you |
| 40 | should implement In-app Billing Version 3 instead.</p> |
| 41 | |
Quddus Chong | 768dba6 | 2012-12-08 17:06:30 -0800 | [diff] [blame] | 42 | <h2 id="billing-types">Product Types</h2> |
| 43 | |
| 44 | <p>In-app Billing Version supports three different product types |
| 45 | to give you flexibility in how you monetize your app. In all cases, you define |
| 46 | your products using the Google Play Developer Console, including product type, |
| 47 | SKU, price, description, and so on. For more information, see <a |
| 48 | href="{@docRoot}google/play/billing/billing_admin.html">Administering In-app Billing</a>.</p> |
| 49 | |
| 50 | <ul> |
| 51 | <li><em>Managed per user account</em> — Items that can be purchased only |
| 52 | once per user account on Google Play. When a user purchases an item that uses |
| 53 | the "managed per user account" product type, Google Play permanently stores the |
| 54 | transaction information for each item on a per-user basis. This enables you to |
| 55 | later query Google Play to restore the state of the items a specific user has |
| 56 | purchased. If a user attempts to purchase a managed item that has already been |
| 57 | purchased, Google Play prevents the user from purchasing the item again and |
| 58 | displays an "Item already purchased" error. |
| 59 | |
| 60 | <p>The "managed" product type is useful if you are selling |
| 61 | items such as game levels or application features. These items are not transient |
| 62 | and usually need to be restored whenever a user reinstalls your application, |
| 63 | wipes the data on their device, or installs your application on a new |
| 64 | device.</p> |
| 65 | |
| 66 | <li><em>Unmanaged</em> — Items that do not have their transaction |
| 67 | information stored on Google Play. This means that you cannot later query Google |
| 68 | Play to retrieve transaction information for those items. For "unmanaged" |
| 69 | purchases, you are responsible for managing the transaction information. Also, |
| 70 | Google Play does not attempt to prevent the user from purchasing an item |
| 71 | multiple times if it uses the "unmanaged" product type. It's up to you to |
| 72 | control how many times an unmanaged item can be purchased.</p> |
| 73 | |
| 74 | <p>The "unmanaged" product type is useful if you are selling consumable items, |
| 75 | such as fuel or magic spells. These items are consumed within your application |
| 76 | and are usually purchased multiple times.</p></li> |
| 77 | |
| 78 | <li><em>Subscriptions</em> — Items that are sold with a |
| 79 | developer-specified, recurring billing interval. When a user purchases a |
| 80 | subscription, Google Play and its payment processor automatically bill the |
| 81 | user's account at the specified interval and price, charging the amount to the |
| 82 | original payment method. Once the user purchases a subscription, Google Play |
| 83 | continues billing the account indefinitely, without requiring approval or action |
| 84 | from the user. The user can cancel the subscription at any time. |
| 85 | |
| 86 | <p>Subscriptions can only be sold using the "managed per user account" purchase |
| 87 | type. As with in-app products, once the user has purchased an in-app product |
| 88 | there is no refund window. Users desiring refunds must contact the developer |
| 89 | directly. For more information about subscriptions and how to sell them in your |
| 90 | apps, see the <a href="{@docRoot}google/play/billing/v2/billing_subscriptions.html">Subscriptions</a> |
| 91 | document.</p></li> |
| 92 | </ul> |
| 93 | |
| 94 | <h2 id="billing-arch">Service Architecture</h2> |
| 95 | |
| 96 | <p>Your app accesses the In-app Billing service using an API that is exposed by |
| 97 | the Google Play app installed on the device. The Google Play app then uses an |
| 98 | asynchronous message loop to convey billing requests and responses between your |
| 99 | application and the Google Play server. In practice, your application never |
| 100 | directly communicates with the Google Play server (see figure 1). Instead, your |
| 101 | application sends billing requests to the Google Play application over |
| 102 | interprocess communication (IPC) and receives purchase responses from the Google |
| 103 | Play application in the form of asynchronous broadcast intents. Your application |
| 104 | does not manage any network connections between itself and the Google Play |
| 105 | server or use any special APIs from the Android platform.</p> |
| 106 | |
| 107 | <div class="figure" style="width:440px"> |
| 108 | <img src="/images/billing_arch.png" alt="" height="582" /> |
| 109 | <p class="img-caption"> |
| 110 | <strong>Figure 1.</strong> Your application sends and receives billing messages through the |
| 111 | Google Play application, which handles all communication with the Google Play server.</p> |
| 112 | </div> |
| 113 | |
| 114 | <p>Some in-app billing implementations may also use a private remote server to deliver content or |
| 115 | validate transactions, but a remote server is not required to implement in-app billing. A remote |
| 116 | server can be useful if you are selling digital content that needs to be delivered to a user's |
| 117 | device, such as media files or photos. You might also use a remote server to store users' |
| 118 | transaction history or perform various in-app billing security tasks, such as signature |
| 119 | verification. Although you can handle all security-related tasks in your application, performing |
| 120 | those tasks on a remote server is recommended because it helps make your application less vulnerable |
| 121 | to security attacks.</p> |
| 122 | |
| 123 | <p>A typical in-app billing implementation relies on three components:</p> |
| 124 | <ul> |
| 125 | <li>A {@link android.app.Service Service} (named <code>BillingService</code> in the sample application), |
| 126 | which processes purchase messages from the application and sends billing requests to the Google |
| 127 | Play in-app billing service.</li> |
| 128 | <li>A {@link android.content.BroadcastReceiver BroadcastReceiver} (named <code>BillingReceiver</code> in the sample |
| 129 | application), which receives all asynchronous billing responses from the Google Play |
| 130 | application.</li> |
| 131 | <li>A security component (named <code>Security</code> in the sample application), which performs |
| 132 | security-related tasks, such as signature verification and nonce generation. For more information |
| 133 | about in-app billing security, see <a href="#billing-security">Security controls</a> later in this |
| 134 | document.</li> |
| 135 | </ul> |
| 136 | |
| 137 | <p>You may also want to incorporate two other components to support in-app billing:</p> |
| 138 | <ul> |
| 139 | <li>A response {@link android.os.Handler Handler} (named <code>ResponseHandler</code> in the sample |
| 140 | application), which provides application-specific processing of purchase notifications, errors, |
| 141 | and other status messages.</li> |
| 142 | <li>An observer (named <code>PurchaseObserver</code> in the sample application), which is |
| 143 | responsible for sending callbacks to your application so you can update your user interface with |
| 144 | purchase information and status.</li> |
| 145 | </ul> |
| 146 | |
| 147 | <p>In addition to these components, your application must provide a way to store information about |
| 148 | users' purchases and some sort of user interface that lets users select items to purchase. You do |
| 149 | not need to provide a checkout user interface. When a user initiates an in-app purchase, the Google |
| 150 | Play application presents the checkout user interface to your user. When the user completes the |
| 151 | checkout process, your application resumes.</p> |
| 152 | |
| 153 | <h2 id="billing-msgs">In-app Billing Messages</h2> |
| 154 | |
| 155 | <p>When the user initiates a purchase, your application sends billing messages to Google Play's |
| 156 | in-app billing service (named <code>MarketBillingService</code>) using simple IPC method calls. The |
| 157 | Google Play application responds to all billing requests synchronously, providing your |
| 158 | application with status notifications and other information. The Google Play application also |
| 159 | responds to some billing requests asynchronously, providing your application with error messages and |
| 160 | detailed transaction information. The following section describes the basic request-response |
| 161 | messaging that takes place between your application and the Google Play application.</p> |
| 162 | |
| 163 | <h3 id="billing-request">In-app billing requests</h3> |
| 164 | |
| 165 | <p>Your application sends in-app billing requests by invoking a single IPC method |
| 166 | (<code>sendBillingRequest()</code>), which is exposed by the <code>MarketBillingService</code> |
| 167 | interface. This interface is defined in an <a |
| 168 | href="{@docRoot}guide/components/aidl.html">Android Interface Definition Language</a> file |
| 169 | (<code>IMarketBillingService.aidl</code>). You can <a |
| 170 | href="{@docRoot}google/play/billing/v2/billing_integrate.html#billing-download">download</a> this AIDL |
| 171 | file with the in-app billing sample application.</p> |
| 172 | |
| 173 | <p>The <code>sendBillingRequest()</code> method has a single {@link android.os.Bundle Bundle} parameter. |
| 174 | The Bundle that you deliver must include several key-value pairs that specify various parameters for |
| 175 | the request, such as the type of billing request you are making, the item that is being purchased and |
| 176 | its type, and the application that is making the request. For more information about the Bundle keys |
| 177 | that are sent with a request, see <a |
| 178 | href="{@docRoot}google/play/billing/v2/billing_reference.html#billing-interface">In-app Billing |
| 179 | Service Interface</a>. |
| 180 | |
| 181 | <p>One of the most important keys that every request Bundle must have is the |
| 182 | <code>BILLING_REQUEST</code> key. This key lets you specify the type of billing request you are |
| 183 | making. Google Play's in-app billing service supports the following five types of billing |
| 184 | requests:</p> |
| 185 | |
| 186 | <ul> |
| 187 | <li><code>CHECK_BILLING_SUPPORTED</code> |
| 188 | <p>This request verifies that the Google Play application supports in-app billing. You |
| 189 | usually send this request when your application first starts up. This request is useful if you |
| 190 | want to enable or disable certain UI features that are relevant only to in-app billing.</p> |
| 191 | </li> |
| 192 | <li><code>REQUEST_PURCHASE</code> |
| 193 | <p>This request sends a purchase message to the Google Play application and is the foundation |
| 194 | of in-app billing. You send this request when a user indicates that he or she wants to purchase |
| 195 | an item in your application. Google Play then handles the financial transaction by displaying |
| 196 | the checkout user interface.</p> |
| 197 | </li> |
| 198 | <li><code>GET_PURCHASE_INFORMATION</code> |
| 199 | <p>This request retrieves the details of a purchase state change. A purchase changes state when |
| 200 | a requested purchase is billed successfully or when a user cancels a transaction during |
| 201 | checkout. It can also occur when a previous purchase is refunded. Google Play notifies your |
| 202 | application when a purchase changes state, so you only need to send this request when there is |
| 203 | transaction information to retrieve.</p> |
| 204 | </li> |
| 205 | <li><code>CONFIRM_NOTIFICATIONS</code> |
| 206 | <p>This request acknowledges that your application received the details of a purchase state |
| 207 | change. Google Play sends purchase state change notifications to your application until you |
| 208 | confirm that you received them.</p> |
| 209 | </li> |
| 210 | <li><code>RESTORE_TRANSACTIONS</code> |
| 211 | <p>This request retrieves a user's transaction status for <a |
| 212 | href="{@docRoot}google/play/billing/billing_admin.html#billing-purchase-type">managed |
| 213 | purchases</a> and <a |
| 214 | href="{@docRoot}google/play/billing/billing_admin.html#billing-purchase-type">subscriptions</a>. |
| 215 | You should send this request only when you need to retrieve a user's transaction |
| 216 | status, which is usually only when your application is reinstalled or installed for the first |
| 217 | time on a device.</p> |
| 218 | </li> |
| 219 | </ul> |
| 220 | |
| 221 | <h3 id="billing-response">In-app Billing Responses</h3> |
| 222 | |
| 223 | <p>The Google Play application responds to in-app billing requests with both synchronous and |
| 224 | asynchronous responses. The synchronous response is a {@link android.os.Bundle Bundle} with the following |
| 225 | three keys:</p> |
| 226 | |
| 227 | <ul> |
| 228 | <li><code>RESPONSE_CODE</code> |
| 229 | <p>This key provides status information and error information about a request.</p> |
| 230 | </li> |
| 231 | <li><code>PURCHASE_INTENT</code> |
| 232 | <p>This key provides a {@link android.app.PendingIntent PendingIntent}, which you use to launch the checkout |
| 233 | activity.</p> |
| 234 | </li> |
| 235 | <li><code>REQUEST_ID</code> |
| 236 | <p>This key provides you with a request identifier, which you can use to match asynchronous |
| 237 | responses with requests.</p> |
| 238 | </li> |
| 239 | </ul> |
| 240 | <p>Some of these keys are not relevant to every request. For more information, see <a |
| 241 | href="#billing-message-sequence">Messaging sequence</a> later in this document.</p> |
| 242 | |
| 243 | <p>The asynchronous response messages are sent in the form of individual broadcast intents and |
| 244 | include the following:</p> |
| 245 | |
| 246 | <ul> |
| 247 | <li><code>com.android.vending.billing.RESPONSE_CODE</code> |
| 248 | <p>This response contains a Google Play server response code, and is sent after you make an |
| 249 | in-app billing request. A server response code can indicate that a billing request was |
| 250 | successfully sent to Google Play or it can indicate that some error occurred during a billing |
| 251 | request. This response is <em>not</em> used to report any purchase state changes (such as refund |
| 252 | or purchase information). For more information about the response codes that are sent with this |
| 253 | response, see <a |
| 254 | href="{@docRoot}google/play/billing/v2/billing_reference.html#billing-codes">Server Response Codes |
| 255 | for In-app Billing</a>.</p> |
| 256 | </li> |
| 257 | <li><code>com.android.vending.billing.IN_APP_NOTIFY</code> |
| 258 | <p>This response indicates that a purchase has changed state, which means a purchase succeeded, |
| 259 | was canceled, or was refunded. This response contains one or more notification IDs. Each |
| 260 | notification ID corresponds to a specific server-side message, and each messages contains |
| 261 | information about one or more transactions. After your application receives an |
| 262 | <code>IN_APP_NOTIFY</code> broadcast intent, you send a <code>GET_PURCHASE_INFORMATION</code> |
| 263 | request with the notification IDs to retrieve message details.</p> |
| 264 | </li> |
| 265 | <li><code>com.android.vending.billing.PURCHASE_STATE_CHANGED</code> |
| 266 | <p>This response contains detailed information about one or more transactions. The transaction |
| 267 | information is contained in a JSON string. The JSON string is signed and the signature is sent |
| 268 | to your application along with the JSON string (unencrypted). To help ensure the security of |
| 269 | your in-app billing messages, your application can verify the signature of this JSON string.</p> |
| 270 | </li> |
| 271 | </ul> |
| 272 | |
| 273 | <p>The JSON string that is returned with the <code>PURCHASE_STATE_CHANGED</code> intent provides |
| 274 | your application with the details of one or more billing transactions. An example of this JSON |
| 275 | string for a subscription item is shown below:</p> |
| 276 | <pre class="no-pretty-print" style="color:black">{ "nonce" : 1836535032137741465, |
| 277 | "orders" : |
| 278 | [{ "notificationId" : "android.test.purchased", |
| 279 | "orderId" : "transactionId.android.test.purchased", |
| 280 | "packageName" : "com.example.dungeons", |
| 281 | "productId" : "android.test.purchased", |
| 282 | "developerPayload" : "bGoa+V7g/yqDXvKRqq+JTFn4uQZbPiQJo4pf9RzJ", |
| 283 | "purchaseTime" : 1290114783411, |
| 284 | "purchaseState" : 0, |
| 285 | "purchaseToken" : "rojeslcdyyiapnqcynkjyyjh" }] |
| 286 | } |
| 287 | </pre> |
| 288 | |
| 289 | <p>For more information about the fields in this JSON string, see <a |
| 290 | href="{@docRoot}google/play/billing/v2/billing_reference.html#billing-intents">In-app Billing |
| 291 | Broadcast Intents</a>.</p> |
| 292 | |
| 293 | <h3 id="billing-message-sequence">Messaging sequence</h3> |
| 294 | |
| 295 | <p>The messaging sequence for a typical purchase request is shown in figure 2. Request types for |
| 296 | each <code>sendBillingRequest()</code> method are shown in <strong>bold</strong>, broadcast intents |
| 297 | are shown in <em>italic</em>. For clarity, figure 2 does not show the <code>RESPONSE_CODE</code> |
| 298 | broadcast intents that are sent for every request.</p> |
| 299 | |
| 300 | <p>The basic message sequence for an in-app purchase request is as follows:</p> |
| 301 | |
| 302 | <ol> |
| 303 | <li>Your application sends a purchase request (<code>REQUEST_PURCHASE</code> type), specifying a |
| 304 | product ID and other parameters.</li> |
| 305 | <li>The Google Play application sends your application a Bundle with the following keys: |
| 306 | <code>RESPONSE_CODE</code>, <code>PURCHASE_INTENT</code>, and <code>REQUEST_ID</code>. The |
| 307 | <code>PURCHASE_INTENT</code> key provides a {@link android.app.PendingIntent PendingIntent}, which your |
| 308 | application uses to start the checkout UI for the given product ID.</li> |
| 309 | <li>Your application launches the pending intent, which launches the checkout UI. |
| 310 | <p class="note"><strong>Note:</strong> You must launch the pending intent from an activity |
| 311 | context and not an application context.</p> |
| 312 | </li> |
| 313 | <li>When the checkout flow finishes (that is, the user successfully purchases the item or cancels |
| 314 | the purchase), Google Play sends your application a notification message (an |
| 315 | <code>IN_APP_NOTIFY</code> broadcast intent). The notification message includes a notification ID, |
| 316 | which references the transaction.</li> |
| 317 | <li>Your application requests the transaction information by sending a |
| 318 | <code>GET_PURCHASE_STATE_CHANGED</code> request, specifying the notification ID for the |
| 319 | transaction.</li> |
| 320 | <li>The Google Play application sends a Bundle with a <code>RESPONSE_CODE</code> key and a |
| 321 | <code>REQUEST_ID</code> key. |
| 322 | <li>Google Play sends the transaction information to your application in a |
| 323 | <code>PURCHASE_STATE_CHANGED</code> broadcast intent.</li> |
| 324 | <li>Your application confirms that you received the transaction information for the given |
| 325 | notification ID by sending a confirmation message (<code>CONFIRM_NOTIFICATIONS</code> type), |
| 326 | specifying the notification ID for which you received transaction information.</li> |
| 327 | <li>The Google Play application sends your application a Bundle with a |
| 328 | <code>RESPONSE_CODE</code> key and a <code>REQUEST_ID</code> key.</li> |
| 329 | </ol> |
| 330 | |
| 331 | <img src="/images/billing_request_purchase.png" height="231" id="figure2" /> |
| 332 | <p class="img-caption"> |
| 333 | <strong>Figure 2.</strong> Message sequence for a purchase request. |
| 334 | </p> |
| 335 | |
| 336 | <p>Keep in mind, you must send a confirmation when you receive transaction information from Google |
| 337 | Play (step 8 in figure 2). If you don't send a confirmation message, Google Play will |
| 338 | continue sending <code>IN_APP_NOTIFY</code> messages for the transactions you have not |
| 339 | confirmed. As a best practice, you should not send a <code>CONFIRM_NOTIFICATIONS</code> request for |
| 340 | a purchased item until you have delivered the item to the user. This way, if your application |
| 341 | crashes or something else prevents your application from delivering the product, your application |
| 342 | will still receive an <code>IN_APP_NOTIFY</code> broadcast intent from Google Play indicating |
| 343 | that you need to deliver the product. Also, as a best practice, your application must be able to |
| 344 | handle <code>IN_APP_NOTIFY</code> messages that contain multiple orders.</p> |
| 345 | |
| 346 | <p>The messaging sequence for a restore transaction request is shown in figure 3. Request types for |
| 347 | each <code>sendBillingRequest()</code> method are shown in <strong>bold</strong>, broadcast intents |
| 348 | are shown in <em>italic</em>. For clarity, figure 3 does not show the <code>RESPONSE_CODE</code> |
| 349 | broadcast intents that are sent for every request.</p> |
| 350 | |
| 351 | <div class="figure" style="width:490px"> |
| 352 | <img src="/images/billing_restore_transactions.png" alt="" height="168" /> |
| 353 | <p class="img-caption"> |
| 354 | <strong>Figure 3.</strong> Message sequence for a restore transactions request. |
| 355 | </p> |
| 356 | </div> |
| 357 | |
| 358 | <p>The request triggers three responses. The first is a {@link android.os.Bundle Bundle} with a |
| 359 | <code>RESPONSE_CODE</code> key and a <code>REQUEST_ID</code> key. Next, the Google Play |
| 360 | application sends a <code>RESPONSE_CODE</code> broadcast intent, which provides status information |
| 361 | or error information about the request. As always, the <code>RESPONSE_CODE</code> message references |
| 362 | a specific request ID, so you can determine which request a <code>RESPONSE_CODE</code> message |
| 363 | pertains to.</p> |
| 364 | |
| 365 | <p>The <code>RESTORE_TRANSACTIONS</code> request type also triggers a |
| 366 | <code>PURCHASE_STATE_CHANGED</code> broadcast intent, which contains the same type of transaction |
| 367 | information that is sent during a purchase request. Unlike with a purchase request, however, the transactions |
| 368 | are given without any associated notification IDs, so you do not need to respond to this |
| 369 | intent with a <code>CONFIRM_NOTIFICATIONS</code> message. </p> |
| 370 | |
| 371 | <p class="note"><strong>Note:</strong> You should use the <code>RESTORE_TRANSACTIONS</code> request |
| 372 | type only when your application is installed for the first time on a device or when your |
| 373 | application has been removed from a device and reinstalled.</p> |
| 374 | |
| 375 | <p>The messaging sequence for checking whether in-app billing is supported is shown in figure 4. The |
| 376 | request type for the <code>sendBillingRequest()</code> method is shown in <strong>bold</strong>.</p> |
| 377 | |
| 378 | <div class="figure" style="width:454px"> |
| 379 | <img src="/images/billing_check_supported.png" alt="" height="168" /> |
| 380 | <p class="img-caption"> |
| 381 | <strong>Figure 4.</strong> Message sequence for checking whether in-app billing is supported. |
| 382 | </p> |
| 383 | </div> |
| 384 | |
| 385 | <p>The synchronous response for a <code>CHECK_BILLING_SUPPORTED</code> request provides a Bundle |
| 386 | with a server response code. A <code>RESULT_OK</code> response code indicates that in-app billing |
| 387 | is supported; a <code>RESULT_BILLING_UNAVAILABLE</code> response code indicates that in-app billing |
| 388 | is unavailable because the API version you specified is unrecognized or the user is not eligible to |
| 389 | make in-app purchases (for example, the user resides in a country that does not allow in-app |
| 390 | billing). A <code>SERVER_ERROR</code> can also be returned, indicating that there was a problem with |
| 391 | the Google Play server.</p> |
| 392 | |
| 393 | <h3 id="billing-action-notify">Handling IN_APP_NOTIFY messages</h3> |
| 394 | |
| 395 | <p>Usually, your application receives an <code>IN_APP_NOTIFY</code> broadcast intent from Google |
| 396 | Play in response to a <code>REQUEST_PURCHASE</code> message (see figure 2). The |
| 397 | <code>IN_APP_NOTIFY</code> broadcast intent informs your application that the state of a requested |
| 398 | purchase has changed. To retrieve the details of that purchase, your application sends a |
| 399 | <code>GET_PURCHASE_INFORMATION</code> request. Google Play responds with a |
| 400 | <code>PURCHASE_STATE_CHANGED</code> broadcast intent, which contains the details of the purchase |
| 401 | state change. Your application then sends a <code>CONFIRM_NOTIFICATIONS</code> message, informing |
| 402 | Google Play that you have received the purchase state change information.</p> |
| 403 | |
| 404 | <p>In some special cases, you may receive multiple <code>IN_APP_NOTIFY</code> messages even though |
| 405 | you have confirmed receipt of the purchase information, or you may receive |
| 406 | <code>IN_APP_NOTIFY</code> messages for a purchase change even though you never initiated the |
| 407 | purchase. Your application must handle both of these special cases.</p> |
| 408 | |
| 409 | <h4>Handling multiple IN_APP_NOTIFY messages</h4> |
| 410 | |
| 411 | <p>When Google Play receives a <code>CONFIRM_NOTIFICATIONS</code> message for a given |
| 412 | <code>PURCHASE_STATE_CHANGED</code> message, it usually stops sending <code>IN_APP_NOTIFY</code> |
| 413 | intents for that <code>PURCHASE_STATE_CHANGED</code> message. Sometimes, however, Google |
| 414 | Play may send repeated <code>IN_APP_NOTIFY</code> intents for a |
| 415 | <code>PURCHASE_STATE_CHANGED</code> message even though your application has sent a |
| 416 | <code>CONFIRM_NOTIFICATIONS</code> message. This can occur if a device loses network connectivity |
| 417 | while you are sending the <code>CONFIRM_NOTIFICATIONS</code> message. In this case, Google Play |
| 418 | might not receive your <code>CONFIRM_NOTIFICATIONS</code> message and it could send multiple |
| 419 | <code>IN_APP_NOTIFY</code> messages until it receives acknowledgement that you received the |
| 420 | transaction message. Therefore, your application must be able to recognize that the subsequent |
| 421 | <code>IN_APP_NOTIFY</code> messages are for a previously processed transaction. You can do this by |
| 422 | checking the <code>orderID</code> that's contained in the JSON string because every transaction has |
| 423 | a unique <code>orderId</code>.</p> |
| 424 | |
| 425 | <h4>Handling refunds and other unsolicited IN_APP_NOTIFY messages</h4> |
| 426 | |
| 427 | <p>There are two cases where your application may receive <code>IN_APP_NOTIFY</code> broadcast |
| 428 | intents even though your application has not sent a <code>REQUEST_PURCHASE</code> message. Figure 5 |
| 429 | shows the messaging sequence for both of these cases. Request types for each |
| 430 | <code>sendBillingRequest()</code> method are shown in <strong>bold</strong>, broadcast intents are |
| 431 | shown in <em>italic</em>. For clarity, figure 5 does not show the <code>RESPONSE_CODE</code> |
| 432 | broadcast intents that are sent for every request.</p> |
| 433 | |
| 434 | <div class="figure" style="width:481px"> |
| 435 | <img src="/images/billing_refund.png" alt="" height="189" /> |
| 436 | <p class="img-caption"> |
| 437 | <strong>Figure 5.</strong> Message sequence for refunds and other unsolicited |
| 438 | IN_APP_NOTIFY messages.</p> |
| 439 | </div> |
| 440 | |
| 441 | <p>In the first case, your application may receive an <code>IN_APP_NOTIFY</code> broadcast intent |
| 442 | when a user has your application installed on two (or more) devices and the user makes an in-app |
| 443 | purchase from one of the devices. In this case, Google Play sends an <code>IN_APP_NOTIFY</code> |
| 444 | message to the second device, informing the application that there is a purchase state change. Your |
| 445 | application can handle this message the same way it handles the response from an |
| 446 | application-initiated <code>REQUEST_PURCHASE</code> message, so that ultimately your application |
| 447 | receives a <code>PURCHASE_STATE_CHANGED</code> broadcast intent message that includes information |
| 448 | about the item that has been purchased. This applies only to items that have their product type |
| 449 | set to "managed per user account."</p> |
| 450 | |
| 451 | <p>In the second case, your application can receive an <code>IN_APP_NOTIFY</code> broadcast intent |
| 452 | when Google Play receives a refund notification from Google Wallet. In this case, Google |
| 453 | Play sends an <code>IN_APP_NOTIFY</code> message to your application. Your application can handle |
| 454 | this message the same way it handles responses from an application-initiated |
| 455 | <code>REQUEST_PURCHASE</code> message so that ultimately your application receives a |
| 456 | <code>PURCHASE_STATE_CHANGED</code> message that includes information about the item that has been |
| 457 | refunded. The refund information is included in the JSON string that accompanies the |
| 458 | <code>PURCHASE_STATE_CHANGED</code> broadcast intent. Also, the <code>purchaseState</code> field in |
| 459 | the JSON string is set to 2.</p> |
| 460 | |
| 461 | <p class="caution"><strong>Important:</strong> You cannot use the Google Wallet API to |
| 462 | issue refunds or cancel in-app billing transactions. You must do this manually through your |
| 463 | Google Wallet merchant account. However, you can use the Google Wallet API to retrieve order |
| 464 | information.</p> |
| 465 | |
| 466 | <h2 id="billing-security">Security Controls</h2> |
| 467 | |
| 468 | <p>To help ensure the integrity of the transaction information that is sent to your application, |
| 469 | Google Play signs the JSON string that is contained in the <code>PURCHASE_STATE_CHANGED</code> |
| 470 | broadcast intent. Google Play uses the private key that is associated with the app to create |
| 471 | this signature. The Developer Console generates an RSA key pair for each app. |
| 472 | You can find the public key portion of this key pair in the app's publishing details |
| 473 | in the Developer Console, under <strong>Settings</strong>, in the License Key field.</p> |
| 474 | |
| 475 | <p>When Google Play signs a billing response, it includes the signed JSON string (unencrypted) |
| 476 | and the signature. When your application receives this signed response you can use the public key |
| 477 | portion of your RSA key pair to verify the signature. By performing signature verification you can |
| 478 | help detect responses that have been tampered with or that have been spoofed. You can perform this |
| 479 | signature verification step in your application; however, if your application connects to a secure |
| 480 | remote server then we recommend that you perform the signature verification on that server.</p> |
| 481 | |
| 482 | <p>In-app billing also uses nonces (a random number used once) to help verify the integrity of the |
| 483 | purchase information that's returned from Google Play. Your application must generate a nonce and |
| 484 | send it with a <code>GET_PURCHASE_INFORMATION</code> request and a <code>RESTORE_TRANSACTIONS</code> |
| 485 | request. When Google Play receives the request, it adds the nonce to the JSON string that |
| 486 | contains the transaction information. The JSON string is then signed and returned to your |
| 487 | application. When your application receives the JSON string, you need to verify the nonce as well as |
| 488 | the signature of the JSON string.</p> |
| 489 | |
| 490 | <p>For more information about best practices for security and design, see <a |
| 491 | href="{@docRoot}google/play/billing/billing_best_practices.html">Security and Design</a>.</p> |
| 492 | |
| 493 | <h2 id="billing-limitations">In-app Billing Requirements and Limitations</h2> |
| 494 | |
| 495 | <p>Before you get started with in-app billing, be sure to review the following requirements and |
| 496 | limitations.</p> |
| 497 | |
| 498 | <ul> |
| 499 | <li>In-app billing can be implemented only in applications that you publish through Google |
| 500 | Play.</li> |
| 501 | <li>You must have a Google Wallet Merchant account to use Google Play In-app Billing.</li> |
| 502 | <li>In-app billing requires version 2.3.4 (or higher) of the Android Market application. |
| 503 | To support subscriptions, version 3.5 or higher of the Google Play app is required. On devices |
| 504 | running Android 3.0, version 5.0.12 (or higher) of the MyApps application is required.</li> |
| 505 | <li>An application can use in-app billing only if the device is running Android 1.6 (API level 4) |
| 506 | or higher.</li> |
| 507 | <li>You can use in-app billing to sell only digital content. You cannot use in-app billing to sell |
| 508 | physical goods, personal services, or anything that requires physical delivery.</li> |
| 509 | <li>Google Play does not provide any form of content delivery. You are responsible for |
| 510 | delivering the digital content that you sell in your applications.</li> |
| 511 | <li>You cannot implement in-app billing on a device that never connects to the network. To |
| 512 | complete in-app purchase requests, a device must be able to access the Google Play server over |
| 513 | the network. </li> |
| 514 | </ul> |