1 page.title=Preparing Your In-app Billing Application 2 parent.title=Selling In-app Products 3 parent.link=index.html 4 5 trainingnavtop=true 6 next.title=Establishing In-app Billing Products for Sale 7 next.link=list-iab-products.html 8 9 @jd:body 10 11 <!-- This is the training bar --> 12 <div id="tb-wrapper"> 13 <div id="tb"> 14 15 <h2>This lesson teaches you to</h2> 16 <ol> 17 <li><a href="#GetSample">Download the Sample App</a></li> 18 <li><a href="#AddToDevConsole">Add Your App to the Developer Console</a></li> 19 <li><a href="#AddLibrary">Add the In-app Billing Library</a></li> 20 <li><a href="#SetPermission">Set the Billing Permission</a></li> 21 <li><a href="#Connect">Initiate a Connection with Google Play</a></li> 22 </ol> 23 24 <h2>You should also read</h2> 25 <ul> 26 <li><a href="{@docRoot}google/play/billing/billing_overview.html">In-app Billing 27 Overview</a></li> 28 </ul> 29 30 </div> 31 </div> 32 33 <a class="notice-developers-video wide" 34 href="https://www.youtube.com/watch?v=UvCl5Xx7Z5o" class="external-link"> 35 <div> 36 <h3>Video</h3> 37 <p>Implementing Freemium</p> 38 </div> 39 </a> 40 41 <p>Before you can start using the In-app Billing service, you need to add the library that 42 contains the In-app Billing Version 3 API to your Android project. You also need to set the 43 permissions for your application to communicate with Google Play. In addition, you need to 44 establish a connection between your application and Google Play. You must also verify that 45 the In-app Billing API version that you are using in your application is supported 46 by Google Play.</p> 47 48 <h2 id="GetSample">Download the Sample Application</h2> 49 <p>In this training class, you use a reference implementation for the In-app Billing 50 Version 3 API 51 called the {@code TrivialDrive} sample application. The sample includes convenience classes to 52 quickly set up the In-app Billing service, marshal and unmarshal data types, and handle In-app 53 Billing requests from the main thread of your application.</p> 54 <p>To download the sample application, follow these steps:</p> 55 <ol> 56 <li>Open Android Studio and then close any open projects until you are 57 presented with the welcome screen.</li> 58 <li>From the <strong>Quick Start</strong> list on the right side of the window, choose 59 <strong>Import an Android code sample</strong>.</li> 60 <li>Type {@code Trivial Drive} into the search bar and select the 61 <strong>Trivial Drive</strong> sample.</li> 62 <li>Follow the rest of the instructions in the <strong>Import Sample</strong> 63 wizard to import the sample to a directory of your choosing. The sample code 64 is in the <strong>TrivialDrive</strong> subdirectory of the repository.</li> 65 </ol> 66 67 <p>Alternatively, you can use {@code git} to manually clone 68 the repository from the <a 69 href="https://github.com/googlesamples/android-play-billing" 70 class="external-link">Google Samples</a> GitHub site.</p> 71 72 <h2 id="AddToDevConsole">Add Your Application to the Developer Console</h2> 73 <p>The Google Play Developer Console is where you publish your In-app Billing application 74 and manage the various digital products that are available for purchase from your 75 application. 76 When you create a new application entry in the Developer Console, it automatically generates 77 a public license key for your application. You need this key to establish a trusted connection 78 from your application to the Google Play servers. You need to generate this key only once 79 per application, and you dont need to repeat these steps when you update the APK file for 80 your application.</p> 81 <p>To add your application to the Developer Console, follow these steps:</p> 82 <ol> 83 <li>Go to the <a href="http://play.google.com/apps/publish" class="external-link"> 84 Google Play Developer Console</a> 85 site and log in. If you have not registered previously, you need to register for a new 86 developer account. To sell in-app products, you also need a 87 <a href="http://www.google.com/wallet/merchants.html" class="external-link"> 88 Google payments</a> merchant account.</li> 89 90 <li>In the <strong>All Applications</strong> tab, complete these steps to add a new 91 application entry: 92 <ol type="a"> 93 <li>Click <strong>Add new application</strong>.</li> 94 <li>Enter a name for your new In-app Billing application.</li> 95 <li>Click <strong>Prepare Store Listing</strong>.</li> 96 </ol> 97 </li> 98 <li>In the <strong>Services & APIs</strong> tab, find and make a note of the public license key 99 that Google Play generated for your application. This is a Base64 string that you need to 100 include in your application code later.</li> 101 </ol> 102 <p>Your application should now appear in the list of applications in Developer Console.</p> 103 104 <h2 id="AddLibrary">Add the In-app Billing Library</h2> 105 <p>To use the In-app Billing Version 3 features, you must add the 106 {@code IInAppBillingService.aidl} 107 file to your Android project. This Android Interface Definition Language 108 (AIDL) file defines the 109 interface to the Google Play service.</p> 110 <p>You can find the {@code IInAppBillingService.aidl} file in the provided sample app. 111 To add the 112 In-app Billing library to your project, follow the instructions below for a new or 113 existing project.</p> 114 <h3>Adding in-app billing to a new project</h3> 115 <p>To add the In-app Billing Version 3 library to a new project, follow these steps:</p> 116 <ol> 117 <li>Copy the {@code TrivialDrive} sample files into your Android project.</li> 118 <li>Modify the package name in the files that you copied to use the package name 119 for your project. 120 In Android Studio, you can right-click the package name and then 121 select <strong>Refactor</strong> > <strong>Rename</strong>.</li> 122 <li>Open the {@code AndroidManifest.xml} file and update the package attribute value to 123 use the package name for your project.</li> 124 <li>Fix import statements as needed so that your project compiles correctly. 125 In Android Studio, you can press <strong>Ctrl+Shift+O</strong> 126 in each file showing errors.</li> 127 <li>Modify the sample to create your own application. Remember to copy the Base64 128 public license key for your application from the Developer Console to 129 your {@code MainActivity.java}.</li> 130 </ol> 131 132 <h3>Adding in-app billing to an existing project</h3> 133 <p>To add the In-app Billing Version 3 library to an existing project, follow these steps:</p> 134 <ol> 135 <li>Copy the {@code IInAppBillingService.aidl} file to your Android project. 136 <ul> 137 <li>In Android Studio: Create a directory named {@code aidl} under {@code src/main}, 138 add a new 139 package {@code com.android.vending.billing} in this directory, and then import the 140 {@code IInAppBillingService.aidl} file into this package.</li> 141 <li>In other dev environments: Create the following directory 142 {@code /src/com/android/vending/billing} and copy the {@code IInAppBillingService.aidl} 143 file into this directory.</li> 144 </ul> 145 </li> 146 <li>Build your application. You should see a generated file named 147 {@code IInAppBillingService.java} 148 in the {@code /gen} directory of your project.</li> 149 <li>Add the helper classes from the {@code /util} directory of the {@code TrivialDrive} 150 sample to 151 your project. Remember to change the package name declarations in those files 152 accordingly so 153 that your project compiles correctly.</li> 154 </ol> 155 <p>Your project should now contain the In-app Billing Version 3 library.</p> 156 157 <h2 id="SetPermission">Set the Billing Permission</h2> 158 <p>Your app needs to have permission to communicate request and response messages to 159 the Google Play billing service. To give your app the necessary permission, add the following 160 line in your {@code AndroidManifest.xml} manifest file:</p> 161 <pre> 162 <uses-permission android:name="com.android.vending.BILLING" /> 163 </pre> 164 165 <h2 id="Connect">Initiate a Connection with Google Play</h2> 166 <p>To send In-app 167 Billing requests to Google Play from your application, you must bind your Activity 168 to the Google Play In-app Billing service. The sample includes convenience classes 169 that handle the binding to the In-app Billing service, so you dont have to 170 manage the network connection directly.</p> 171 <p>To set up synchronous communication with Google Play, create an {@code IabHelper} 172 instance in your activity's {@code onCreate} method, as shown in the following example. 173 In the constructor, pass in the {@code Context} for the activity along with a string 174 containing the public license key that was generated earlier by the Google Play 175 Developer Console. 176 </p> 177 <p class="caution"><strong>Security Recommendation:</strong> Google highly recommends that 178 you do not hard-code the exact public license key string value as provided by Google Play. 179 Instead, construct the whole public license key string at runtime from substrings 180 or retrieve it from an encrypted store before passing it to the constructor. 181 This approach makes it more difficult for malicious third parties to modify the public 182 license key string in your APK file.</p> 183 184 <pre> 185 IabHelper mHelper; 186 187 @Override 188 public void onCreate(Bundle savedInstanceState) { 189 // ... 190 String base64EncodedPublicKey; 191 192 // compute your public key and store it in base64EncodedPublicKey 193 mHelper = new IabHelper(this, base64EncodedPublicKey); 194 } 195 </pre> 196 197 <p>Next, perform the service binding by calling the {@code startSetup} method on the 198 {@code IabHelper} instance that you created, as shown in the following example. 199 Pass the method an {@code OnIabSetupFinishedListener} instance, which is called once 200 the {@code IabHelper} completes the asynchronous setup operation. As part of the 201 setup process, the {@code IabHelper} also checks if the In-app Billing Version 3 API 202 is supported by Google Play. If the API version is not supported, or if an error occurs 203 while establishing the service binding, the listener is notified and passed an 204 {@code IabResult} object with the error message.</p> 205 206 <pre> 207 mHelper.startSetup(new IabHelper.OnIabSetupFinishedListener() { 208 public void onIabSetupFinished(IabResult result) { 209 if (!result.isSuccess()) { 210 // Oh no, there was a problem. 211 Log.d(TAG, "Problem setting up In-app Billing: " + result); 212 } 213 // Hooray, IAB is fully set up! 214 } 215 }); 216 </pre> 217 218 <p>If the setup completed successfully, you can now use the {@code mHelper} reference 219 to communicate with the Google Play service. When your application is launched, it is 220 a good practice to query Google Play to find out what in-app items are owned by a user. 221 This is covered further in the 222 <a href="{@docRoot}training/in-app-billing/purchase-iab-products.html#QueryPurchases"> 223 Query Purchased Items</a> section.</p> 224 225 <p class="caution"><strong>Important:</strong> Remember to unbind from the In-app Billing service 226 when you are done with your activity. If you dont unbind, the open service connection could 227 degrade device performance. To unbind and free your system resources, call the 228 {@code IabHelper}'s {@code dispose} method when your {@code Activity} is destroyed, 229 as shown in the following example.</p> 230 231 <pre> 232 @Override 233 public void onDestroy() { 234 super.onDestroy(); 235 if (mHelper != null) mHelper.dispose(); 236 mHelper = null; 237 } 238 </pre> 239
