docs/html/training/in-app-billing/preparing-iab-app.jd

page.title=Preparing Your In-app Billing Application
parent.title=Selling In-app Products
parent.link=index.html

trainingnavtop=true
next.title=Establishing In-app Billing Products for Sale
next.link=list-iab-products.html

@jd:body

<!-- This is the training bar -->
<div id="tb-wrapper">
<div id="tb">

<h2>This lesson teaches you to</h2>
<ol>
  <li><a href="#GetSample">Download the Sample App</a></li>
  <li><a href="#AddToDevConsole">Add Your App to the Developer Console</a></li>
  <li><a href="#AddLibrary">Add the In-app Billing Library</a></li>
  <li><a href="#SetPermission">Set the Billing Permission</a></li>
  <li><a href="#Connect">Initiate a Connection with Google Play</a></li>
</ol>

<h2>You should also read</h2>
<ul>
<li><a href="{@docRoot}google/play/billing/billing_overview.html">In-app Billing
    Overview</a></li>
</ul>

</div>
</div>

<a class="notice-developers-video wide"
href="https://www.youtube.com/watch?v=UvCl5Xx7Z5o" class="external-link">
<div>
    <h3>Video</h3>
    <p>Implementing Freemium</p>
  </div>
  </a>

<p>Before you can start using the In-app Billing service, you need to add the library that
 contains the In-app Billing Version 3 API to your Android project. You also need to set the
 permissions for your application to communicate with Google Play. In addition, you need to
 establish a connection between your application and  Google Play. You must also verify that
 the In-app Billing API version that you are using in your application is supported
 by Google Play.</p>

<h2 id="GetSample">Download the Sample Application</h2>
<p>In this training class, you use a reference implementation for the In-app Billing
 Version 3 API
 called the {@code TrivialDrive} sample application. The sample includes convenience classes to
 quickly set up the In-app Billing service, marshal and unmarshal data types, and handle In-app
 Billing requests from the main thread of your application.</p>
<p>To download the sample application, follow these steps:</p>
<ol>
<li>Open Android Studio and then close any open projects until you are
presented with the welcome screen.</li>
<li>From the <strong>Quick Start</strong> list on the right side of the window, choose
 <strong>Import an Android code sample</strong>.</li>
<li>Type {@code Trivial Drive} into the search bar and select the
  <strong>Trivial Drive</strong> sample.</li>
<li>Follow the rest of the instructions in the <strong>Import Sample</strong>
  wizard to import the sample to a directory of your choosing. The sample code
  is in the <strong>TrivialDrive</strong> subdirectory of the repository.</li>
</ol>

<p>Alternatively, you can use {@code git} to manually clone
 the repository from the <a
 href="https://github.com/googlesamples/android-play-billing"
 class="external-link">Google Samples</a> GitHub site.</p>

<h2 id="AddToDevConsole">Add Your Application to the Developer Console</h2>
<p>The Google Play Developer Console is where you publish your In-app Billing application
 and  manage the various digital products that are available for purchase from your
 application.
 When you create a new application entry in the Developer Console, it automatically generates
 a public license key for your application. You need this key to establish a trusted connection
 from your application to the Google Play servers. You need to generate this key only once
 per application, and you don’t need to repeat these steps when you update the APK file for
 your application.</p>
<p>To add your application to the Developer Console, follow these steps:</p>
<ol>
<li>Go to the <a href="http://play.google.com/apps/publish" class="external-link">
Google Play Developer Console</a>
 site and log in. If you have not registered previously, you need to register for a new
 developer account. To sell in-app products, you also need a
 <a href="http://www.google.com/wallet/merchants.html" class="external-link">
 Google payments</a> merchant account.</li>

<li>In the <strong>All Applications</strong> tab, complete these steps to add a new
 application entry:
<ol type="a">
<li>Click <strong>Add new application</strong>.</li>
<li>Enter a name for your new In-app Billing application.</li>
<li>Click <strong>Prepare Store Listing</strong>.</li>
</ol>
</li>
<li>In the <strong>Services & APIs</strong> tab, find and make a note of the public license key
 that Google Play generated for your application. This is a Base64 string that you need to
 include in your application code later.</li>
</ol>
<p>Your application should now appear in the list of applications in Developer Console.</p>

<h2 id="AddLibrary">Add the In-app Billing Library</h2>
<p>To use the In-app Billing Version 3 features, you must add the
 {@code IInAppBillingService.aidl}
 file to your Android project. This Android Interface Definition Language
 (AIDL) file defines the
 interface to the Google Play service.</p>
<p>You can find the {@code IInAppBillingService.aidl} file in the provided sample app.
 To add the
 In-app Billing library to your project, follow the instructions below for a new or
 existing project.</p>
<h3>Adding in-app billing to a new project</h3>
<p>To add the In-app Billing Version 3 library to a new project, follow these steps:</p>
<ol>
<li>Copy the {@code TrivialDrive} sample files into your Android project.</li>
<li>Modify the package name in the files that you copied to use the package name
 for your project.
 In Android Studio, you can right-click the package name and then
 select <strong>Refactor</strong> > <strong>Rename</strong>.</li>
<li>Open the {@code AndroidManifest.xml} file and update the package attribute value to
 use the package name for your project.</li>
<li>Fix import statements as needed so that your project compiles correctly.
 In Android Studio, you can press <strong>Ctrl+Shift+O</strong>
 in each file showing errors.</li>
<li>Modify the sample to create your own application. Remember to copy the Base64
 public license key for your application from the Developer Console to
 your {@code MainActivity.java}.</li>
</ol>

<h3>Adding in-app billing to an existing project</h3>
<p>To add the In-app Billing Version 3 library to an existing project, follow these steps:</p>
<ol>
<li>Copy the {@code IInAppBillingService.aidl} file to your Android project.
  <ul>
  <li>In Android Studio: Create a directory named {@code aidl} under {@code src/main},
  add a new
  package {@code com.android.vending.billing} in this directory, and then import the
  {@code IInAppBillingService.aidl} file into this package.</li>
  <li>In other dev environments: Create the following directory
  {@code /src/com/android/vending/billing} and copy the {@code IInAppBillingService.aidl}
  file into this directory.</li>
  </ul>
</li>
<li>Build your application. You should see a generated file named
 {@code IInAppBillingService.java}
 in the {@code /gen} directory of your project.</li>
<li>Add the helper classes from the {@code /util} directory of the {@code TrivialDrive}
 sample to
 your project.  Remember to change the package name declarations in those files
 accordingly so
 that your project compiles correctly.</li>
</ol>
<p>Your project should now contain the In-app Billing Version 3 library.</p>

<h2 id="SetPermission">Set the Billing Permission</h2>
<p>Your app needs to have permission to communicate request and response messages to
 the Google Play billing service. To give your app the necessary permission, add the following
 line in your {@code AndroidManifest.xml} manifest file:</p>
<pre>
&lt;uses-permission android:name="com.android.vending.BILLING" /&gt;
</pre>

<h2 id="Connect">Initiate a Connection with Google Play</h2>
<p>To send In-app
 Billing requests to Google Play from your application, you must bind your Activity
 to the Google Play In-app Billing service. The sample includes convenience classes
 that handle the binding to the In-app Billing service, so you don’t have to
 manage the network connection directly.</p>
<p>To set up synchronous communication with Google Play, create an {@code IabHelper}
 instance in your activity's {@code onCreate} method, as shown in the following example.
 In the constructor, pass in the {@code Context} for the activity along with a string
 containing the public license key that was generated earlier by the Google Play
 Developer Console.
</p>
<p class="caution"><strong>Security Recommendation:</strong> Google highly recommends that
 you do not hard-code the exact public license key string value as provided by Google Play.
 Instead, construct the whole public license key string at runtime from substrings
 or retrieve it from an encrypted store before passing it to the constructor.
 This approach makes it more difficult for malicious third parties to modify the public
 license key string in your APK file.</p>

<pre>
IabHelper mHelper;

&#64;Override
public void onCreate(Bundle savedInstanceState) {
   // ...
   String base64EncodedPublicKey;

   // compute your public key and store it in base64EncodedPublicKey
   mHelper = new IabHelper(this, base64EncodedPublicKey);
}
</pre>

<p>Next, perform the service binding by calling the {@code startSetup} method on the
 {@code IabHelper} instance that you created, as shown in the following example.
 Pass the method an {@code OnIabSetupFinishedListener} instance, which is called once
 the {@code IabHelper} completes the asynchronous setup operation. As part of the
 setup process, the {@code IabHelper} also checks if the In-app Billing Version 3 API
 is supported by Google Play. If the API version is not supported, or if an error occurs
 while establishing the service binding, the listener is notified and passed an
 {@code IabResult} object with the error message.</p>

<pre>
mHelper.startSetup(new IabHelper.OnIabSetupFinishedListener() {
   public void onIabSetupFinished(IabResult result) {
      if (!result.isSuccess()) {
         // Oh no, there was a problem.
         Log.d(TAG, "Problem setting up In-app Billing: " + result);
      }
         // Hooray, IAB is fully set up!
   }
});
</pre>

<p>If the setup completed successfully, you can now use the {@code mHelper} reference
 to communicate with the Google Play service. When your application is launched, it is
 a good practice to query Google Play to find out what in-app items are owned by a user.
 This is covered further in the
 <a href="{@docRoot}training/in-app-billing/purchase-iab-products.html#QueryPurchases">
 Query Purchased Items</a> section.</p>

<p class="caution"><strong>Important:</strong> Remember to unbind from the In-app Billing service
 when you are done with your activity. If you don’t unbind, the open service connection could
 degrade device performance. To unbind and free your system resources, call the
 {@code IabHelper}'s {@code dispose} method when your {@code Activity} is destroyed,
 as shown in the following example.</p>

<pre>
&#64;Override
public void onDestroy() {
   super.onDestroy();
   if (mHelper != null) mHelper.dispose();
   mHelper = null;
}
</pre>