Dirk Dougherty | 555439c | 2014-08-04 17:33:25 -0700 | [diff] [blame] | 1 | page.title=Implementing In-app Billing |
Scott Main | 50e990c | 2012-06-21 17:14:39 -0700 | [diff] [blame] | 2 | parent.title=In-app Billing |
| 3 | parent.link=index.html |
Dirk Dougherty | 555439c | 2014-08-04 17:33:25 -0700 | [diff] [blame] | 4 | page.tags="inapp, billing, iap" |
Scott Main | 50e990c | 2012-06-21 17:14:39 -0700 | [diff] [blame] | 5 | @jd:body |
| 6 | |
| 7 | <div id="qv-wrapper"> |
| 8 | <div id="qv"> |
| 9 | <h2>In this document</h2> |
| 10 | <ol> |
Quddus Chong | 768dba6 | 2012-12-08 17:06:30 -0800 | [diff] [blame] | 11 | <li><a href="#billing-add-aidl">Adding the AIDL file</a></li> |
George French | 9748d76 | 2016-09-07 09:59:32 -0700 | [diff] [blame] | 12 | <li><a href="#billing-permission">Updating your manifest</a></li> |
Quddus Chong | 768dba6 | 2012-12-08 17:06:30 -0800 | [diff] [blame] | 13 | <li><a href="#billing-service">Creating a ServiceConnection</a></li> |
George French | 9748d76 | 2016-09-07 09:59:32 -0700 | [diff] [blame] | 14 | <li><a href="#billing-requests">Making In-app Billing requests</a> |
Quddus Chong | 768dba6 | 2012-12-08 17:06:30 -0800 | [diff] [blame] | 15 | <ol> |
George French | 9748d76 | 2016-09-07 09:59:32 -0700 | [diff] [blame] | 16 | <li><a href="#QueryDetails">Querying items available for purchase</a><li> |
| 17 | <li><a href="#Purchase">Purchasing an item</a></li> |
| 18 | <li><a href="#QueryPurchases">Querying purchased items</a></li> |
| 19 | <li><a href="#Consume">Consuming a purchase</a></li> |
| 20 | <li><a href="#Subs">Implementing subscriptions</a></li> |
Quddus Chong | 768dba6 | 2012-12-08 17:06:30 -0800 | [diff] [blame] | 21 | </ol> |
| 22 | </li> |
George French | 9748d76 | 2016-09-07 09:59:32 -0700 | [diff] [blame] | 23 | <li><a href="#billing-security">Securing your app</a> |
Scott Main | 50e990c | 2012-06-21 17:14:39 -0700 | [diff] [blame] | 24 | </ol> |
Quddus Chong | 768dba6 | 2012-12-08 17:06:30 -0800 | [diff] [blame] | 25 | <h2>Reference</h2> |
Scott Main | 50e990c | 2012-06-21 17:14:39 -0700 | [diff] [blame] | 26 | <ol> |
Quddus Chong | 768dba6 | 2012-12-08 17:06:30 -0800 | [diff] [blame] | 27 | <li><a href="{@docRoot}google/play/billing/billing_reference.html">In-app Billing |
| 28 | Reference (V3)</a></li> |
| 29 | </ol> |
| 30 | <h2>Related Samples</h2> |
| 31 | <ol> |
| 32 | <li><a href="{@docRoot}training/in-app-billing/preparing-iab-app.html#GetSample">Sample Application (V3)</a></li> |
Scott Main | 50e990c | 2012-06-21 17:14:39 -0700 | [diff] [blame] | 33 | </ol> |
| 34 | <h2>See also</h2> |
| 35 | <ol> |
Quddus Chong | 768dba6 | 2012-12-08 17:06:30 -0800 | [diff] [blame] | 36 | <li><a href="{@docRoot}training/in-app-billing/index.html">Selling In-app Products</a></li> |
Quddus Chong | a0c887c | 2015-04-07 11:37:34 -0700 | [diff] [blame] | 37 | </ol> |
Scott Main | 50e990c | 2012-06-21 17:14:39 -0700 | [diff] [blame] | 38 | </div> |
| 39 | </div> |
| 40 | |
Andrew Solovay | 7e86ae8 | 2015-10-01 14:04:25 -0700 | [diff] [blame] | 41 | <p> |
| 42 | In-app Billing on Google Play provides a straightforward, simple interface |
| 43 | for sending In-app Billing requests and managing In-app Billing transactions |
| 44 | using Google Play. The information below covers the basics of how to make |
George French | 9748d76 | 2016-09-07 09:59:32 -0700 | [diff] [blame] | 45 | calls from your application to the In-app Billing service using the In-app Billing Version 3 |
Andrew Solovay | 7e86ae8 | 2015-10-01 14:04:25 -0700 | [diff] [blame] | 46 | API. |
| 47 | </p> |
Scott Main | 50e990c | 2012-06-21 17:14:39 -0700 | [diff] [blame] | 48 | |
Andrew Solovay | 7e86ae8 | 2015-10-01 14:04:25 -0700 | [diff] [blame] | 49 | <p class="note"> |
| 50 | <strong>Note:</strong> To see a complete implementation and learn how to test |
| 51 | your application, see the <a href= |
| 52 | "{@docRoot}training/in-app-billing/index.html">Selling In-app Products</a> |
| 53 | training class. The training class provides a complete sample In-app Billing |
George French | 9748d76 | 2016-09-07 09:59:32 -0700 | [diff] [blame] | 54 | application, including convenience classes to handle key tasks that are related to |
| 55 | setting up your connection, sending billing requests, processing responses |
Andrew Solovay | 7e86ae8 | 2015-10-01 14:04:25 -0700 | [diff] [blame] | 56 | from Google Play, and managing background threading so that you can make |
| 57 | In-app Billing calls from your main activity. |
| 58 | </p> |
Scott Main | 50e990c | 2012-06-21 17:14:39 -0700 | [diff] [blame] | 59 | |
Andrew Solovay | 7e86ae8 | 2015-10-01 14:04:25 -0700 | [diff] [blame] | 60 | <p> |
George French | 9748d76 | 2016-09-07 09:59:32 -0700 | [diff] [blame] | 61 | Before you start, read the <a href= |
Andrew Solovay | 7e86ae8 | 2015-10-01 14:04:25 -0700 | [diff] [blame] | 62 | "{@docRoot}google/play/billing/billing_overview.html">In-app Billing |
George French | 9748d76 | 2016-09-07 09:59:32 -0700 | [diff] [blame] | 63 | Overview</a> to familiarize yourself with concepts that make it easier |
Andrew Solovay | 7e86ae8 | 2015-10-01 14:04:25 -0700 | [diff] [blame] | 64 | for you to implement In-app Billing. |
| 65 | </p> |
Quddus Chong | 768dba6 | 2012-12-08 17:06:30 -0800 | [diff] [blame] | 66 | |
George French | 9748d76 | 2016-09-07 09:59:32 -0700 | [diff] [blame] | 67 | <p>Complete these steps to implement In-app Billing in your application:</p> |
Andrew Solovay | 7e86ae8 | 2015-10-01 14:04:25 -0700 | [diff] [blame] | 68 | |
Scott Main | 50e990c | 2012-06-21 17:14:39 -0700 | [diff] [blame] | 69 | <ol> |
Quddus Chong | 768dba6 | 2012-12-08 17:06:30 -0800 | [diff] [blame] | 70 | <li>Add the In-app Billing library to your project.</li> |
| 71 | <li>Update your {@code AndroidManifest.xml} file.</li> |
George French | 9748d76 | 2016-09-07 09:59:32 -0700 | [diff] [blame] | 72 | <li>Create a {@code ServiceConnection} and bind it to the |
quddusc | 5319f31 | 2013-02-27 14:44:18 -0800 | [diff] [blame] | 73 | {@code IInAppBillingService}.</li> |
Quddus Chong | a0c887c | 2015-04-07 11:37:34 -0700 | [diff] [blame] | 74 | <li>Send In-app Billing requests from your application to |
quddusc | 5319f31 | 2013-02-27 14:44:18 -0800 | [diff] [blame] | 75 | {@code IInAppBillingService}.</li> |
Quddus Chong | 768dba6 | 2012-12-08 17:06:30 -0800 | [diff] [blame] | 76 | <li>Handle In-app Billing responses from Google Play.</li> |
Scott Main | 50e990c | 2012-06-21 17:14:39 -0700 | [diff] [blame] | 77 | </ol> |
| 78 | |
Scott Main | 50e990c | 2012-06-21 17:14:39 -0700 | [diff] [blame] | 79 | <h2 id="billing-add-aidl">Adding the AIDL file to your project</h2> |
| 80 | |
George French | 9748d76 | 2016-09-07 09:59:32 -0700 | [diff] [blame] | 81 | <p>The {@code IInAppBillingService.aidl} is an Android Interface Definition |
Quddus Chong | a0c887c | 2015-04-07 11:37:34 -0700 | [diff] [blame] | 82 | Language (AIDL) file that defines the interface to the In-app Billing Version |
George French | 9748d76 | 2016-09-07 09:59:32 -0700 | [diff] [blame] | 83 | 3 service. You can use this interface to make billing requests by invoking IPC |
quddusc | 5319f31 | 2013-02-27 14:44:18 -0800 | [diff] [blame] | 84 | method calls.</p> |
George French | 9748d76 | 2016-09-07 09:59:32 -0700 | [diff] [blame] | 85 | |
| 86 | <p>Complete these steps to get the AIDL file:</p> |
quddusc | 5319f31 | 2013-02-27 14:44:18 -0800 | [diff] [blame] | 87 | <ol> |
| 88 | <li>Open the <a href="{@docRoot}tools/help/sdk-manager.html">Android SDK Manager</a>.</li> |
| 89 | <li>In the SDK Manager, expand the {@code Extras} section.</li> |
| 90 | <li>Select <strong>Google Play Billing Library</strong>.</li> |
| 91 | <li>Click <strong>Install packages</strong> to complete the download.</li> |
| 92 | </ol> |
George French | 9748d76 | 2016-09-07 09:59:32 -0700 | [diff] [blame] | 93 | <p>The {@code IInAppBillingService.aidl} file will be installed to {@code <sdk>/extras/google/play_billing/}.</p> |
Scott Main | 50e990c | 2012-06-21 17:14:39 -0700 | [diff] [blame] | 94 | |
George French | 9748d76 | 2016-09-07 09:59:32 -0700 | [diff] [blame] | 95 | <p>Complete these steps to add the AIDL to your project:</p> |
Scott Main | 50e990c | 2012-06-21 17:14:39 -0700 | [diff] [blame] | 96 | |
Andrew Solovay | 7e86ae8 | 2015-10-01 14:04:25 -0700 | [diff] [blame] | 97 | <ol> |
George French | 9748d76 | 2016-09-07 09:59:32 -0700 | [diff] [blame] | 98 | <li>Download the Google Play Billing Library to your Android project: |
Joe Fernandez | 0832001 | 2016-01-04 16:24:22 -0800 | [diff] [blame] | 99 | <ol type="a"> |
| 100 | <li>Select <strong>Tools > Android > SDK Manager</strong>.</li> |
| 101 | <li>Under <strong>Appearance & Behavior > System Settings > Android SDK</strong>, |
| 102 | select the <em>SDK Tools</em> tab to select and download <em>Google Play Billing |
| 103 | Library</em>.</li></ol> |
| 104 | |
George French | 9748d76 | 2016-09-07 09:59:32 -0700 | [diff] [blame] | 105 | <li>Copy the {@code IInAppBillingService.aidl} file to your project. |
Andrew Solovay | 7e86ae8 | 2015-10-01 14:04:25 -0700 | [diff] [blame] | 106 | <ul> |
George French | 9748d76 | 2016-09-07 09:59:32 -0700 | [diff] [blame] | 107 | <li>If you are using Android Studio, complete these steps to copy the file: |
Andrew Solovay | 7e86ae8 | 2015-10-01 14:04:25 -0700 | [diff] [blame] | 108 | <ol type="a"> |
Joe Fernandez | 0832001 | 2016-01-04 16:24:22 -0800 | [diff] [blame] | 109 | <li>Navigate to {@code src/main} in the Project tool window.</li> |
Andrew Solovay | 7e86ae8 | 2015-10-01 14:04:25 -0700 | [diff] [blame] | 110 | |
George French | 9748d76 | 2016-09-07 09:59:32 -0700 | [diff] [blame] | 111 | <li>Select <strong>File > New > Directory</strong>, enter {@code aidl} in the |
| 112 | <em>New Directory</em> window, and select <strong>OK</strong>. |
Andrew Solovay | 7e86ae8 | 2015-10-01 14:04:25 -0700 | [diff] [blame] | 113 | |
George French | 9748d76 | 2016-09-07 09:59:32 -0700 | [diff] [blame] | 114 | <li>Select <strong>File > New > Package</strong>, enter |
| 115 | {@code com.android.vending.billing} in the <em>New Package</em> window, and select |
Joe Fernandez | 0832001 | 2016-01-04 16:24:22 -0800 | [diff] [blame] | 116 | <strong>OK</strong>.</li> |
| 117 | |
Kevin Hufnagle | 5deb0d6 | 2016-05-10 18:03:42 -0700 | [diff] [blame] | 118 | <li>Using your operating system file explorer, navigate to |
George French | 9748d76 | 2016-09-07 09:59:32 -0700 | [diff] [blame] | 119 | {@code <sdk>/extras/google/play_billing/}, copy the |
Kevin Hufnagle | 5deb0d6 | 2016-05-10 18:03:42 -0700 | [diff] [blame] | 120 | {@code IInAppBillingService.aidl} file, and paste it into the |
Joe Fernandez | 0832001 | 2016-01-04 16:24:22 -0800 | [diff] [blame] | 121 | {@code com.android.vending.billing} package in your project. |
Andrew Solovay | 7e86ae8 | 2015-10-01 14:04:25 -0700 | [diff] [blame] | 122 | </li> |
| 123 | </ol> |
| 124 | </li> |
| 125 | |
George French | 9748d76 | 2016-09-07 09:59:32 -0700 | [diff] [blame] | 126 | <li>If you are developing in a non-Android Studio environment, create the |
| 127 | following directory: {@code /src/com/android/vending/billing}. Copy the |
| 128 | {@code IInAppBillingService.aidl} file into this directory. Place the AIDL |
| 129 | file in your project and use the Gradle tool to build your project so that |
| 130 | the <code>IInAppBillingService.java</code> file is generated. |
Andrew Solovay | 7e86ae8 | 2015-10-01 14:04:25 -0700 | [diff] [blame] | 131 | </li> |
| 132 | </ul> |
| 133 | </li> |
| 134 | |
| 135 | <li>Build your application. You should see a generated file named {@code |
| 136 | IInAppBillingService.java} in the {@code /gen} directory of your project. |
| 137 | </li> |
| 138 | </ol> |
Scott Main | 50e990c | 2012-06-21 17:14:39 -0700 | [diff] [blame] | 139 | |
George French | 9748d76 | 2016-09-07 09:59:32 -0700 | [diff] [blame] | 140 | <h2 id="billing-permission">Updating your app's manifest</h2> |
Scott Main | 50e990c | 2012-06-21 17:14:39 -0700 | [diff] [blame] | 141 | |
Andrew Solovay | 7e86ae8 | 2015-10-01 14:04:25 -0700 | [diff] [blame] | 142 | <p> |
| 143 | In-app billing relies on the Google Play application, which handles all |
George French | 9748d76 | 2016-09-07 09:59:32 -0700 | [diff] [blame] | 144 | of the communication between your application and the Google Play server. To use the |
Andrew Solovay | 7e86ae8 | 2015-10-01 14:04:25 -0700 | [diff] [blame] | 145 | Google Play application, your application must request the proper permission. |
| 146 | You can do this by adding the {@code com.android.vending.BILLING} permission |
| 147 | to your AndroidManifest.xml file. If your application does not declare the |
| 148 | In-app Billing permission, but attempts to send billing requests, Google Play |
George French | 9748d76 | 2016-09-07 09:59:32 -0700 | [diff] [blame] | 149 | refuses the requests and responds with an error. |
Andrew Solovay | 7e86ae8 | 2015-10-01 14:04:25 -0700 | [diff] [blame] | 150 | </p> |
Scott Main | 50e990c | 2012-06-21 17:14:39 -0700 | [diff] [blame] | 151 | |
Andrew Solovay | 7e86ae8 | 2015-10-01 14:04:25 -0700 | [diff] [blame] | 152 | <p> |
Hemal Patel | a1ed45d | 2016-05-19 14:13:29 -0700 | [diff] [blame] | 153 | To give your app the necessary permission, add this line in the {@code |
| 154 | AndroidManifest.xml} file: |
Andrew Solovay | 7e86ae8 | 2015-10-01 14:04:25 -0700 | [diff] [blame] | 155 | </p> |
| 156 | |
Scott Main | 50e990c | 2012-06-21 17:14:39 -0700 | [diff] [blame] | 157 | <pre> |
Quddus Chong | 768dba6 | 2012-12-08 17:06:30 -0800 | [diff] [blame] | 158 | <uses-permission android:name="com.android.vending.BILLING" /> |
Scott Main | 50e990c | 2012-06-21 17:14:39 -0700 | [diff] [blame] | 159 | </pre> |
| 160 | |
Quddus Chong | 768dba6 | 2012-12-08 17:06:30 -0800 | [diff] [blame] | 161 | <h2 id="billing-service">Creating a ServiceConnection</h2> |
Scott Main | 50e990c | 2012-06-21 17:14:39 -0700 | [diff] [blame] | 162 | |
Andrew Solovay | 7e86ae8 | 2015-10-01 14:04:25 -0700 | [diff] [blame] | 163 | <p> |
| 164 | Your application must have a {@link android.content.ServiceConnection} to |
| 165 | facilitate messaging between your application and Google Play. At a minimum, |
| 166 | your application must do the following: |
| 167 | </p> |
Scott Main | 50e990c | 2012-06-21 17:14:39 -0700 | [diff] [blame] | 168 | |
| 169 | <ul> |
Quddus Chong | 768dba6 | 2012-12-08 17:06:30 -0800 | [diff] [blame] | 170 | <li>Bind to {@code IInAppBillingService}. |
| 171 | <li>Send billing requests (as IPC method calls) to the Google Play application.</li> |
Scott Main | 50e990c | 2012-06-21 17:14:39 -0700 | [diff] [blame] | 172 | <li>Handle the synchronous response messages that are returned with each billing request.</li> |
| 173 | </ul> |
| 174 | |
Quddus Chong | 768dba6 | 2012-12-08 17:06:30 -0800 | [diff] [blame] | 175 | <h3>Binding to IInAppBillingService</h3> |
Andrew Solovay | 7e86ae8 | 2015-10-01 14:04:25 -0700 | [diff] [blame] | 176 | |
| 177 | <p> |
| 178 | To establish a connection with the In-app Billing service on Google Play, |
| 179 | implement a {@link android.content.ServiceConnection} to bind your activity |
| 180 | to {@code IInAppBillingService}. Override the {@link |
| 181 | android.content.ServiceConnection#onServiceDisconnected |
| 182 | onServiceDisconnected} and {@link |
| 183 | android.content.ServiceConnection#onServiceConnected onServiceConnected} |
| 184 | methods to get a reference to the {@code IInAppBillingService} instance after |
George French | 9748d76 | 2016-09-07 09:59:32 -0700 | [diff] [blame] | 185 | a connection is established. |
Andrew Solovay | 7e86ae8 | 2015-10-01 14:04:25 -0700 | [diff] [blame] | 186 | </p> |
| 187 | |
Scott Main | 50e990c | 2012-06-21 17:14:39 -0700 | [diff] [blame] | 188 | <pre> |
Quddus Chong | 768dba6 | 2012-12-08 17:06:30 -0800 | [diff] [blame] | 189 | IInAppBillingService mService; |
| 190 | |
| 191 | ServiceConnection mServiceConn = new ServiceConnection() { |
| 192 | @Override |
| 193 | public void onServiceDisconnected(ComponentName name) { |
| 194 | mService = null; |
| 195 | } |
| 196 | |
| 197 | @Override |
Quddus Chong | a0c887c | 2015-04-07 11:37:34 -0700 | [diff] [blame] | 198 | public void onServiceConnected(ComponentName name, |
Quddus Chong | 768dba6 | 2012-12-08 17:06:30 -0800 | [diff] [blame] | 199 | IBinder service) { |
| 200 | mService = IInAppBillingService.Stub.asInterface(service); |
| 201 | } |
| 202 | }; |
| 203 | </pre> |
| 204 | |
Andrew Solovay | 7e86ae8 | 2015-10-01 14:04:25 -0700 | [diff] [blame] | 205 | <p> |
| 206 | In your activity’s {@link android.app.Activity#onCreate onCreate} method, |
| 207 | perform the binding by calling the {@link android.content.Context#bindService |
| 208 | bindService} method. Pass the method an {@link android.content.Intent} that |
| 209 | references the In-app Billing service and an instance of the {@link |
| 210 | android.content.ServiceConnection} that you created, and explicitly set the |
George French | 9748d76 | 2016-09-07 09:59:32 -0700 | [diff] [blame] | 211 | Intent's target package name to <code>com.android.vending</code>—the |
Andrew Solovay | 7e86ae8 | 2015-10-01 14:04:25 -0700 | [diff] [blame] | 212 | package name of Google Play app. |
| 213 | </p> |
Dirk Dougherty | 555439c | 2014-08-04 17:33:25 -0700 | [diff] [blame] | 214 | |
Andrew Solovay | 7e86ae8 | 2015-10-01 14:04:25 -0700 | [diff] [blame] | 215 | <p class="caution"> |
| 216 | <strong>Caution:</strong> To protect the security of billing transactions, |
George French | 9748d76 | 2016-09-07 09:59:32 -0700 | [diff] [blame] | 217 | always explicitly set the intent's target package name to |
Andrew Solovay | 7e86ae8 | 2015-10-01 14:04:25 -0700 | [diff] [blame] | 218 | <code>com.android.vending</code>, using {@link |
George French | 9748d76 | 2016-09-07 09:59:32 -0700 | [diff] [blame] | 219 | android.content.Intent#setPackage(java.lang.String) setPackage()}. |
| 220 | Setting the package name explicitly ensures that |
Andrew Solovay | 7e86ae8 | 2015-10-01 14:04:25 -0700 | [diff] [blame] | 221 | <em>only</em> the Google Play app can handle billing requests from your app, |
| 222 | preventing other apps from intercepting those requests. |
| 223 | </p> |
Dirk Dougherty | 555439c | 2014-08-04 17:33:25 -0700 | [diff] [blame] | 224 | |
George French | 9748d76 | 2016-09-07 09:59:32 -0700 | [diff] [blame] | 225 | <p> |
| 226 | The following code sample demonstrates how to set the intent's target package |
| 227 | to protect the security of transactions: |
| 228 | </p> |
| 229 | |
Dirk Dougherty | 555439c | 2014-08-04 17:33:25 -0700 | [diff] [blame] | 230 | <pre>@Override |
| 231 | public void onCreate(Bundle savedInstanceState) { |
| 232 | super.onCreate(savedInstanceState); |
| 233 | setContentView(R.layout.activity_main); |
Andrew Solovay | 8e34a80 | 2015-11-05 14:10:29 -0800 | [diff] [blame] | 234 | Intent serviceIntent = |
| 235 | new Intent("com.android.vending.billing.InAppBillingService.BIND"); |
Dirk Dougherty | 555439c | 2014-08-04 17:33:25 -0700 | [diff] [blame] | 236 | serviceIntent.setPackage("com.android.vending"); |
| 237 | bindService(serviceIntent, mServiceConn, Context.BIND_AUTO_CREATE); |
Andrew Solovay | 8e34a80 | 2015-11-05 14:10:29 -0800 | [diff] [blame] | 238 | } |
Quddus Chong | 768dba6 | 2012-12-08 17:06:30 -0800 | [diff] [blame] | 239 | </pre> |
Andrew Solovay | 7e86ae8 | 2015-10-01 14:04:25 -0700 | [diff] [blame] | 240 | |
George French | 9748d76 | 2016-09-07 09:59:32 -0700 | [diff] [blame] | 241 | <p class="caution"><strong>Caution</strong>: To ensure that your app is secure, always use an |
| 242 | explicit intent when starting a {@link android.app.Service} and do not declare intent filters for |
| 243 | your services. Using an implicit intent to start a service is a security hazard because you cannot |
| 244 | be certain of the service that will respond to the intent, and the user cannot see which service |
| 245 | starts. Beginning with Android 5.0 (API level 21), the system throws an exception if you call |
| 246 | {@link android.content.Context#bindService bindService()} with an implicit intent.</p> |
| 247 | |
Andrew Solovay | 7e86ae8 | 2015-10-01 14:04:25 -0700 | [diff] [blame] | 248 | <p> |
| 249 | You can now use the mService reference to communicate with the Google Play |
| 250 | service. |
| 251 | </p> |
| 252 | |
| 253 | <p class="note"> |
| 254 | <strong>Important:</strong> Remember to unbind from the In-app Billing |
| 255 | service when you are done with your {@link android.app.Activity}. If you |
| 256 | don’t unbind, the open service connection could cause your device’s |
George French | 9748d76 | 2016-09-07 09:59:32 -0700 | [diff] [blame] | 257 | performance to degrade. |
| 258 | </p> |
| 259 | |
| 260 | <p> |
| 261 | This example shows how to perform the unbind |
Andrew Solovay | 7e86ae8 | 2015-10-01 14:04:25 -0700 | [diff] [blame] | 262 | operation on a service connection to In-app Billing called {@code |
| 263 | mServiceConn} by overriding the activity’s {@link |
George French | 9748d76 | 2016-09-07 09:59:32 -0700 | [diff] [blame] | 264 | android.app.Activity#onDestroy onDestroy} method: |
Andrew Solovay | 7e86ae8 | 2015-10-01 14:04:25 -0700 | [diff] [blame] | 265 | </p> |
| 266 | |
Quddus Chong | 768dba6 | 2012-12-08 17:06:30 -0800 | [diff] [blame] | 267 | <pre> |
| 268 | @Override |
| 269 | public void onDestroy() { |
Scott Main | 6aad995 | 2013-01-07 18:51:49 -0800 | [diff] [blame] | 270 | super.onDestroy(); |
quddusc | fca563a | 2013-12-20 15:21:38 -0800 | [diff] [blame] | 271 | if (mService != null) { |
Scott Main | 6aad995 | 2013-01-07 18:51:49 -0800 | [diff] [blame] | 272 | unbindService(mServiceConn); |
Quddus Chong | a0c887c | 2015-04-07 11:37:34 -0700 | [diff] [blame] | 273 | } |
Scott Main | 50e990c | 2012-06-21 17:14:39 -0700 | [diff] [blame] | 274 | } |
| 275 | </pre> |
| 276 | |
Andrew Solovay | 7e86ae8 | 2015-10-01 14:04:25 -0700 | [diff] [blame] | 277 | <p> |
| 278 | For a complete implementation of a service connection that binds to the |
| 279 | {@code IInAppBillingService}, see the <a href= |
| 280 | "{@docRoot}training/in-app-billing/preparing-iab-app.html">Selling In-app |
| 281 | Products</a> training class and associated sample. |
| 282 | </p> |
George French | 9748d76 | 2016-09-07 09:59:32 -0700 | [diff] [blame] | 283 | <h2 id="billing-requests">Making In-app Billing requests</h2> |
Andrew Solovay | 7e86ae8 | 2015-10-01 14:04:25 -0700 | [diff] [blame] | 284 | <p> |
George French | 9748d76 | 2016-09-07 09:59:32 -0700 | [diff] [blame] | 285 | After your application is connected to Google Play, you can initiate purchase |
Andrew Solovay | 7e86ae8 | 2015-10-01 14:04:25 -0700 | [diff] [blame] | 286 | requests for in-app products. Google Play provides a checkout interface for |
George French | 9748d76 | 2016-09-07 09:59:32 -0700 | [diff] [blame] | 287 | users to enter their payment method, so your application doesn't need to |
Andrew Solovay | 7e86ae8 | 2015-10-01 14:04:25 -0700 | [diff] [blame] | 288 | handle payment transactions directly. When an item is purchased, Google Play |
| 289 | recognizes that the user has ownership of that item and prevents the user |
| 290 | from purchasing another item with the same product ID until it is consumed. |
George French | 9748d76 | 2016-09-07 09:59:32 -0700 | [diff] [blame] | 291 | You can control how the item is consumed in your application and notify |
Andrew Solovay | 7e86ae8 | 2015-10-01 14:04:25 -0700 | [diff] [blame] | 292 | Google Play to make the item available for purchase again. You can also query |
George French | 9748d76 | 2016-09-07 09:59:32 -0700 | [diff] [blame] | 293 | Google Play to quickly retrieve the list of purchases that the |
| 294 | user made. This is useful, for example, when you want to restore the user's |
Andrew Solovay | 7e86ae8 | 2015-10-01 14:04:25 -0700 | [diff] [blame] | 295 | purchases when your user launches your app. |
Scott Main | 50e990c | 2012-06-21 17:14:39 -0700 | [diff] [blame] | 296 | </p> |
| 297 | |
George French | 9748d76 | 2016-09-07 09:59:32 -0700 | [diff] [blame] | 298 | <h3 id="QueryDetails">Querying for items available for purchase</h3> |
Andrew Solovay | 7e86ae8 | 2015-10-01 14:04:25 -0700 | [diff] [blame] | 299 | |
| 300 | <p> |
| 301 | In your application, you can query the item details from Google Play using |
| 302 | the In-app Billing Version 3 API. To pass a request to the In-app Billing |
George French | 9748d76 | 2016-09-07 09:59:32 -0700 | [diff] [blame] | 303 | service, create a {@link android.os.Bundle} that contains a String |
Andrew Solovay | 7e86ae8 | 2015-10-01 14:04:25 -0700 | [diff] [blame] | 304 | {@link java.util.ArrayList} of product IDs with key "ITEM_ID_LIST", where |
George French | 9748d76 | 2016-09-07 09:59:32 -0700 | [diff] [blame] | 305 | each string is a product ID for an purchasable item. Here is an example: |
Andrew Solovay | 7e86ae8 | 2015-10-01 14:04:25 -0700 | [diff] [blame] | 306 | </p> |
| 307 | |
Quddus Chong | 768dba6 | 2012-12-08 17:06:30 -0800 | [diff] [blame] | 308 | <pre> |
quddusc | 896e974 | 2014-01-06 11:36:07 -0800 | [diff] [blame] | 309 | ArrayList<String> skuList = new ArrayList<String> (); |
Quddus Chong | 768dba6 | 2012-12-08 17:06:30 -0800 | [diff] [blame] | 310 | skuList.add("premiumUpgrade"); |
| 311 | skuList.add("gas"); |
| 312 | Bundle querySkus = new Bundle(); |
| 313 | querySkus.putStringArrayList(“ITEM_ID_LIST”, skuList); |
| 314 | </pre> |
Andrew Solovay | 7e86ae8 | 2015-10-01 14:04:25 -0700 | [diff] [blame] | 315 | |
| 316 | <p> |
| 317 | To retrieve this information from Google Play, call the {@code getSkuDetails} |
George French | 9748d76 | 2016-09-07 09:59:32 -0700 | [diff] [blame] | 318 | method on the In-app Billing Version 3 API and pass the In-app |
Andrew Solovay | 7e86ae8 | 2015-10-01 14:04:25 -0700 | [diff] [blame] | 319 | Billing API version (“3”), the package name of your calling app, the purchase |
George French | 9748d76 | 2016-09-07 09:59:32 -0700 | [diff] [blame] | 320 | type (“inapp”), and the {@link android.os.Bundle} that you created, into the method: |
Andrew Solovay | 7e86ae8 | 2015-10-01 14:04:25 -0700 | [diff] [blame] | 321 | </p> |
| 322 | |
Quddus Chong | 768dba6 | 2012-12-08 17:06:30 -0800 | [diff] [blame] | 323 | <pre> |
Quddus Chong | a0c887c | 2015-04-07 11:37:34 -0700 | [diff] [blame] | 324 | Bundle skuDetails = mService.getSkuDetails(3, |
Scott Kennedy | 7ed189e | 2013-01-11 22:31:43 -0800 | [diff] [blame] | 325 | getPackageName(), "inapp", querySkus); |
Quddus Chong | 768dba6 | 2012-12-08 17:06:30 -0800 | [diff] [blame] | 326 | </pre> |
Scott Main | 50e990c | 2012-06-21 17:14:39 -0700 | [diff] [blame] | 327 | |
Andrew Solovay | 7e86ae8 | 2015-10-01 14:04:25 -0700 | [diff] [blame] | 328 | <p> |
George French | 9748d76 | 2016-09-07 09:59:32 -0700 | [diff] [blame] | 329 | If the request is successful, the returned {@link android.os.Bundle} has a |
Andrew Solovay | 7e86ae8 | 2015-10-01 14:04:25 -0700 | [diff] [blame] | 330 | response code of {@code BILLING_RESPONSE_RESULT_OK} (0). |
| 331 | </p> |
Scott Main | 50e990c | 2012-06-21 17:14:39 -0700 | [diff] [blame] | 332 | |
Andrew Solovay | 7e86ae8 | 2015-10-01 14:04:25 -0700 | [diff] [blame] | 333 | <p class="note"> |
George French | 9748d76 | 2016-09-07 09:59:32 -0700 | [diff] [blame] | 334 | <strong>Warning:</strong> Don't call the {@code getSkuDetails} method on the |
| 335 | main thread. Calling this method triggers a network request that could block |
Andrew Solovay | 7e86ae8 | 2015-10-01 14:04:25 -0700 | [diff] [blame] | 336 | your main thread. Instead, create a separate thread and call the {@code |
George French | 9748d76 | 2016-09-07 09:59:32 -0700 | [diff] [blame] | 337 | getSkuDetails} method from inside of that thread. |
Andrew Solovay | 7e86ae8 | 2015-10-01 14:04:25 -0700 | [diff] [blame] | 338 | </p> |
Scott Main | 50e990c | 2012-06-21 17:14:39 -0700 | [diff] [blame] | 339 | |
Andrew Solovay | 7e86ae8 | 2015-10-01 14:04:25 -0700 | [diff] [blame] | 340 | <p> |
George French | 9748d76 | 2016-09-07 09:59:32 -0700 | [diff] [blame] | 341 | To view all of the possible response codes from Google Play, see <a href= |
Andrew Solovay | 7e86ae8 | 2015-10-01 14:04:25 -0700 | [diff] [blame] | 342 | "{@docRoot}google/play/billing/billing_reference.html#billing-codes">In-app |
| 343 | Billing Reference</a>. |
| 344 | </p> |
| 345 | |
| 346 | <p> |
| 347 | The query results are stored in a String ArrayList with key {@code |
George French | 9748d76 | 2016-09-07 09:59:32 -0700 | [diff] [blame] | 348 | DETAILS_LIST}. The purchase information is stored within the String in JSON |
| 349 | format. To view the types of product detail information that are returned, see |
Andrew Solovay | 7e86ae8 | 2015-10-01 14:04:25 -0700 | [diff] [blame] | 350 | <a href= |
| 351 | "{@docRoot}google/play/billing/billing_reference.html#getSkuDetails">In-app |
| 352 | Billing Reference</a>. |
| 353 | </p> |
| 354 | |
| 355 | <p> |
George French | 9748d76 | 2016-09-07 09:59:32 -0700 | [diff] [blame] | 356 | In this example shows how to retrieve the prices for your in-app items from the |
| 357 | skuDetails {@link android.os.Bundle} that is returned from the previous code snippet: |
Andrew Solovay | 7e86ae8 | 2015-10-01 14:04:25 -0700 | [diff] [blame] | 358 | </p> |
| 359 | |
Quddus Chong | 768dba6 | 2012-12-08 17:06:30 -0800 | [diff] [blame] | 360 | <pre> |
| 361 | int response = skuDetails.getInt("RESPONSE_CODE"); |
| 362 | if (response == 0) { |
quddusc | 896e974 | 2014-01-06 11:36:07 -0800 | [diff] [blame] | 363 | ArrayList<String> responseList |
Quddus Chong | 768dba6 | 2012-12-08 17:06:30 -0800 | [diff] [blame] | 364 | = skuDetails.getStringArrayList("DETAILS_LIST"); |
Quddus Chong | a0c887c | 2015-04-07 11:37:34 -0700 | [diff] [blame] | 365 | |
Quddus Chong | 768dba6 | 2012-12-08 17:06:30 -0800 | [diff] [blame] | 366 | for (String thisResponse : responseList) { |
| 367 | JSONObject object = new JSONObject(thisResponse); |
| 368 | String sku = object.getString("productId"); |
| 369 | String price = object.getString("price"); |
Scott Kennedy | 7ed189e | 2013-01-11 22:31:43 -0800 | [diff] [blame] | 370 | if (sku.equals("premiumUpgrade")) mPremiumUpgradePrice = price; |
| 371 | else if (sku.equals("gas")) mGasPrice = price; |
Quddus Chong | 768dba6 | 2012-12-08 17:06:30 -0800 | [diff] [blame] | 372 | } |
| 373 | } |
| 374 | </pre> |
Scott Main | 50e990c | 2012-06-21 17:14:39 -0700 | [diff] [blame] | 375 | |
George French | 9748d76 | 2016-09-07 09:59:32 -0700 | [diff] [blame] | 376 | <h3 id="Purchase">Purchasing an item</h3> |
Andrew Solovay | 7e86ae8 | 2015-10-01 14:04:25 -0700 | [diff] [blame] | 377 | <p> |
| 378 | To start a purchase request from your app, call the {@code getBuyIntent} |
George French | 9748d76 | 2016-09-07 09:59:32 -0700 | [diff] [blame] | 379 | method on the In-app Billing service. Pass the In-app |
Andrew Solovay | 7e86ae8 | 2015-10-01 14:04:25 -0700 | [diff] [blame] | 380 | Billing API version (“3”), the package name of your calling app, the product |
| 381 | ID for the item to purchase, the purchase type (“inapp” or "subs"), and a |
George French | 9748d76 | 2016-09-07 09:59:32 -0700 | [diff] [blame] | 382 | {@code developerPayload} String into the method. The {@code developerPayload} String is used |
Andrew Solovay | 7e86ae8 | 2015-10-01 14:04:25 -0700 | [diff] [blame] | 383 | to specify any additional arguments that you want Google Play to send back |
George French | 9748d76 | 2016-09-07 09:59:32 -0700 | [diff] [blame] | 384 | along with the purchase information. Here is an example: |
Andrew Solovay | 7e86ae8 | 2015-10-01 14:04:25 -0700 | [diff] [blame] | 385 | </p> |
Scott Main | 50e990c | 2012-06-21 17:14:39 -0700 | [diff] [blame] | 386 | |
Quddus Chong | 768dba6 | 2012-12-08 17:06:30 -0800 | [diff] [blame] | 387 | <pre> |
| 388 | Bundle buyIntentBundle = mService.getBuyIntent(3, getPackageName(), |
| 389 | sku, "inapp", "bGoa+V7g/yqDXvKRqq+JTFn4uQZbPiQJo4pf9RzJ"); |
| 390 | </pre> |
Andrew Solovay | 7e86ae8 | 2015-10-01 14:04:25 -0700 | [diff] [blame] | 391 | |
Quddus Chong | 768dba6 | 2012-12-08 17:06:30 -0800 | [diff] [blame] | 392 | <p> |
Andrew Solovay | 7e86ae8 | 2015-10-01 14:04:25 -0700 | [diff] [blame] | 393 | If the request is successful, the returned {@link android.os.Bundle} has a |
| 394 | response code of {@code BILLING_RESPONSE_RESULT_OK} (0) and a {@link |
| 395 | android.app.PendingIntent} that you can use to start the purchase flow. To |
George French | 9748d76 | 2016-09-07 09:59:32 -0700 | [diff] [blame] | 396 | view all of the possible response codes from Google Play, see <a href= |
Andrew Solovay | 7e86ae8 | 2015-10-01 14:04:25 -0700 | [diff] [blame] | 397 | "{@docRoot}google/play/billing/billing_reference.html#billing-codes">In-app |
George French | 9748d76 | 2016-09-07 09:59:32 -0700 | [diff] [blame] | 398 | Billing Reference</a>. |
| 399 | |
| 400 | <p> |
| 401 | The next step is to extract a {@link android.app.PendingIntent} from |
| 402 | the response {@link android.os.Bundle} with key {@code BUY_INTENT}, as shown here: |
Quddus Chong | 768dba6 | 2012-12-08 17:06:30 -0800 | [diff] [blame] | 403 | </p> |
Andrew Solovay | 7e86ae8 | 2015-10-01 14:04:25 -0700 | [diff] [blame] | 404 | |
Quddus Chong | 768dba6 | 2012-12-08 17:06:30 -0800 | [diff] [blame] | 405 | <pre> |
Scott Kennedy | 7ed189e | 2013-01-11 22:31:43 -0800 | [diff] [blame] | 406 | PendingIntent pendingIntent = buyIntentBundle.getParcelable("BUY_INTENT"); |
Quddus Chong | 768dba6 | 2012-12-08 17:06:30 -0800 | [diff] [blame] | 407 | </pre> |
Andrew Solovay | 7e86ae8 | 2015-10-01 14:04:25 -0700 | [diff] [blame] | 408 | |
Quddus Chong | 768dba6 | 2012-12-08 17:06:30 -0800 | [diff] [blame] | 409 | <p> |
Andrew Solovay | 7e86ae8 | 2015-10-01 14:04:25 -0700 | [diff] [blame] | 410 | To complete the purchase transaction, call the {@link |
| 411 | android.app.Activity#startIntentSenderForResult startIntentSenderForResult} |
George French | 9748d76 | 2016-09-07 09:59:32 -0700 | [diff] [blame] | 412 | method and use the {@link android.app.PendingIntent} that you created. This |
| 413 | example uses an arbitrary value of 1001 for the request code: |
Andrew Solovay | 7e86ae8 | 2015-10-01 14:04:25 -0700 | [diff] [blame] | 414 | </p> |
| 415 | |
Quddus Chong | 768dba6 | 2012-12-08 17:06:30 -0800 | [diff] [blame] | 416 | <pre> |
| 417 | startIntentSenderForResult(pendingIntent.getIntentSender(), |
| 418 | 1001, new Intent(), Integer.valueOf(0), Integer.valueOf(0), |
| 419 | Integer.valueOf(0)); |
| 420 | </pre> |
Scott Main | 50e990c | 2012-06-21 17:14:39 -0700 | [diff] [blame] | 421 | |
Andrew Solovay | 7e86ae8 | 2015-10-01 14:04:25 -0700 | [diff] [blame] | 422 | <p> |
| 423 | Google Play sends a response to your {@link android.app.PendingIntent} to the |
| 424 | {@link android.app.Activity#onActivityResult onActivityResult} method of your |
| 425 | application. The {@link android.app.Activity#onActivityResult |
George French | 9748d76 | 2016-09-07 09:59:32 -0700 | [diff] [blame] | 426 | onActivityResult} method has a result code of {@code |
| 427 | Activity.RESULT_OK} (1) or {@code Activity.RESULT_CANCELED} (0). To view the |
| 428 | types of order information that are returned in the response {@link |
Andrew Solovay | 7e86ae8 | 2015-10-01 14:04:25 -0700 | [diff] [blame] | 429 | android.content.Intent}, see <a href= |
| 430 | "{@docRoot}google/play/billing/billing_reference.html#getBuyIntent">In-app |
| 431 | Billing Reference</a>. |
| 432 | </p> |
| 433 | |
| 434 | <p> |
| 435 | The purchase data for the order is a String in JSON format that is mapped to |
| 436 | the {@code INAPP_PURCHASE_DATA} key in the response {@link |
George French | 9748d76 | 2016-09-07 09:59:32 -0700 | [diff] [blame] | 437 | android.content.Intent}. Here is an example: |
Andrew Solovay | 7e86ae8 | 2015-10-01 14:04:25 -0700 | [diff] [blame] | 438 | </p> |
| 439 | |
Quddus Chong | 768dba6 | 2012-12-08 17:06:30 -0800 | [diff] [blame] | 440 | <pre> |
Quddus Chong | a0c887c | 2015-04-07 11:37:34 -0700 | [diff] [blame] | 441 | '{ |
Dirk Dougherty | 3c05930 | 2015-09-03 15:24:36 -0700 | [diff] [blame] | 442 | "orderId":"GPA.1234-5678-9012-34567", |
Quddus Chong | 768dba6 | 2012-12-08 17:06:30 -0800 | [diff] [blame] | 443 | "packageName":"com.example.app", |
| 444 | "productId":"exampleSku", |
| 445 | "purchaseTime":1345678900000, |
| 446 | "purchaseState":0, |
| 447 | "developerPayload":"bGoa+V7g/yqDXvKRqq+JTFn4uQZbPiQJo4pf9RzJ", |
Andrew Solovay | c860242 | 2015-02-06 17:29:24 -0800 | [diff] [blame] | 448 | "purchaseToken":<em>"opaque-token-up-to-1000-characters"</em> |
Quddus Chong | 768dba6 | 2012-12-08 17:06:30 -0800 | [diff] [blame] | 449 | }' |
| 450 | </pre> |
Andrew Solovay | 7e86ae8 | 2015-10-01 14:04:25 -0700 | [diff] [blame] | 451 | |
| 452 | <p class="note"> |
| 453 | <strong>Note:</strong> Google Play generates a token for the purchase. This |
| 454 | token is an opaque character sequence that may be up to 1,000 characters |
| 455 | long. Pass this entire token to other methods, such as when you consume the |
| 456 | purchase, as described in <a href= |
| 457 | "{@docRoot}training/in-app-billing/purchase-iab-products.html#Consume">Consume |
George French | 9748d76 | 2016-09-07 09:59:32 -0700 | [diff] [blame] | 458 | a Purchase</a>. Don't abbreviate or truncate this token; you must save and |
Andrew Solovay | 7e86ae8 | 2015-10-01 14:04:25 -0700 | [diff] [blame] | 459 | return the entire token. |
Quddus Chong | 768dba6 | 2012-12-08 17:06:30 -0800 | [diff] [blame] | 460 | </p> |
Scott Main | 50e990c | 2012-06-21 17:14:39 -0700 | [diff] [blame] | 461 | |
Andrew Solovay | 7e86ae8 | 2015-10-01 14:04:25 -0700 | [diff] [blame] | 462 | <p> |
George French | 9748d76 | 2016-09-07 09:59:32 -0700 | [diff] [blame] | 463 | Continuing from the previous example, you receive the response code, purchase |
| 464 | data, and signature from the response {@link android.content.Intent}: |
Andrew Solovay | 7e86ae8 | 2015-10-01 14:04:25 -0700 | [diff] [blame] | 465 | </p> |
Andrew Solovay | c860242 | 2015-02-06 17:29:24 -0800 | [diff] [blame] | 466 | |
Quddus Chong | 768dba6 | 2012-12-08 17:06:30 -0800 | [diff] [blame] | 467 | <pre> |
| 468 | @Override |
Quddus Chong | a0c887c | 2015-04-07 11:37:34 -0700 | [diff] [blame] | 469 | protected void onActivityResult(int requestCode, int resultCode, Intent data) { |
| 470 | if (requestCode == 1001) { |
Quddus Chong | 768dba6 | 2012-12-08 17:06:30 -0800 | [diff] [blame] | 471 | int responseCode = data.getIntExtra("RESPONSE_CODE", 0); |
Scott Kennedy | 7ed189e | 2013-01-11 22:31:43 -0800 | [diff] [blame] | 472 | String purchaseData = data.getStringExtra("INAPP_PURCHASE_DATA"); |
| 473 | String dataSignature = data.getStringExtra("INAPP_DATA_SIGNATURE"); |
Quddus Chong | a0c887c | 2015-04-07 11:37:34 -0700 | [diff] [blame] | 474 | |
Quddus Chong | 768dba6 | 2012-12-08 17:06:30 -0800 | [diff] [blame] | 475 | if (resultCode == RESULT_OK) { |
| 476 | try { |
| 477 | JSONObject jo = new JSONObject(purchaseData); |
| 478 | String sku = jo.getString("productId"); |
Quddus Chong | a0c887c | 2015-04-07 11:37:34 -0700 | [diff] [blame] | 479 | alert("You have bought the " + sku + ". Excellent choice, |
Quddus Chong | 768dba6 | 2012-12-08 17:06:30 -0800 | [diff] [blame] | 480 | adventurer!"); |
| 481 | } |
| 482 | catch (JSONException e) { |
| 483 | alert("Failed to parse purchase data."); |
| 484 | e.printStackTrace(); |
| 485 | } |
| 486 | } |
| 487 | } |
| 488 | } |
| 489 | </pre> |
Andrew Solovay | 7e86ae8 | 2015-10-01 14:04:25 -0700 | [diff] [blame] | 490 | |
| 491 | <p class="note"> |
| 492 | <strong>Security Recommendation:</strong> When you send a purchase request, |
| 493 | create a String token that uniquely identifies this purchase request and |
George French | 9748d76 | 2016-09-07 09:59:32 -0700 | [diff] [blame] | 494 | include this token in the {@code developerPayload}. You can use a randomly-generated |
| 495 | string as the token. When you receive the purchase response from |
| 496 | Google Play, ensure that you check the returned data signature, the {@code |
Andrew Solovay | 7e86ae8 | 2015-10-01 14:04:25 -0700 | [diff] [blame] | 497 | orderId}, and the {@code developerPayload} String. For added security, you |
George French | 9748d76 | 2016-09-07 09:59:32 -0700 | [diff] [blame] | 498 | should perform the checking on your own secure server. Verify |
Andrew Solovay | 7e86ae8 | 2015-10-01 14:04:25 -0700 | [diff] [blame] | 499 | that the {@code orderId} is a unique value that you have not previously |
George French | 9748d76 | 2016-09-07 09:59:32 -0700 | [diff] [blame] | 500 | processed and that the {@code developerPayload} String matches the token that you |
Andrew Solovay | 7e86ae8 | 2015-10-01 14:04:25 -0700 | [diff] [blame] | 501 | sent previously with the purchase request. |
| 502 | </p> |
Scott Main | 50e990c | 2012-06-21 17:14:39 -0700 | [diff] [blame] | 503 | |
George French | 9748d76 | 2016-09-07 09:59:32 -0700 | [diff] [blame] | 504 | <h3 id="QueryPurchases">Querying for purchased items</h3> |
Andrew Solovay | 7e86ae8 | 2015-10-01 14:04:25 -0700 | [diff] [blame] | 505 | |
| 506 | <p> |
George French | 9748d76 | 2016-09-07 09:59:32 -0700 | [diff] [blame] | 507 | To retrieve information about purchases that are made by a user from your app, call |
Andrew Solovay | 7e86ae8 | 2015-10-01 14:04:25 -0700 | [diff] [blame] | 508 | the {@code getPurchases} method on the In-app Billing Version 3 service. Pass |
George French | 9748d76 | 2016-09-07 09:59:32 -0700 | [diff] [blame] | 509 | the In-app Billing API version (“3”), the package name of |
| 510 | your calling app, and the purchase type (“inapp” or "subs") into the method. Here is an example: |
Andrew Solovay | 7e86ae8 | 2015-10-01 14:04:25 -0700 | [diff] [blame] | 511 | </p> |
| 512 | |
Quddus Chong | 768dba6 | 2012-12-08 17:06:30 -0800 | [diff] [blame] | 513 | <pre> |
Scott Kennedy | 7ed189e | 2013-01-11 22:31:43 -0800 | [diff] [blame] | 514 | Bundle ownedItems = mService.getPurchases(3, getPackageName(), "inapp", null); |
Quddus Chong | 768dba6 | 2012-12-08 17:06:30 -0800 | [diff] [blame] | 515 | </pre> |
Andrew Solovay | 7e86ae8 | 2015-10-01 14:04:25 -0700 | [diff] [blame] | 516 | |
| 517 | <p> |
| 518 | The Google Play service returns only the purchases made by the user account |
| 519 | that is currently logged in to the device. If the request is successful, the |
| 520 | returned {@link android.os.Bundle} has a response code of 0. The response |
| 521 | {@link android.os.Bundle} also contains a list of the product IDs, a list of |
| 522 | the order details for each purchase, and the signatures for each purchase. |
| 523 | </p> |
| 524 | |
| 525 | <p> |
| 526 | To improve performance, the In-app Billing service returns only up to 700 |
| 527 | products that are owned by the user when {@code getPurchase} is first called. |
| 528 | If the user owns a large number of products, Google Play includes a String |
George French | 9748d76 | 2016-09-07 09:59:32 -0700 | [diff] [blame] | 529 | token that is mapped to the key {@code INAPP_CONTINUATION_TOKEN} in the response |
Andrew Solovay | 7e86ae8 | 2015-10-01 14:04:25 -0700 | [diff] [blame] | 530 | {@link android.os.Bundle} to indicate that more products can be retrieved. |
George French | 9748d76 | 2016-09-07 09:59:32 -0700 | [diff] [blame] | 531 | Your application can then make a subsequent {@code getPurchases} call and |
Andrew Solovay | 7e86ae8 | 2015-10-01 14:04:25 -0700 | [diff] [blame] | 532 | pass in this token as an argument. Google Play continues to return a |
| 533 | continuation token in the response {@link android.os.Bundle} until all |
George French | 9748d76 | 2016-09-07 09:59:32 -0700 | [diff] [blame] | 534 | of the products that are owned by the user are sent to your app. |
Andrew Solovay | 7e86ae8 | 2015-10-01 14:04:25 -0700 | [diff] [blame] | 535 | </p> |
| 536 | |
George French | 9748d76 | 2016-09-07 09:59:32 -0700 | [diff] [blame] | 537 | <p>For more information about the data that is returned by {@code getPurchases}, see |
Andrew Solovay | 8e34a80 | 2015-11-05 14:10:29 -0800 | [diff] [blame] | 538 | <a href="{@docRoot}google/play/billing/billing_reference.html#getPurchases"> |
| 539 | In-app Billing Reference</a>. The following example shows how you can |
George French | 9748d76 | 2016-09-07 09:59:32 -0700 | [diff] [blame] | 540 | retrieve this data from the response: |
Andrew Solovay | 8e34a80 | 2015-11-05 14:10:29 -0800 | [diff] [blame] | 541 | </p> |
Andrew Solovay | 7e86ae8 | 2015-10-01 14:04:25 -0700 | [diff] [blame] | 542 | |
Quddus Chong | 768dba6 | 2012-12-08 17:06:30 -0800 | [diff] [blame] | 543 | <pre> |
| 544 | int response = ownedItems.getInt("RESPONSE_CODE"); |
| 545 | if (response == 0) { |
quddusc | 896e974 | 2014-01-06 11:36:07 -0800 | [diff] [blame] | 546 | ArrayList<String> ownedSkus = |
Quddus Chong | 768dba6 | 2012-12-08 17:06:30 -0800 | [diff] [blame] | 547 | ownedItems.getStringArrayList("INAPP_PURCHASE_ITEM_LIST"); |
quddusc | 896e974 | 2014-01-06 11:36:07 -0800 | [diff] [blame] | 548 | ArrayList<String> purchaseDataList = |
Quddus Chong | 768dba6 | 2012-12-08 17:06:30 -0800 | [diff] [blame] | 549 | ownedItems.getStringArrayList("INAPP_PURCHASE_DATA_LIST"); |
quddusc | 896e974 | 2014-01-06 11:36:07 -0800 | [diff] [blame] | 550 | ArrayList<String> signatureList = |
Quddus Chong | a0c887c | 2015-04-07 11:37:34 -0700 | [diff] [blame] | 551 | ownedItems.getStringArrayList("INAPP_DATA_SIGNATURE_LIST"); |
| 552 | String continuationToken = |
Quddus Chong | 768dba6 | 2012-12-08 17:06:30 -0800 | [diff] [blame] | 553 | ownedItems.getString("INAPP_CONTINUATION_TOKEN"); |
Quddus Chong | a0c887c | 2015-04-07 11:37:34 -0700 | [diff] [blame] | 554 | |
Andrew Solovay | 7e86ae8 | 2015-10-01 14:04:25 -0700 | [diff] [blame] | 555 | for (int i = 0; i < purchaseDataList.size(); ++i) { |
Quddus Chong | 768dba6 | 2012-12-08 17:06:30 -0800 | [diff] [blame] | 556 | String purchaseData = purchaseDataList.get(i); |
| 557 | String signature = signatureList.get(i); |
| 558 | String sku = ownedSkus.get(i); |
Quddus Chong | a0c887c | 2015-04-07 11:37:34 -0700 | [diff] [blame] | 559 | |
Quddus Chong | 768dba6 | 2012-12-08 17:06:30 -0800 | [diff] [blame] | 560 | // do something with this purchase information |
| 561 | // e.g. display the updated list of products owned by user |
Quddus Chong | a0c887c | 2015-04-07 11:37:34 -0700 | [diff] [blame] | 562 | } |
Scott Main | 50e990c | 2012-06-21 17:14:39 -0700 | [diff] [blame] | 563 | |
Quddus Chong | a0c887c | 2015-04-07 11:37:34 -0700 | [diff] [blame] | 564 | // if continuationToken != null, call getPurchases again |
Quddus Chong | 768dba6 | 2012-12-08 17:06:30 -0800 | [diff] [blame] | 565 | // and pass in the token to retrieve more items |
| 566 | } |
Quddus Chong | 768dba6 | 2012-12-08 17:06:30 -0800 | [diff] [blame] | 567 | </pre> |
| 568 | |
Andrew Solovay | 7e86ae8 | 2015-10-01 14:04:25 -0700 | [diff] [blame] | 569 | |
George French | 9748d76 | 2016-09-07 09:59:32 -0700 | [diff] [blame] | 570 | <h3 id="Consume">Consuming a purchase</h3> |
Andrew Solovay | 7e86ae8 | 2015-10-01 14:04:25 -0700 | [diff] [blame] | 571 | |
| 572 | <p> |
| 573 | You can use the In-app Billing Version 3 API to track the ownership of |
| 574 | purchased in-app products in Google Play. Once an in-app product is |
George French | 9748d76 | 2016-09-07 09:59:32 -0700 | [diff] [blame] | 575 | purchased, it is considered to be <em>owned</em> and cannot be purchased from Google |
Andrew Solovay | 7e86ae8 | 2015-10-01 14:04:25 -0700 | [diff] [blame] | 576 | Play. You must send a consumption request for the in-app product before |
| 577 | Google Play makes it available for purchase again. |
| 578 | </p> |
| 579 | |
George French | 9748d76 | 2016-09-07 09:59:32 -0700 | [diff] [blame] | 580 | <p class="note"> |
Andrew Solovay | 7e86ae8 | 2015-10-01 14:04:25 -0700 | [diff] [blame] | 581 | <strong>Important</strong>: Managed in-app products are consumable, but |
| 582 | subscriptions are not. |
| 583 | </p> |
| 584 | |
| 585 | <p> |
George French | 9748d76 | 2016-09-07 09:59:32 -0700 | [diff] [blame] | 586 | The way that you use the consumption mechanism in your app is up to you. Typically, |
| 587 | you implement consumption for in-app products with temporary benefits |
Andrew Solovay | 7e86ae8 | 2015-10-01 14:04:25 -0700 | [diff] [blame] | 588 | that users may want to purchase multiple times (for example, in-game currency |
George French | 9748d76 | 2016-09-07 09:59:32 -0700 | [diff] [blame] | 589 | or equipment). You typically don't want to implement consumption for |
Andrew Solovay | 7e86ae8 | 2015-10-01 14:04:25 -0700 | [diff] [blame] | 590 | in-app products that are purchased once and provide a permanent effect (for |
| 591 | example, a premium upgrade). |
| 592 | </p> |
| 593 | |
| 594 | <p> |
| 595 | To record a purchase consumption, send the {@code consumePurchase} method to |
| 596 | the In-app Billing service and pass in the {@code purchaseToken} String value |
| 597 | that identifies the purchase to be removed. The {@code purchaseToken} is part |
George French | 9748d76 | 2016-09-07 09:59:32 -0700 | [diff] [blame] | 598 | of the data that is returned in the {@code INAPP_PURCHASE_DATA} String by the Google |
| 599 | Play service following a successful purchase request. This example |
| 600 | records the consumption of a product that is identified with the {@code |
| 601 | purchaseToken} in the {@code token} variable: |
Andrew Solovay | 7e86ae8 | 2015-10-01 14:04:25 -0700 | [diff] [blame] | 602 | </p> |
| 603 | |
Quddus Chong | 768dba6 | 2012-12-08 17:06:30 -0800 | [diff] [blame] | 604 | <pre> |
| 605 | int response = mService.consumePurchase(3, getPackageName(), token); |
| 606 | </pre> |
Andrew Solovay | 7e86ae8 | 2015-10-01 14:04:25 -0700 | [diff] [blame] | 607 | |
George French | 9748d76 | 2016-09-07 09:59:32 -0700 | [diff] [blame] | 608 | <p class="caution"> |
| 609 | <strong>Warning:</strong> Don't call the {@code consumePurchase} method on |
| 610 | the main thread. Calling this method triggers a network request that could |
Andrew Solovay | 7e86ae8 | 2015-10-01 14:04:25 -0700 | [diff] [blame] | 611 | block your main thread. Instead, create a separate thread and call the {@code |
George French | 9748d76 | 2016-09-07 09:59:32 -0700 | [diff] [blame] | 612 | consumePurchase} method from inside of that thread. |
Andrew Solovay | 7e86ae8 | 2015-10-01 14:04:25 -0700 | [diff] [blame] | 613 | </p> |
| 614 | |
| 615 | <p> |
| 616 | It's your responsibility to control and track how the in-app product is |
| 617 | provisioned to the user. For example, if the user purchased in-game currency, |
| 618 | you should update the player's inventory with the amount of currency |
| 619 | purchased. |
| 620 | </p> |
| 621 | |
George French | 9748d76 | 2016-09-07 09:59:32 -0700 | [diff] [blame] | 622 | <p class="caution"> |
| 623 | <strong>Security Recommendation:</strong> Send a consumption request |
Andrew Solovay | 7e86ae8 | 2015-10-01 14:04:25 -0700 | [diff] [blame] | 624 | before provisioning the benefit of the consumable in-app purchase to the |
George French | 9748d76 | 2016-09-07 09:59:32 -0700 | [diff] [blame] | 625 | user. Ensure that you receive a successful consumption response from |
Andrew Solovay | 7e86ae8 | 2015-10-01 14:04:25 -0700 | [diff] [blame] | 626 | Google Play before you provision the item. |
| 627 | </p> |
Quddus Chong | 768dba6 | 2012-12-08 17:06:30 -0800 | [diff] [blame] | 628 | |
George French | 9748d76 | 2016-09-07 09:59:32 -0700 | [diff] [blame] | 629 | <h3 id="Subs">Implementing subscriptions</h3> |
Andrew Solovay | 7e86ae8 | 2015-10-01 14:04:25 -0700 | [diff] [blame] | 630 | |
Quddus Chong | a0c887c | 2015-04-07 11:37:34 -0700 | [diff] [blame] | 631 | <p>Launching a purchase flow for a subscription is similar to launching the |
| 632 | purchase flow for a product, with the exception that the product type must be set |
| 633 | to "subs". The purchase result is delivered to your Activity's |
| 634 | {@link android.app.Activity#onActivityResult onActivityResult} method, exactly |
George French | 9748d76 | 2016-09-07 09:59:32 -0700 | [diff] [blame] | 635 | as in the case of in-app products. Here is an example:</p> |
Andrew Solovay | 7e86ae8 | 2015-10-01 14:04:25 -0700 | [diff] [blame] | 636 | |
quddusc | 8dcc99d | 2013-02-07 17:16:33 -0800 | [diff] [blame] | 637 | <pre> |
| 638 | Bundle bundle = mService.getBuyIntent(3, "com.example.myapp", |
| 639 | MY_SKU, "subs", developerPayload); |
| 640 | |
| 641 | PendingIntent pendingIntent = bundle.getParcelable(RESPONSE_BUY_INTENT); |
| 642 | if (bundle.getInt(RESPONSE_CODE) == BILLING_RESPONSE_RESULT_OK) { |
| 643 | // Start purchase flow (this brings up the Google Play UI). |
| 644 | // Result will be delivered through onActivityResult(). |
| 645 | startIntentSenderForResult(pendingIntent, RC_BUY, new Intent(), |
| 646 | Integer.valueOf(0), Integer.valueOf(0), Integer.valueOf(0)); |
| 647 | } |
| 648 | </pre> |
Andrew Solovay | 7e86ae8 | 2015-10-01 14:04:25 -0700 | [diff] [blame] | 649 | |
Quddus Chong | a0c887c | 2015-04-07 11:37:34 -0700 | [diff] [blame] | 650 | <p>To query for active subscriptions, use the {@code getPurchases} method, again |
George French | 9748d76 | 2016-09-07 09:59:32 -0700 | [diff] [blame] | 651 | with the product type parameter set to "subs":</p> |
Andrew Solovay | 7e86ae8 | 2015-10-01 14:04:25 -0700 | [diff] [blame] | 652 | |
quddusc | 8dcc99d | 2013-02-07 17:16:33 -0800 | [diff] [blame] | 653 | <pre> |
| 654 | Bundle activeSubs = mService.getPurchases(3, "com.example.myapp", |
| 655 | "subs", continueToken); |
| 656 | </pre> |
Andrew Solovay | 7e86ae8 | 2015-10-01 14:04:25 -0700 | [diff] [blame] | 657 | |
George French | 9748d76 | 2016-09-07 09:59:32 -0700 | [diff] [blame] | 658 | <p>The call returns a {@code Bundle} with all of the active subscriptions that are owned by |
| 659 | the user. When a subscription expires without renewal, it no longer appears |
quddusc | 8dcc99d | 2013-02-07 17:16:33 -0800 | [diff] [blame] | 660 | in the returned {@code Bundle}.</p> |
Quddus Chong | 768dba6 | 2012-12-08 17:06:30 -0800 | [diff] [blame] | 661 | |
George French | 9748d76 | 2016-09-07 09:59:32 -0700 | [diff] [blame] | 662 | <h2 id="billing-security">Securing your application</h2> |
quddusc | ce4027b | 2013-03-29 15:32:38 -0700 | [diff] [blame] | 663 | |
Quddus Chong | a0c887c | 2015-04-07 11:37:34 -0700 | [diff] [blame] | 664 | <p>To help ensure the integrity of the transaction information that is sent to |
| 665 | your application, Google Play signs the JSON string that contains the response |
| 666 | data for a purchase order. Google Play uses the private key that is associated |
| 667 | with your application in the Developer Console to create this signature. The |
quddusc | ce4027b | 2013-03-29 15:32:38 -0700 | [diff] [blame] | 668 | Developer Console generates an RSA key pair for each application.<p> |
| 669 | |
George French | 9748d76 | 2016-09-07 09:59:32 -0700 | [diff] [blame] | 670 | <p class="note"><strong>Note:</strong> To find the public key portion of this key |
| 671 | pair, open your application's details in the Developer Console, click |
| 672 | <strong>Services & APIs</strong>, and review the field titled |
quddusc | ce4027b | 2013-03-29 15:32:38 -0700 | [diff] [blame] | 673 | <strong>Your License Key for This Application</strong>.</p> |
| 674 | |
George French | 9748d76 | 2016-09-07 09:59:32 -0700 | [diff] [blame] | 675 | <p>The Base64-encoded RSA public key that is generated by Google Play is in binary |
Quddus Chong | a0c887c | 2015-04-07 11:37:34 -0700 | [diff] [blame] | 676 | encoded, X.509 subjectPublicKeyInfo DER SEQUENCE format. It is the same public |
quddusc | ce4027b | 2013-03-29 15:32:38 -0700 | [diff] [blame] | 677 | key that is used with Google Play licensing.</p> |
| 678 | |
George French | 9748d76 | 2016-09-07 09:59:32 -0700 | [diff] [blame] | 679 | <p>When your application receives this signed response, you can |
Quddus Chong | a0c887c | 2015-04-07 11:37:34 -0700 | [diff] [blame] | 680 | use the public key portion of your RSA key pair to verify the signature. |
George French | 9748d76 | 2016-09-07 09:59:32 -0700 | [diff] [blame] | 681 | By performing signature verification, you can detect any responses that have |
Quddus Chong | a0c887c | 2015-04-07 11:37:34 -0700 | [diff] [blame] | 682 | been tampered with or that have been spoofed. You can perform this signature |
| 683 | verification step in your application; however, if your application connects |
George French | 9748d76 | 2016-09-07 09:59:32 -0700 | [diff] [blame] | 684 | to a secure remote server, Google recommends that you perform the signature |
quddusc | ce4027b | 2013-03-29 15:32:38 -0700 | [diff] [blame] | 685 | verification on that server.</p> |
| 686 | |
| 687 | <p>For more information about best practices for security and design, see <a |
Andrew Solovay | 8e34a80 | 2015-11-05 14:10:29 -0800 | [diff] [blame] | 688 | href="{@docRoot}google/play/billing/billing_best_practices.html">Security and |
| 689 | Design</a>.</p> |