cherrypick Change-Id: Ica1b68a1687917432d39d7d116c9c24fa1644a83
Initial posting of in-app billing docs
Change-Id: I26adb5480e556d8f914a3443f1b75c220742245d
diff --git a/docs/html/guide/guide_toc.cs b/docs/html/guide/guide_toc.cs
index 416b431a..8b8dc86 100644
--- a/docs/html/guide/guide_toc.cs
+++ b/docs/html/guide/guide_toc.cs
@@ -297,6 +297,50 @@
</li>
<li>
+ <h2>
+ <span class="en">Android Market Topics</span>
+ </h2>
+ <ul>
+ <li><a href="<?cs var:toroot ?>guide/publishing/licensing.html">
+ <span class="en">Application Licensing</span></a>
+ </li>
+ <li class="toggle-list">
+ <div><a href="<?cs var:toroot?>guide/market/billing/index.html">
+ <span class="en">In-app Billing</span></a>
+ <span class="new">new!</span>
+ </div>
+ <ul>
+ <li><a href="<?cs var:toroot?>guide/market/billing/billing_about.html">
+ <span class="en">About this Release</span></a>
+ </li>
+ <li><a href="<?cs var:toroot?>guide/market/billing/billing_overview.html">
+ <span class="en">In-app Billing Overview</span></a>
+ </li>
+ <li><a href="<?cs var:toroot?>guide/market/billing/billing_integrate.html">
+ <span class="en">Implementing In-app Billing</span></a>
+ </li>
+ <li><a href="<?cs var:toroot?>guide/market/billing/billing_best_practices.html">
+ <span class="en">Security and Design</span></a>
+ </li>
+ <li><a href="<?cs var:toroot?>guide/market/billing/billing_testing.html">
+ <span class="en">Testing In-app Billing</span></a>
+ </li>
+ <li><a href="<?cs var:toroot?>guide/market/billing/billing_admin.html">
+ <span class="en">Administering In-app Billing</span></a>
+ </li>
+ <li><a href="<?cs var:toroot?>guide/market/billing/billing_reference.html">
+ <span class="en">In-app Billing Reference</span></a>
+ </li>
+ </ul>
+ </li>
+ <li><a href="<?cs var:toroot ?>guide/appendix/market-filters.html">
+ <span class="en">Market Filters</span></a>
+ </li>
+ </ul>
+ </li>
+
+
+ <li>
<h2><span class="en">Developing</span>
<span class="de" style="display:none">Entwicklung</span>
<span class="es" style="display:none">Desarrollo</span>
@@ -443,9 +487,6 @@
<span class="zh-CN" style="display:none">应用程序版本控制</span>
<span class="zh-TW" style="display:none">應用程式版本設定</span>
</a></li>
- <li><a href="<?cs var:toroot ?>guide/publishing/licensing.html">
- <span class="en">Licensing Your Applications</span>
- </a></li>
<li><a href="<?cs var:toroot ?>guide/publishing/preparing.html">
<span class="en">Preparing to Publish</span>
<span class="de" style="display:none">Vorbereitung auf die Veröffentlichung</span>
@@ -570,9 +611,6 @@
<li><a href="<?cs var:toroot ?>guide/appendix/api-levels.html">
<span class="en">Android API Levels</span>
</a></li>
- <li><a href="<?cs var:toroot ?>guide/appendix/market-filters.html">
- <span class="en">Market Filters</span>
- </a></li>
<li><a href="<?cs var:toroot ?>guide/appendix/install-location.html">
<span class="en">App Install Location</span>
</a></li>
diff --git a/docs/html/guide/market/billing/billing_about.jd b/docs/html/guide/market/billing/billing_about.jd
new file mode 100755
index 0000000..9c027ca
--- /dev/null
+++ b/docs/html/guide/market/billing/billing_about.jd
@@ -0,0 +1,73 @@
+page.title=About this Release
+@jd:body
+
+<style type="text/css">
+ #jd-content {
+ background:transparent url({@docRoot}assets/images/preliminary.png) repeat scroll 0 0;
+ }
+</style>
+
+<div id="qv-wrapper">
+<div id="qv">
+ <h2>In this document</h2>
+ <ol>
+ <li><a href="#billing-about">About this Release</a></li>
+ </ol>
+ <h2>Downloads</h2>
+ <ol>
+ <li><a href="{@docRoot}guide/market/billing/billing_integrate.html#billing-download">Sample Application</a></li>
+ </ol>
+ <h2>See also</h2>
+ <ol>
+ <li><a href="{@docRoot}guide/market/billing/billing_overview.html">Overview of In-app Billing</a></li>
+ <li><a href="{@docRoot}guide/market/billing/billing_integrate.html">Implementing In-app Billing</a></li>
+ <li><a href="{@docRoot}guide/market/billing/billing_best_practices.html">Security and Design</a></li>
+ <li><a href="{@docRoot}guide/market/billing/billing_testing.html">Testing In-app Billing</a></li>
+ <li><a href="{@docRoot}guide/market/billing/billing_admin.html">Administering In-app Billing</a></li>
+ <li><a href="{@docRoot}guide/market/billing/billing_reference.html">In-app Billing Reference</a></li>
+ </ol>
+</div>
+</div>
+
+<div class="special" style="margin-right:345px">
+ <p>This documentation provides an early look at the Android Market In-app Billing service. The documentation may change without notice.</p>
+</div>
+
+<p>This documentation gives you an early look at the Android Market In-app Billing service. We are providing this documentation to help you get started designing your in-app billing implementation. </p>
+
+<p>In addition to this documentation, we are providing a <a href="{@docRoot}guide/market/billing/billing_integrate.html#billing-download">sample application</a> that shows you how to implement in-app billing. Although you can compile the sample application, load it on a device, and run it, you cannot use it to make purchases at this time. In-app billing relies on version 2.3.0 (and higher) of the Android Market application, which may not be available yet.</p>
+
+<p>In the coming weeks we plan to launch the testing phase of the in-app billing release. Following the testing phase we will launch in-app billing to the general public (see table 1 for a summary of upcoming launch milestones).
+
+<p class="table-caption"><strong>Table 1.</strong> Summary of launch milestones for in-app billing.</p>
+
+<table>
+
+<tr>
+<th>Release Phase</th>
+<th>Android Market Application</th>
+<th>Description</th>
+</tr>
+<tr>
+ <td>Early Development</td>
+ <td>Version 2.3.0 not available</td>
+ <td>Provides an early look at documentation and sample application.</td>
+</tr>
+<tr>
+ <td>Test Development</td>
+ <td>Version 2.3.0 available to developers and users</td>
+ <td>In-app billing service allows static testing with reserved product IDs. You cannot publish applications that use in-app billing.</td>
+</tr>
+<tr>
+ <td>Final Release</td>
+ <td>Version 2.3.0 available to developers and users</td>
+ <td>In-app billing service allows end-to-end testing of in-app billing. You can publish applications that use in-app billing.</td>
+</tr>
+
+</table>
+
+<p>During the testing phase we will release version 2.3.0 of the Android Market application. This will allow you to test your in-app billing implementation using the <a href="{@docRoot}guide/market/billing/billing_testing.html#billing-testing-static">reserved product IDs and test responses</a>. However, you will not be able to test end-to-end in-app purchases during the testing phase, and you will not be able to publish an application that uses in in-app billing. </p>
+
+<p>After the testing phase is complete, we will release in-app billing to the general public. This will enable you to perform end-to-end tests of your in-app billing implementation using your actual in-app products. You will also be able to publish applications that use in-app billing.</p>
+
+<p>This documentation may change in the coming weeks as we move from the preview phase to the testing phase of this beta release. Be sure to check this documentation frequently for updates.</p>
\ No newline at end of file
diff --git a/docs/html/guide/market/billing/billing_admin.jd b/docs/html/guide/market/billing/billing_admin.jd
new file mode 100755
index 0000000..cc5cb59
--- /dev/null
+++ b/docs/html/guide/market/billing/billing_admin.jd
@@ -0,0 +1,185 @@
+page.title=Administering In-app Billing
+@jd:body
+
+<style type="text/css">
+ #jd-content {
+ background:transparent url({@docRoot}assets/images/preliminary.png) repeat scroll 0 0;
+ }
+</style>
+
+<div id="qv-wrapper">
+<div id="qv">
+ <h2>In this document</h2>
+ <ol>
+ <li><a href="#billing-list-setup">Creating a Product List</a></li>
+ <li><a href="#billing-purchase-type">Choosing a Purchase Type</a></li>
+ <li><a href="#billing-testing-setup">Setting up Test Accounts</a></li>
+ <li><a href="#billing-refunds">Handling Refunds</a></li>
+ <li><a href="#billing-support">Where to Get Support</a></li>
+ </ol>
+ <h2>Downloads</h2>
+ <ol>
+ <li><a href="{@docRoot}guide/market/billing/billing_integrate.html#billing-download">Sample Application</a></li>
+ </ol>
+ <h2>See also</h2>
+ <ol>
+ <li><a href="{@docRoot}guide/market/billing/billing_overview.html">Overview of In-app Billing</a></li>
+ <li><a href="{@docRoot}guide/market/billing/billing_integrate.html">Implementing In-app Billing</a></li>
+ <li><a href="{@docRoot}guide/market/billing/billing_best_practices.html">Security and Design</a></li>
+ <li><a href="{@docRoot}guide/market/billing/billing_testing.html">Testing In-app Billing</a></li>
+ <li><a href="{@docRoot}guide/market/billing/billing_reference.html">In-app Billing Reference</a></li>
+ </ol>
+</div>
+</div>
+
+<div class="special" style="margin-right:345px">
+ <p>This documentation provides an early look at the Android Market In-app Billing service. The documentation may change without notice.</p>
+</div>
+
+<p>In-app billing frees you from processing financial transactions, but you still need to perform a few administrative tasks, including setting up and maintaining your product list on the publisher site, registering test accounts, and handling refunds when necessary.</p>
+
+<p>You must have an Android Market publisher account to set up a product list and register test accounts. And you must have a Google Checkout merchant account to issue refunds to your users. If you already have a publisher account on Android Market, you can use your existing account. You do not need to register for a new account to support in-app billing. If you do not have a publisher account, you can register as an Android Market developer and set up a publisher account at the Android Market <a href="http://market.android.com/publish">publisher site</a>. If you do not have a Google Checkout merchant account, you can register for one at the <a href="http://checkout.google.com">Google Checkout site</a>.</p>
+
+<h2 id="billing-list-setup">Creating a Product List</h2>
+
+<p>The Android Market publisher site provides a product list for each of your published applications. You can sell an item using the in-app billing feature only if the item is listed on an application's product list. Each application has its own product list; you cannot sell items that are listed in another application's product list.</p>
+
+<p>A product list contains information about the items you are selling, such as a product id, product description, and price (see figure 1). The product list stores only metadata about the items you are selling in your application. It does not store any digital content. You are responsible for storing and delivering the digital content that you sell in your applications.</p>
+
+<div style="margin-bottom:2em;">
+<img src="{@docRoot}images/billing_product_list.png" style="text-align:left;margin-bottom:0;" />
+<div style="margin:0 2em;padding:0"><strong>Figure 1.</strong> An application's product list.</div>
+</div>
+
+<p>You can create a product list for a published application or a draft application that's been uploaded and saved to the Android Market site. However, the application's manifest must include the com.android.vending.BILLING permission. If an application's manifest does not include this permission, you will be able to edit existing items in the product list but you will not be able to add new items to the list. For more information, see <a href="#billing-permission">Modifying your application's AndroidManifest.xml file</a>.</p>
+
+<p>To create a product list for an application, follow these steps:</p>
+
+<ol>
+ <li><a href="http://market.android.com/publish">Log in</a> to your publisher account.</li>
+ <li>In the <strong>All Android Market listings</strong> panel, under the application name, click <strong>In-app Products</strong>.</li>
+ <li>On the In-app Products List page, click <strong>Add in-app product</strong>.</li>
+ <li>On the Create New In-app Product page (see figure 2), provide details about the item you are selling and then click <strong>Save</strong>.</li>
+</ol>
+
+<div style="margin-bottom:2em;">
+<img src="{@docRoot}images/billing_list_form.png" style="text-align:left;margin-bottom:0;" />
+<div style="margin:0 2em;padding:0"><strong>Figure 2.</strong> The Create New In-app Product page lets you add items to an application's product list.</div>
+</div>
+
+<p>You must enter the following information for each item in a product list:</p>
+<ul>
+ <li><strong>In-app Product ID</strong>
+ <p>Product IDs are unique across an application's namespace. A product ID must start with a lowercase letter or a number, and must be composed using only lowercase letters (a-z), numbers (0-9), underlines (_), and dots (.). The product ID "android.test" is reserved, as are all product IDs that start with "android.test."</p>
+ <p>In addition, you cannot modify an item's product ID after it is created, and you cannot reuse a product ID, even if you delete the item previously using the product ID.</p>
+ </li>
+ <li><strong>Purchase type</strong>
+ <p>The purchase type can be "managed per user account" or "unmanaged." You can specify an item's purchase type only through the publisher site and you can never change an item's purchase type once you specify it. For more information, see <a href="#billing_purchase_type">Choosing a purchase type</a> later in this document.</p>
+ </li>
+ <li><strong>Publishing State</strong>
+ <p>An item's publishing state can be "published" or "unpublished." However, to be visible to a user during checkout, an item's publishing state must be set to "published" and the item's application must be published on Android Market. (Note: This is not true for test accounts: that is, an item is visible to a trusted tester if the application is not published and the item is published. See <a href="{@docRoot}guide/market/billing/billing_testing.html#billing-testing-real">Testing In-app Billing</a> for more information.)</p>
+ </li>
+ <li><strong>Language</strong>
+ <p>A product list inherits its language from the parent application.</p>
+ </li>
+ <li><strong>Title</strong>
+ <p>The title is a short descriptor for the item. For example, "sleeping potion." Titles must be unique across an application's namespace. Every item must have a title. The title is visible to users during checkout.</p>
+ </li>
+ <li><strong>Description</strong>
+ <p>The description is a long descriptor for the item. For example, "Instantly puts creatures to sleep. Does not work on angry elves." Every item must have a description. The description is visible to users during checkout.</p>
+ </li>
+ <li><strong>Price</strong>
+ <p>Every item must have a price greater than zero; you cannot sell free items.</p>
+ </li>
+</ul>
+
+<p class="note"><strong>Note</strong>: Be sure to plan your product ID namespace. You cannot reuse or modify product IDs after you save them.</p>
+
+<h3 id="billing-purchase-type">Choosing a Purchase Type</h3>
+
+<p>An item's purchase type controls how Android Market manages the purchase of the item. There are two purchase types: "managed per user account" and "unmanaged."</p>
+
+<p>Items that are managed per user account can be purchased only once per user account. When an item is managed per user account, Android Market permanently stores the transaction information for each item on a per-user basis. This enables you to query Android Market with the <code>RESTORE_TRANSACTIONS</code> request and restore the state of the items a specific user has purchased.</p>
+
+<p>If a user attempts to purchase a managed item that has already been purchased, Android Market displays an "Item already purchased" error. This occurs during checkout, when Android Market displays the price and description information on the checkout page. When the user dismisses the error message, the checkout page disappears and the user returns to your user interface. As a best practice, your application should prevent the user from seeing this error. The sample application demonstrates how you can do this by keeping track of items that are managed and already purchased and not allowing users to select those items from the list. Your application should do something similar—either graying out the item or hiding it so that it cannot be selected.</p>
+
+<p>The "manage by user account" purchase type is useful if you are selling items such as game levels or application features. These items are not transient and usually need to be restored whenever a user reinstalls your application, wipes the data on their device, or installs your application on a new device.</p>
+
+<p>Items that are unmanaged do not have their transaction information stored on Android Market, which means you cannot query Android Market to retrieve transaction information for items whose purchase type is listed as unmanaged. You are responsible for managing the transaction information of unmanaged items. Also, unmanaged items can be purchased multiple times as far as Android Market is concerned, so it's also up to you to control how many times an unmanaged item can be purchased.</p>
+
+<p>The "unmanaged" purchase type is useful if you are selling consumable items, such as fuel or magic spells. These items are consumed within your application and are usually purchased multiple times.</p>
+
+<h2 id="billing-refunds">Handling Refunds</h2>
+
+<p>The in-app billing feature does not allow users to send a refund request to Android Market. Refunds for purchases that were made with the in-app billing feature must be directed to you (the application developer). You can then process the refund through your Google Checkout merchant account. When you do this, Android Market receives a refund notification from Google Checkout, and Android Market sends a refund message to your application. Your application can handle this message the same way it handles the response from an application-initiated <code>REQUEST_PURCHASE</code> message so that ultimately your application receives a purchase state change message that includes information about the item that's been refunded.</p>
+
+<h2 id="billing-testing-setup">Setting Up Test Accounts</h2>
+
+<p>The Android Market publisher site lets you set up one or more test accounts. A test account is a regular Google account that you register on the publisher site as a test account. Test accounts are authorized to make in-app purchases from applications that you have uploaded to the Android Market site but have not yet published.</p>
+
+<p>You can use any Google account as a test account. Test accounts are useful if you want to let multiple people test in-app billing on applications without giving them access to your publisher account's sign-in credentials. If you want to own and control the test accounts, you can create the accounts yourself and distribute the credentials to your developers or testers.</p>
+
+<p>Test accounts have three limitations:</p>
+
+<ul>
+ <li>Test account users can make purchase requests only within applications that are already uploaded to your publisher account (although the application doesn't need to be published).</li>
+ <li>Test accounts can only be used to purchase items that are listed (and published) in an application's product list.</li>
+ <li>Test account users do not have access to your publisher account and cannot upload applications to your publisher account.</li>
+</ul>
+
+<p>To add test accounts to your publisher account, follow these steps:</p>
+
+<ol>
+ <li><a href="http://market.android.com/publish">Log in</a> to your publisher account.</li>
+ <li>On the upper left part of the page, under your name, click <strong>Edit profile</strong>.</li>
+ <li>On the Edit Profile page, scroll down to the Licensing & In-app Billing panel (see figure 3).</li>
+ <li>In Test Accounts, add the email addresses for the test accounts you want to register, separating each account with a comma.</li>
+ <li>Click <strong>Save</strong> to save your profile changes.</li>
+</ol>
+
+<div style="margin-bottom:2em;">
+<img src="{@docRoot}images/billing_public_key.png" style="text-align:left;margin-bottom:0;" />
+<div style="margin:0 2em;padding:0"><strong>Figure 3.</strong> The Licensing and In-app Billing
+panel of your account's Edit Profile page lets you register test accounts.</div>
+</div>
+
+<h2 id="billing-support">Where to Get Support</h2>
+
+<p>If you have questions or encounter problems while implementing in-app billing, contact the support resources listed in the following table (see table 2). By directing your queries to the correct forum, you can get the support you need more quickly.</p>
+
+<p class="table-caption" id="support-table"><strong>Table 2.</strong> Developer support resources for Android Market in-app billing.</p>
+
+<table>
+
+<tr>
+<th>Support Type</th>
+<th>Resource</th>
+<th>Range of Topics</th>
+</tr>
+<tr>
+<td rowspan="2">Development and testing issues</td>
+<td>Google Groups: <a href="http://groups.google.com/group/android-developers">android-developers</a> </td>
+<td rowspan="2">In-app billing integration questions, user experience ideas, handling of responses, obfuscating code, IPC, test environment setup.</td>
+</tr>
+<tr>
+<td>Stack Overflow: <a
+href="http://stackoverflow.com/questions/tagged/android">http://stackoverflow.com/questions/tagged/android</a></td>
+</tr>
+<tr>
+<td>Accounts, publishing, and deployment issues</td>
+<td><a href="http://www.google.com/support/forum/p/Android+Market">Android
+Market Help Forum</a></td>
+<td>Publisher accounts, Android Market key pair, test accounts, server responses, test responses, application deployment and results.</td>
+</tr>
+<tr>
+<td>Market billing issue tracker</td>
+<td><a href="http://code.google.com/p/marketbilling/issues/">Market billing
+project issue tracker</a></td>
+<td>Bug and issue reports related specifically to in-app billing sample code.</td>
+</tr>
+</table>
+
+<p>For general information about how to post to the groups listed above, see <a href="{@docRoot}resources/community-groups.html">Developer Forums</a> document in the Resources tab.</p>
+
+
+
diff --git a/docs/html/guide/market/billing/billing_best_practices.jd b/docs/html/guide/market/billing/billing_best_practices.jd
new file mode 100755
index 0000000..fd67e80
--- /dev/null
+++ b/docs/html/guide/market/billing/billing_best_practices.jd
@@ -0,0 +1,79 @@
+page.title=Security and Design
+@jd:body
+
+<style type="text/css">
+ #jd-content {
+ background:transparent url({@docRoot}assets/images/preliminary.png) repeat scroll 0 0;
+ }
+</style>
+
+<div id="qv-wrapper">
+<div id="qv">
+ <h2>In this document</h2>
+ <ol>
+ <li><a href="#billing-security">Security Best Practices</a></li>
+ </ol>
+ <h2>Downloads</h2>
+ <ol>
+ <li><a href="{@docRoot}guide/market/billing/billing_integrate.html#billing-download">Sample Application</a></li>
+ </ol>
+ <h2>See also</h2>
+ <ol>
+ <li><a href="{@docRoot}guide/market/billing/billing_overview.html">Overview of In-app Billing</a></li>
+ <li><a href="{@docRoot}guide/market/billing/billing_integrate.html">Implementing In-app Billing</a></li>
+ <li><a href="{@docRoot}guide/market/billing/billing_testing.html">Testing In-app Billing</a></li>
+ <li><a href="{@docRoot}guide/market/billing/billing_admin.html">Administering In-app Billing</a></li>
+ <li><a href="{@docRoot}guide/market/billing/billing_reference.html">In-app Billing Reference</a></li>
+ </ol>
+</div>
+</div>
+
+<div class="special" style="margin-right:345px">
+ <p>This documentation provides an early look at the Android Market In-app Billing service. The documentation may change without notice.</p>
+</div>
+<p>As you design your in-app billing implementation, be sure to follow the security and design guidelines that are discussed in this document. These guidelines are recommended best practices for anyone who is using the Android Market In-app Billing service and can be incorporated into any in-app billing implementation.</p>
+
+<h2>Security Best Practices</h2>
+
+<h4>Perform signature verification tasks on a server</h4>
+<p>If practical, you should perform signature verification on a remote server and not on a device. Implementing the verification process on a server makes it difficult for attackers to break the verification process by reverse engineering your .apk file. If you do offload security processing to a remote server, be sure that the device-server handshake is secure.</p>
+
+<h4>Protect your unlocked content</h4>
+<p>To prevent malicious users from redistributing your unlocked content, do not bundle it in your .apk file. Instead, do one of the following:</p>
+ <ul>
+ <li>Use a real-time service to deliver your content, such as a content feed. Delivering content through a real-time service allows you to keep your content fresh.</li>
+ <li>Use a remote server to deliver your content.</li>
+ </ul>
+<p>When you deliver content from a remote server or a real-time service, you can store the unlocked content in device memory or store it on the device's SD card. If you store content on an SD card, be sure to encrypt the content and use a device-specific encryption key.</p>
+
+<h4>Obfuscate your code</h4>
+<p>You should obfuscate your in-app billing code so it is difficult for an attacker to reverse engineer security protocols and other application components. At a minimum, we recommend that you run an obfuscation tool like <a href="http://developer.android.com/guide/developing/tools/proguard.html">Proguard</a> on your code.</p>
+<p>In addition to running an obfuscation program, we recommend that you use the following techniques to obfuscate your in-app billing code.</p>
+<ul>
+ <li>Inline methods into other methods.</li>
+ <li>Construct strings on the fly instead of defining them as constants.</li>
+ <li>Use Java reflection to call methods.</li>
+</ul>
+<p>Using these techniques can help reduce the attack surface of your application and help minimize attacks that can compromise your in-app billing implementation.</p>
+<div class="note">
+ <p><strong>Note:</strong> If you use Proguard to obfuscate your code, you must add the following line to your Proguard configuration file:</p>
+ <p><code>-keep class com.android.vending.billing.**</code></p>
+</div>
+
+<h4>Modify all sample application code</h4>
+<p>The in-app billing sample application is publicly distributed and can be downloaded by anyone, which means it is relatively easy for an attacker to reverse engineer your application if you use the sample code exactly as it is published. The sample application is intended to be used only as an example. If you use any part of the sample application, you must modify it before you publish it or release it as part of a production application.</p>
+<p>In particular, attackers look for known entry points and exit points in an application, so it is important that you modify these parts of your code that are identical to the sample application.</p>
+
+<h4>Use secure random nonces</h4>
+<p>Nonces must not be predictable or reused. Always use a cryptographically secure random number generator (like {@link java.security.SecureRandom}) when you generate nonces. This can help reduce replay attacks.</p>
+<p>Also, if you are performing nonce verification on a server, make sure that you generate the nonces on the server.</p>
+
+<h4>Take action against trademark and copyright infringement</h4>
+<p>If you see your content being redistributed on Android Market, act quickly and decisively. File a <a href="http://market.android.com/support/bin/answer.py?hl=en&answer=141511">trademark notice of infringement</a> or a <a href="http://www.google.com/android_dmca.html">copyright notice of infringement</a>.</p>
+
+<h4>Implement a revocability scheme for unlocked content</h4>
+<p>If you are using a remote server to deliver or manage content, have your application verify the purchase state of the unlocked content whenever a user accesses the content. This allows you to revoke use when necessary and minimize piracy.</p>
+
+<h4>Protect your Android Market public key</h4>
+<p>To keep your public key safe from malicious users and hackers, do not embed it in any code as a literal string. Instead, construct the string at runtime from pieces or use bit manipulation (for example, XOR with some other string) to hide the actual key. The key itself is not secret information, but you do not want to make it easy for a hacker or malicious user to replace the public key with another key.</p>
+
diff --git a/docs/html/guide/market/billing/billing_integrate.jd b/docs/html/guide/market/billing/billing_integrate.jd
new file mode 100755
index 0000000..0f081a5
--- /dev/null
+++ b/docs/html/guide/market/billing/billing_integrate.jd
@@ -0,0 +1,617 @@
+page.title=Implementing In-app Billing
+@jd:body
+
+<style type="text/css">
+ #jd-content {
+ background:transparent url({@docRoot}assets/images/preliminary.png) repeat scroll 0 0;
+ }
+</style>
+
+<div id="qv-wrapper">
+<div id="qv">
+ <h2>In this document</h2>
+ <ol>
+ <li><a href="#billing-download">Downloading the Sample Application</a></li>
+ <li><a href="#billing-add-aidl">Adding the AIDL file to your project</a></li>
+ <li><a href="#billing-permission">Updating Your Application's Manifest</a></li>
+ <li><a href="#billing-service">Creating a Service</a></li>
+ <li><a href="#billing-broadcast-receiver">Creating a BroadcastReceiver</a></li>
+ <li><a href="#billing-signatures">Creating a security processing component</a></li>
+ <li><a href="#billing-implement">Modifying Your Application Code</a></li>
+ </ol>
+ <h2>Downloads</h2>
+ <ol>
+ <li><a href="#billing-download">Sample Application</a></li>
+ </ol>
+ <h2>See also</h2>
+ <ol>
+ <li><a href="{@docRoot}guide/market/billing/billing_overview.html">Overview of In-app Billing</a></li>
+ <li><a href="{@docRoot}guide/market/billing/billing_best_practices.html">Security and Design</a></li>
+ <li><a href="{@docRoot}guide/market/billing/billing_testing.html">Testing In-app Billing</a></li>
+ <li><a href="{@docRoot}guide/market/billing/billing_admin.html">Administering In-app Billing</a></li>
+ <li><a href="{@docRoot}guide/market/billing/billing_reference.html">In-app Billing Reference</a></li>
+ </ol>
+</div>
+</div>
+
+<div class="special" style="margin-right:345px">
+ <p>This documentation provides an early look at the Android Market In-app Billing service. The documentation may change without notice.</p>
+</div>
+
+<p>The Android Market In-app Billing service provides a straightforward, simple interface for sending in-app billing requests and managing in-app billing transactions using Android Market. This document helps you implement in-app billing by stepping through the primary implementation tasks, using the in-app billing sample application as an example.</p>
+
+<p>Before you implement in-app billing in your own application, be sure that you read <a href="{@docRoot}guide/market/billing/billing_overview.html">Overview of In-app Billing</a> and <a href="{@docRoot}guide/market/billing/billing_best_practices.html">Security and Design</a>. These documents provide background information that will make it easier for you to implement in-app billing.</p>
+
+<p>To implement in-app billing in your application, you need to do the following:</p>
+<ol>
+ <li><a href="#billing-download">Download the in-app billing sample application</a>.</li>
+ <li><a href="#billing-add-aidl">Add the IMarketBillingService.aidl file</a> to your project.</li>
+ <li><a href="#billing-permission">Update your AndroidManifest.xml file</a>.</li>
+ <li><a href="#billing-service">Create a Service</a> and bind it to the <code>MarketBillingService</code> so your application can send billing requests and receive billing responses from the Android Market application.</li>
+ <li><a href="#billing-broadcast-receiver">Create a BroadcastReceiver</a> to handle broadcast intents from the Android Market application.</li>
+ <li><a href="#billing-signatures">Create a security processing component</a> to verify the integrity of the transaction messages that are sent by Android Market .</li>
+ <li><a href="#billing-implement">Modify your application code</a> to support in-app billing.</li>
+</ol>
+
+<h2 id="billing-download">Downloading the Sample Application</h2>
+
+<p>The in-app billing sample application shows you how to perform several tasks that are common to all in-app billing implementations, including:</p>
+
+<ul>
+ <li>Sending in-app billing requests to the Android Market application.</li>
+ <li>Handling synchronous responses from the Android Market application.</li>
+ <li>Handling broadcast intents (asynchronous responses) from the Android Market application.</li>
+ <li>Using in-app billing security mechanisms to verify the integrity of billing responses.</li>
+ <li>Creating a user interface that lets users select items for purchase.</li>
+</ul>
+
+<p>The sample application includes an application file (<code><code>Dungeons.java</code></code>), the AIDL file for the <code>MarketBillingService</code> (<code>IMarketBillingService.aidl</code>), and several classes that demonstrate in-app billing messaging. It also includes a class that demonstrates basic security tasks, such as signature verification.</p>
+
+<p>Table 1 lists the source files that are included with the sample application.</p>
+<p class="table-caption" id="source-files-table"><strong>Table 1.</strong>
+In-app billing sample application source files.</p>
+
+<table>
+<tr>
+<th>File</th>
+<th>Description</th>
+</tr>
+
+<tr>
+<td>IMarketBillingService.aidl</td>
+<td>Android Interface Definition Library (AIDL) file that defines the IPC interface to the Android Market in-app billing service (<code>MarketBillingService</code>).</td>
+</tr>
+
+<tr>
+<td>Dungeons.java</td>
+<td>Sample application file that provides a UI for making purchases and diplaying purchase history.</td>
+</tr>
+
+<tr>
+<td>PurchaseDatabase.java</td>
+<td>A local database for storing purchase information.</td>
+</tr>
+
+<tr>
+ <td>BillingReceiver.java</td>
+ <td>A {@link android.content.BroadcastReceiver} that receives asynchronous response messages (broadcast intents) from Android Market. Forwards all messages to the <code>BillingService</code>.</td>
+</tr>
+<tr>
+ <td>BillingService.java</td>
+ <td>A {@link android.app.Service} that sends messages to Android Market on behalf of the application by connecting (binding) to the <code>MarketBillingService</code>.</td>
+</tr>
+
+<tr>
+ <td>ResponseHandler.java</td>
+ <td>A {@link android.os.Handler} that contains methods for updating the purchases database and the UI.</td>
+</tr>
+
+<tr>
+ <td>PurchaseObserver.java</td>
+ <td>An abstract class for observing changes related to purchases.</td>
+</tr>
+
+<tr>
+<td>Security.java</td>
+<td>Provides various security-related methods.</td>
+</tr>
+
+<tr>
+<td>Consts.java</td>
+<td>Defines various Android Market constants and sample application constants. All constants that are defined by Android Market must be defined the same way in your application.</td>
+</tr>
+
+<tr>
+<td>Base64.java and Base64DecoderException.java</td>
+<td>Provides conversion services from binary to Base64 encoding. The <code>Security</code> class relies on these utility classes.</td>
+</tr>
+
+</table>
+
+<p>The in-app billing sample application is available as a downloadable component of the Android SDK. To download the sample application component, launch the Android SDK and AVD Manager and then select the "Market Billing package, revision 1" component (see figure 1), and click <strong>Install Selected</strong> to begin the download.</p>
+
+<div style="margin-bottom:2em;">
+
+<img src="{@docRoot}images/billing_package.png" style="text-align:left;margin-bottom:0;" />
+<div style="margin:0 2em;padding:0"><strong>Figure 1.</strong> The Google Market
+Billing package contains the sample application and the AIDL file. </div>
+</div>
+
+<p>When the download is complete, the Android SDK and AVD Manager saves the component into the following directory:</p>
+
+<p><code><sdk>/google-market_billing/</code></p>
+
+<h2 id="billing-add-aidl">Adding the AIDL file to your project</h2>
+
+<p>The sample application contains an Android Interface Definition Language (AIDL) file, which defines the interface to the Android Market in-app billing service <code>MarketBillingService</code>). When you add this file to your project, the Android build environment creates an interface file (<code>IMarketBillingService.java</code>). You can then use this interface to make billing requests by invoking IPC method calls.</p>
+
+<p>If you are using the ADT plug-in with Eclipse, you can just add this file to your <code>/src</code> directory. Eclipse will automatically generate the interface file when you build your project (which should happen immediately). If you are not using the ADT plug-in, you can put the AIDL file into your project and use the Ant tool to build your project so that the <code>IMarketBillingService.java</code> file gets generated.</p>
+
+<p>To add the <code>IMarketBillingService.aidl</code> file to your project, do the following:</p>
+
+<ol>
+ <li>Create the following directory in your application's <code>/src</code> directory:
+ <p><code>com/android/vending/billing/</code></p>
+ </li>
+ <li>Copy the <code>IMarketBillingService.aidl</code> file into the <code>sample/src/com/android/vending/billing/</code> directory.</li>
+ <li>Build your application.</li>
+</ol>
+
+<p>You should now find a generated interface file named <code><code>IMarketBillingService.java</code></code> in the <code>gen</code> folder of your project.</p>
+
+<h2 id="billing-permission">Updating Your Application's Manifest</h2>
+
+<p>In-app billing relies on the Android Market application, which handles all communication between your application and the Android Market server. To use the Android Market application, your application must request the proper permission. You can do this by adding the <code>com.android.vending.BILLING</code> permission to your AndroidManifest.xml file. If your application does not declare the in-app billing permission, but attempts to send billing requests, Android Market will refuse the requests and respond with a <code>RESULT_DEVELOPER_ERROR</code> response code.</p>
+
+<p>In addition to the billing permission, you need to declare the {@link android.content.BroadcastReceiver} that you will use to receive asynchronous response messages (broadcast intents) from Android Market, and you need to declare the {@link android.app.Service} that you will use to bind with the <code>IMarketBillingService</code> and send messages to Android Market. You must also declare <a href="{@docRoot}guide/topics/manifest/intent-filter-element.html">intent filters</a> for the {@link android.content.BroadcastReceiver} so that the Android system knows how to handle broadcast intents that are sent from the Android Market application.</p>
+
+<p>For example, here's how the in-app billing sample application declares the billing permission, the {@link android.content.BroadcastReceiver}, the {@link android.app.Service}, and the intent filters. In the sample application, <code>BillingReceiver</code> is the {@link android.content.BroadcastReceiver} that handles broadcast intents from the Android Market application and <code>BillingService</code> is the {@link android.app.Service} that sends requests to the Android Market application.</p>
+
+<pre>
+<?xml version="1.0" encoding="utf-8"?>
+<manifest xmlns:android="http://schemas.android.com/apk/res/android"
+ package="com.example.dungeons"
+ android:versionCode="1"
+ android:versionName="1.0">
+
+ <uses-permission android:name="com.android.vending.BILLING" />
+
+ <application android:icon="@drawable/icon" android:label="@string/app_name">
+ <activity android:name=".Dungeons" android:label="@string/app_name">
+ <intent-filter>
+ <action android:name="android.intent.action.MAIN" />
+ <category android:name="android.intent.category.LAUNCHER" />
+ </intent-filter>
+ </activity>
+
+ <service android:name="BillingService" />
+
+ <receiver android:name="BillingReceiver">
+ <intent-filter>
+ <action android:name="com.android.vending.billing.IN_APP_NOTIFY" />
+ <action android:name="com.android.vending.billing.RESPONSE_CODE" />
+ <action android:name="com.android.vending.billing.PURCHASE_STATE_CHANGED" />
+ </intent-filter>
+ </receiver>
+
+ </application>
+</manifest>
+</pre>
+
+<h2 id="billing-service">Creating a Local Service</h2>
+
+<p>Your application must have a local {@link android.app.Service} to facilitate messaging between your application and Android Market. At a minimum, this service must do the following:</p>
+
+<ul>
+ <li>Bind to the <code>MarketBillingService</code>.
+ <li>Send billing requests (as IPC method calls) to the Android Market application. The five types of billing requests include:
+ <ul>
+ <li><code>CHECK_BILLING_SUPPORTED</code> requests</li>
+ <li><code>REQUEST_PURCHASE</code> requests</li>
+ <li><code>GET_PURCHASE_INFORMATION</code> requests</li>
+ <li><code>CONFIRM_NOTIFICATIONS</code> requests</li>
+ <li><code>RESTORE_TRANSACTIONS</code> requests</li>
+ </ul>
+ </li>
+ <li>Handle the synchronous response messages that are returned with each billing request.</li>
+</ul>
+
+<h3>Binding to the MarketBillingService</h3>
+
+<p>Binding to the <code>MarketBillingService</code> is relatively easy if you've already added the <code>IMarketBillingService.aidl</code> file to your project. The following code sample shows how to use the {@link android.content.Context#bindService bindService()} method to bind a service to the <code>MarketBillingService</code>. You could put this code in your service's {@link android.app.Activity#onCreate onCreate()} method.</p>
+
+<pre>
+try {
+ boolean bindResult = mContext.bindService(
+ new Intent(IMarketBillingService.class.getName()), this, Context.BIND_AUTO_CREATE);
+ if (bindResult) {
+ Log.i(TAG, "Service bind successful.");
+ } else {
+ Log.e(TAG, "Could not bind to the MarketBillingService.");
+ }
+} catch (SecurityException e) {
+ Log.e(TAG, "Security exception: " + e);
+}
+</pre>
+
+<p>After you bind to the service, you need to create a reference to the <code>IMarketBillingService</code> interface so you can make billing requests via IPC method calls. The following code shows you how to do this using the {@link android.content.ServiceConnection#onServiceConnected onServiceConnected()} callback method.</p>
+
+<pre>
+/**
+ * The Android system calls this when we are connected to the MarketBillingService.
+ */
+ public void onServiceConnected(ComponentName name, IBinder service) {
+ Log.i(TAG, "MarketBillingService connected.");
+ mService = IMarketBillingService.Stub.asInterface(service);
+ }
+</pre>
+
+<p>You can now use the <code>mService</code> reference to invoke the <code>sendBillingRequest()</code> method.</p>
+
+<p>For a complete implementation of a service that binds to the <code>MarketBillingService</code>, see the <code>BillingService</code> class in the sample application.</p>
+
+<h3>Sending billing requests to the MarketBillingService</h3>
+
+<p>Now that your {@link android.app.Service} has a reference to the <code>IMarketBillingService</code> interface, you can use that reference to send billing requests (via IPC method calls) to the <code>MarketBillingService</code>. The <code>MarketBillingService</code> IPC interface exposes a single public method (<code>sendBillingRequest()</code>), which takes a single {@link android.os.Bundle} parameter. The Bundle that you deliver with this method specifies the type of request you want to perform, using various key-value pairs. For instance, one key indicates the type of request you are making, another indicates the item being purchased, and another identifies your application. The <code>sendBillingRequest()</code> method immediately returns a Bundle containing an initial response code. However, this is not the complete purchase response; the complete response is delivered with an asynchronous broadcast intent. For more information about the various Bundle keys that are supported by the <code>MarketBillingService</code>, see <a href="{@docRoot}guide/market/billing/billing_reference.html#billing-interface">In-app Billing Service Interface</a>.</p>
+
+<p>You can use the <code>sendBillingRequest()</code> method to send five types of billing requests. The five request types are specified using the <code>BILLING_REQUEST</code> Bundle key. This Bundle key can have the following five values:</p>
+
+<ul>
+ <li><code>CHECK_BILLING_SUPPORTED</code>—verifies that the Android Market application supports in-app billing.</li>
+ <li><code>REQUEST_PURCHASE</code>—sends a purchase request for an in-app item.</li> <li><code>GET_PURCHASE_INFORMATION</code>—retrieves transaction information for a purchase or refund.</li>
+ <li><code>CONFIRM_NOTIFICATIONS</code>—acknowledges that you received the transaction information for a purchase or refund.</li>
+ <li><code>RESTORE_TRANSACTIONS</code>—retrieves a user's transaction history for <a href="{@docRoot}guide/market/billing/billing_admin.html#billing-purchase-type">managed purchases</a>.</li>
+</ul>
+
+<p>To make any of these billing requests, you first need to build an initial Bundle that contains the three keys that are required for all requests: <code>BILLING_REQUEST</code>, <code>API_VERSION</code>, and <code>PACKAGE_NAME</code>. The following code sample shows you how to create a helper method named <code>makeRequestBundle()</code> that does this.</p>
+
+<pre>
+protected Bundle makeRequestBundle(String method) {
+ Bundle request = new Bundle();
+ request.putString(BILLING_REQUEST, method);
+ request.putInt(API_VERSION, 1);
+ request.putString(PACKAGE_NAME, getPackageName());
+ return request;
+</pre>
+
+<p>To use this helper method, you pass in a <code>String</code> that corresponds to one of the five types of billing requests. The method returns a Bundle that has the three required keys defined. The following sections show you how to use this helper method when you send a billing request.<p>
+
+<p class="caution"><strong>Important</strong>: You must make all in-app billing requests from your application's main thread.</p>
+
+<h4>Verifying that in-app billing is supported (CHECK_BILLING_SUPPPORTED)</h4>
+
+<p>The following code sample shows how to verify whether the Android Market application supports in-app billing. In the sample, <code>mService</code> is an instance of the <code>MarketBillingService</code> interface.</p>
+
+<pre>
+/**
+* Request type is CHECK_BILLING_SUPPORTED
+*/
+ Bundle request = makeRequestBundle("CHECK_BILLING_SUPPORTED");
+ Bundle response = mService.sendBillingRequest(request);
+ // Do something with this response.
+}
+</pre>
+<p>The <code>makeRequestBundle()</code> method constructs an initial Bundle, which contains the three keys that are required for all requests: <code>BILLING_REQUEST</code>, <code>API_VERSION</code>, and <code>PACKAGE_NAME</code>. The request returns a synchronous {@link android.os.Bundle} response, which contains only a single key: <code>RESPONSE_CODE</code>. The <code>RESPONSE_CODE</code> key can have the following values:</p>
+<ul>
+ <li><code>RESULT_OK</code>—in-app billing is supported.</li>
+ <li><code>RESULT_BILLING_UNAVAILABLE</code>—in-app billing is not supported or the in-app billing API version you specified is not recognized.</li>
+ <li><code>RESULT_ERROR</code>—there was an error connecting with the Android Market appliction.</li>
+ <li><code>RESULT_DEVELOPER_ERROR</code>—the application is trying to make an in-app billing request but the application has not declared the com.android.vending.BILLING permission in its manifest. Can also indicate that an application is not properly signed, or that you sent a malformed request.</li>
+</ul>
+
+<p>The <code>CHECK_BILLING_SUPPORTED</code> request does not trigger any asynchronous responses (broadcast intents).</p>
+
+<h4>Making a purchase request (REQUEST_PURCHASE)</h4>
+
+<p>To make a purchase request you must do the following:</p>
+
+<ul>
+ <li>Send the <code>REQUEST_PURCHASE</code> request.</li>
+ <li>Launch the {@link android.app.PendingIntent} that is returned from the Android Market application.</li>
+ <li>Handle the broadcast intents that are sent by the Android Market application.</li>
+</ul>
+
+<h5>Making the request</h5>
+
+<p>You must specify four keys in the request {@link android.os.Bundle}. The following code sample shows how to set these keys and make a purchase request for a single in-app item. In the sample, <code>mProductId</code> is the Android Market product ID of an in-app item (which is listed in the application's <a href="{@docRoot}guide/market/billing/billing_admin.html#billing-list-setup">product list</a>), and <code>mService</code> is an instance of the <code>MarketBillingService</code> interface.</p>
+
+<pre>
+/**
+* Request type is REQUEST_PURCHASE
+*/
+ Bundle request = makeRequestBundle("REQUEST_PURCHASE");
+ request.putString(ITEM_ID, mProductId);
+ // Note that the developer payload is optional.
+ if (mDeveloperPayload != null) {
+ request.putString(DEVELOPER_PAYLOAD, mDeveloperPayload);
+ Bundle response = mService.sendBillingRequest(request);
+ // Do something with this response.
+ }
+</pre>
+<p>The <code>makeRequestBundle()</code> method constructs an initial Bundle, which contains the three keys that are required for all requests: <code>BILLING_REQUEST</code>, <code>API_VERSION</code>, and <code>PACKAGE_NAME</code>. The <code>ITEM_ID</code> key is then added to the Bundle prior to invoking the <code>sendBillingRequest()</code> method.</p>
+
+<p>The request returns a synchronous {@link android.os.Bundle} response, which contains three keys: <code>RESPONSE_CODE</code>, <code>PURCHASE_INTENT</code>, and <code>REQUEST_ID</code>. The <code>RESPONSE_CODE</code> key provides you with the status of the request and the <code>REQUEST_ID</code> key provides you with a unique request identifier for the request. The <code>PURCHASE_INTENT</code> key provides you with a {@link android.app.PendingIntent}, which you can use to launch the checkout UI.</p>
+
+<h5>Launching the pending intent</h5>
+
+<p>How you use the pending intent depends on which version of Android a device is running. On Android 1.6, you must use the pending intent to launch the checkout UI in its own separate task instead of your application's activity stack. On Android 2.0 and higher, you can use the pending intent to launch the checkout UI on your application's activity stack. The following code shows you how to do this. You can find this code in the PurchaseObserver.java file in the sample application.</p>
+
+<pre>
+void startBuyPageActivity(PendingIntent pendingIntent, Intent intent) {
+ if (mStartIntentSender != null) {
+ // This is on Android 2.0 and beyond. The in-app checkout page activity
+ // will be on the activity stack of the application.
+ try {
+ // This implements the method call:
+ // mActivity.startIntentSender(pendingIntent.getIntentSender(),
+ // intent, 0, 0, 0);
+ mStartIntentSenderArgs[0] = pendingIntent.getIntentSender();
+ mStartIntentSenderArgs[1] = intent;
+ mStartIntentSenderArgs[2] = Integer.valueOf(0);
+ mStartIntentSenderArgs[3] = Integer.valueOf(0);
+ mStartIntentSenderArgs[4] = Integer.valueOf(0);
+ mStartIntentSender.invoke(mActivity, mStartIntentSenderArgs);
+ } catch (Exception e) {
+ Log.e(TAG, "error starting activity", e);
+ }
+ } else {
+ // This is on Android 1.6. The in-app checkout page activity will be on its
+ // own separate activity stack instead of on the activity stack of
+ // the application.
+ try {
+ pendingIntent.send(mActivity, 0 /* code */, intent);
+ } catch (CanceledException e) {
+ Log.e(TAG, "error starting activity", e);
+ }
+ }
+}
+</pre>
+
+<p class="note">You must launch the pending intent from an activity context and not an application context.</p>
+
+<h5>Handling broadcast intents</h5>
+
+<p>A <code>REQUEST_PURCHASE</code> request also triggers two asynchronous responses (broadcast intents). First, the Android Market application sends an <code>ACTION_RESPONSE_CODE</code> broadcast intent, which provides error information about the request. Next, if the request was successful, the Android Market application sends an <code>ACTION_NOTIFY</code> broadcast intent. This message contains a notification ID, which you can use to retrieve the transaction details for the <code>REQUEST_PURCHASE</code> request.</p>
+
+<p>Keep in mind, the Android Market application also sends an <code>ACTION_NOTIFY</code> for refunds. For more information, see <a href="{@docRoot}guide/market/billing/billing_overview.html#billing-action-notify">Handling ACTION_NOTIFY messages</a>.</p>
+
+<h4>Retrieving transaction information for a purchase or refund (GET_PURCHASE_INFORMATION)</h4>
+
+<p>You retrieve transaction information in response to an <code>ACTION_NOTIFY</code> broadcast intent. The <code>ACTION_NOTIFY</code> message contains a notification ID, which you can use to retrieve transaction information.</p>
+
+<p>To retrieve transaction information for a purchase or refund you must specify five keys in the request {@link android.os.Bundle}. The following code sample shows how to set these keys and make the request. In the sample, <code>mService</code> is an instance of the <code>MarketBillingService</code> interface.</p>
+
+<pre>
+/**
+* Request type is GET_PURCHASE_INFORMATION
+*/
+ Bundle request = makeRequestBundle("GET_PURCHASE_INFORMATION");
+ request.putLong(REQUEST_NONCE, mNonce);
+ request.putStringArray(NOTIFY_IDS, mNotifyIds);
+ Bundle response = mService.sendBillingRequest(request);
+ // Do something with this response.
+}
+</pre>
+<p>The <code>makeRequestBundle()</code> method constructs an initial Bundle, which contains the three keys that are required for all requests: <code>BILLING_REQUEST</code>, <code>API_VERSION</code>, and <code>PACKAGE_NAME</code>. The additional keys are then added to the bundle prior to invoking the <code>sendBillingRequest()</code> method. The <code>REQUEST_NONCE</code> key contains a cryptographically secure nonce (number used once) that you must generate. The Android Market application returns this nonce with the <code>ACTION_PURCHASE_STATE_CHANGED</code> broadcast intent so you can verify the integrity of the transaction information. The <code>NOTIFY_IDS</code> key contains an array of notification IDs, which you received in the <code>ACTION_NOTIFY</code> broadcast intent.</p>
+
+<p>The request returns a synchronous {@link android.os.Bundle} response, which contains two keys: <code>RESPONSE_CODE</code> and <code>REQUEST_ID</code>. The <code>RESPONSE_CODE</code> key provides you with the status of the request and the <code>REQUEST_ID</code> key provides you with a unique request identifier for the request.</p>
+
+<p>A <code>GET_PURCHASE_INFORMATION</code> request also triggers two asynchronous responses (broadcast intents). First, the Android Market application sends an <code>ACTION_RESPONSE_CODE</code> broadcast intent, which provides status and error information about the request. Next, if the request was successful, the Android Market application sends an <code>ACTION_PURCHASE_STATE_CHANGED</code> broadcast intent. This message contains detailed transaction information. The transaction information is contained in a signed JSON string (unencrypted). The message includes the signature so you can verify the integrity of the signed string.</p>
+
+<h4>Acknowledging transaction information (CONFIRM_NOTIFICATIONS)</h4>
+
+<p>To acknowledge that you received transaction information you send a <code>CONFIRM_NOTIFICATIONS</code> request. You must specify four keys in the request {@link android.os.Bundle}. The following code sample shows how to set these keys and make the request. In the sample, <code>mService</code> is an instance of the <code>MarketBillingService</code> interface.</p>
+
+<pre>
+/**
+* Request type is CONFIRM_NOTIFICATIONS
+*/
+ Bundle request = makeRequestBundle("CONFIRM_NOTIFICATIONS");
+ request.putStringArray(NOTIFY_IDS, mNotifyIds);
+ Bundle response = mService.sendBillingRequest(request);
+ // Do something with this response.
+}
+</pre>
+<p>The <code>makeRequestBundle()</code> method constructs an initial Bundle, which contains the three keys that are required for all requests: <code>BILLING_REQUEST</code>, <code>API_VERSION</code>, and <code>PACKAGE_NAME</code>. The additional <code>NOTIFY_IDS</code> key is then added to the bundle prior to invoking the <code>sendBillingRequest()</code> method. The <code>NOTIFY_IDS</code> key contains an array of notification IDs, which you received in an <code>ACTION_NOTIFY</code> broadcast intent and also used in a <code>GET_PURCHASE_INFORMATION</code> request.</p>
+
+<p>The request returns a synchronous {@link android.os.Bundle} response, which contains two keys: <code>RESPONSE_CODE</code> and <code>REQUEST_ID</code>. The <code>RESPONSE_CODE</code> key provides you with the status of the request and the <code>REQUEST_ID</code> key provides you with a unique request identifier for the request.</p>
+
+<p>A <code>CONFIRM_NOTIFICATIONS</code> request triggers a single asynchronous response—an <code>ACTION_RESPONSE_CODE</code> broadcast intent. This broadcast intent provides status and error information about the request.</p>
+
+<h4>Restoring transaction information (RESTORE_TRANSACTIONS)</h4>
+
+<p>To restore a user's transaction information, you send a <code>RESTORE_TRANSACTIONS</code> request. You must specify four keys in the request {@link android.os.Bundle}. The following code sample shows how to set these keys and make the request. In the sample, <code>mService</code> is an instance of the <code>MarketBillingService</code> interface.</p>
+
+<pre>
+/**
+* Request type is RESTORE_TRANSACTIONS
+*/
+ Bundle request = makeRequestBundle("RESTORE_TRANSACTIONS");
+ request.putLong(REQUEST_NONCE, mNonce);
+ Bundle response = mService.sendBillingRequest(request);
+ // Do something with this response.
+}
+</pre>
+<p>The <code>makeRequestBundle()</code> method constructs an initial Bundle, which contains the three keys that are required for all requests: <code>BILLING_REQUEST</code>, <code>API_VERSION</code>, and <code>PACKAGE_NAME</code>. The additional <code>REQUEST_NONCE</code> key is then added to the bundle prior to invoking the <code>sendBillingRequest()</code> method. The <code>REQUEST_NONCE</code> key contains a cryptographically secure nonce (number used once) that you must generate. The Android Market application returns this nonce with the transactions information contained in the <code>ACTION_PURCHASE_STATE_CHANGED</code> broadcast intent so you can verify the integrity of the transaction information.</p>
+
+<p>The request returns a synchronous {@link android.os.Bundle} response, which contains two keys: <code>RESPONSE_CODE</code> and <code>REQUEST_ID</code>. The <code>RESPONSE_CODE</code> key provides you with the status of the request and the <code>REQUEST_ID</code> key provides you with a unique request identifier for the request.</p>
+
+<p>A <code>RESTORE_TRANSACTIONS</code> request also triggers two asynchronous responses (broadcast intents). First, the Android Market application sends an <code>ACTION_RESPONSE_CODE</code> broadcast intent, which provides status and error information about the request. Next, if the request was successful, the Android Market application sends an <code>ACTION_PURCHASE_STATE_CHANGED</code> broadcast intent. This message contains the detailed transaction information. The transaction information is contained in a signed JSON string (unencrypted). The message includes the signature so you can verify the integrity of the signed string.</p>
+
+
+<h3>Other service tasks</h3>
+
+<p>You may also want your {@link android.app.Service} to receive intent messages from your {@link android.content.BroadcastReceiver}. You can use these intent messages to convey the information that was sent asynchronously from the Android Market application to your {@link android.content.BroadcastReceiver}. To see an example of how you can send and receive these intent messages, see the BillingReceiver.java and BillingService.java files in the sample application. You can use these samples as a basis for your own implementation. However, if you use any of the code from the sample application, be sure you follow the guidelines in <a href="{@docRoot}guide/market/billing/billing_best_practices.html">Security and Design</a>.</p>
+
+<h2 id="billing-broadcast-receiver">Creating a BroadcastReceiver</h2>
+
+<p>The Android Market application uses broadcast intents to send asynchronous billing responses to your application. To receive these intent messages, you need to create a {@link android.content.BroadcastReceiver} that can handle the following intents:</p>
+
+<ul>
+ <li>ACTION_RESPONSE_CODE
+ <p>This broadcast intent contains an Android Market response code, and is sent after you make an in-app billing request. For more information about the response codes that are sent with this response, see <a href="{@docRoot}guide/market/billing/billing_reference.html#billing-codes">Android Market Response Codes for In-app Billing</a>.</p>
+ </li>
+ <li>ACTION_NOTIFY
+ <p>This response indicates that a purchase has changed state, which means a purchase succeeded, was canceled, or was refunded. For more information about notification messages, see <a href="{@docRoot}guide/market/billing/billing_reference.html#billing-intents">In-app Billing Broadcast Intents</a></p>
+ </li>
+ <li>ACTION_PURCHASE_STATE_CHANGED
+ <p>This broadcast intent contains detailed information about one or more transactions. For more information about purchase state messages, see <a href="{@docRoot}guide/market/billing/billing_reference.html#billing-intents">In-app Billing Broadcast Intents</a></p>
+ </li>
+</ul>
+
+<p>Each of these broadcast intents provide intent extras, which your {@link android.content.BroadcastReceiver} must handle. The intent extras are listed in the following table (see table 1).</p>
+
+<p class="table-caption"><strong>Table 1.</strong> Description of broadcast intent extras that are sent in response to billing requests.</p>
+
+<table>
+
+<tr>
+<th>Intent</th>
+<th>Extra</th>
+<th>Description</th>
+</tr>
+<tr>
+ <td><code>ACTION_RESPONSE_CODE</code></td>
+ <td><code>INAPP_REQUEST_ID</code></td>
+ <td>A <code>long</code> representing a request ID. A request ID identifies a specific billing request and is returned by Android Market at the time a request is made.</td>
+</tr>
+<tr>
+ <td><code>ACTION_RESPONSE_CODE</code></td>
+ <td><code>INAPP_RESPONSE_CODE</code></td>
+ <td>An <code>int</code> representing the actual Android Market server response code.</td>
+</tr>
+<tr>
+ <td><code>ACTION_NOTIFY</code></td>
+ <td><code>NOTIFICATION_ID</code></td>
+ <td>A <code>String</code> representing the notification ID for a given purchase state change. Android Market notifies you when there is a purchase state change and the notification includes a unique notification ID. To get the details of the purchase state change, you send the notification ID with the <code>GET_PURCHASE_INFORMATION</code> request.</td>
+</tr>
+<tr>
+ <td><code>ACTION_PURCHASE_STATE_CHANGED</code></td>
+ <td><code>INAPP_SIGNED_DATA</code></td>
+ <td>A <code>String</code> representing the signed JSON string. The JSON string contains information about the billing transaction, such as order number, amount, and the item that was purchased or refunded.</td>
+</tr>
+<tr>
+ <td><code>ACTION_PURCHASE_STATE_CHANGED</code></td>
+ <td><code>INAPP_SIGNATURE</code></td>
+ <td>A <code>String</code> representing the signature of the JSON string.</td>
+</tr>
+</table>
+
+<p>The following code sample shows how to handle these broadcast intents and intent extras within a {@link android.content.BroadcastReceiver}. The BroadcastReceiver in this case is named <code>BillingReceiver</code>, just as it is in the sample application.</p>
+
+<pre>
+public class BillingReceiver extends BroadcastReceiver {
+
+ private static final String TAG = "BillingReceiver";
+
+ // Intent actions that we receive in the BillingReceiver from Android Market.
+ // These are defined by Android Market and cannot be changed.
+ // The sample application defines these in the Consts.java file.
+ public static final String ACTION_NOTIFY = "com.android.vending.billing.IN_APP_NOTIFY";
+ public static final String ACTION_RESPONSE_CODE = "com.android.vending.billing.RESPONSE_CODE";
+ public static final String ACTION_PURCHASE_STATE_CHANGED =
+ "com.android.vending.billing.PURCHASE_STATE_CHANGED";
+
+ // The intent extras that are passed in an intent from Android Market.
+ // These are defined by Android Market and cannot be changed.
+ // The sample application defines these in the Consts.java file.
+ public static final String NOTIFICATION_ID = "notification_id";
+ public static final String INAPP_SIGNED_DATA = "inapp_signed_data";
+ public static final String INAPP_SIGNATURE = "inapp_signature";
+ public static final String INAPP_REQUEST_ID = "request_id";
+ public static final String INAPP_RESPONSE_CODE = "response_code";
+
+
+ @Override
+ public void onReceive(Context context, Intent intent) {
+ String action = intent.getAction();
+ if (ACTION_PURCHASE_STATE_CHANGED.equals(action)) {
+ String signedData = intent.getStringExtra(INAPP_SIGNED_DATA);
+ String signature = intent.getStringExtra(INAPP_SIGNATURE);
+ // Do something with the signedData and the signature.
+ } else if (ACTION_NOTIFY.equals(action)) {
+ String notifyId = intent.getStringExtra(NOTIFICATION_ID);
+ // Do something with the notifyId.
+ } else if (ACTION_RESPONSE_CODE.equals(action)) {
+ long requestId = intent.getLongExtra(INAPP_REQUEST_ID, -1);
+ int responseCodeIndex = intent.getIntExtra(INAPP_RESPONSE_CODE,
+ ResponseCode.RESULT_ERROR.ordinal());
+ // Do something with the requestId and the responseCodeIndex.
+ } else {
+ Log.w(TAG, "unexpected action: " + action);
+ }
+ }
+ // Perform other processing here, such as forwarding intent messages to your local service.
+}
+</pre>
+
+<p>In addition to receiving broadcast intents from the Android Market application, your {@link android.content.BroadcastReceiver} must handle the information it received in the broadcast intents. Usually, your {@link android.content.BroadcastReceiver} does this by sending the information to a local service (discussed in the next section). The BillingReceiver.java file in the sample application shows you how to do this. You can use this sample as a basis for your own {@link android.content.BroadcastReceiver}. However, if you use any of the code from the sample application, be sure you follow the guidelines that are discussed in <a href="{@docRoot}guide/market/billing/billing_best_practices.html">Security and Design </a>.</p>
+
+<h2 id="billing-signatures">Verifying Signatures and Nonces</h2>
+
+<p>The in-app billing service uses two mechanisms to help verify the integrity of the transaction information you receive from Android Market: nonces and signatures. A nonce (number used once) is a cryptographically secure number that your application generates and sends with every <code>GET_PURCHASE_INFORMATION</code> and <code>RESTORE_TRANSACTIONS</code> request. The nonce is returned with the <code>ACTION_PURCHASE_STATE_CHANGED</code> broadcast intent, enabling you to verify that any given <code>ACTION_PURCHASE_STATE_CHANGED</code> response corresponds to an actual request that you made. Every <code>ACTION_PURCHASE_STATE_CHANGED</code> broadcast intent also includes a signed JSON string and a signature, which you can use to verify the integrity of the response.</p>
+
+<p>Your application must provide a way to generate, manage, and verify nonces. The following sample code shows some simple methods you can use to do this.</p>
+
+<pre>
+ private static final SecureRandom RANDOM = new SecureRandom();
+ private static HashSet<Long> sKnownNonces = new HashSet<Long>();
+
+ public static long generateNonce() {
+ long nonce = RANDOM.nextLong();
+ sKnownNonces.add(nonce);
+ return nonce;
+ }
+
+ public static void removeNonce(long nonce) {
+ sKnownNonces.remove(nonce);
+ }
+
+ public static boolean isNonceKnown(long nonce) {
+ return sKnownNonces.contains(nonce);
+ }
+</pre>
+
+<p>Your application must also provide a way to verify the signatures that accompany every <code>ACTION_PURCHASE_STATE_CHANGED</code> broadcast intent. The Security.java file in the sample application shows you how to do this. If you use this file as a basis for your own security implementation, be sure to follow the guidelines in <a href="{@docRoot}guide/market/billing/billing_best_practices.html">Security and Design</a> and obfuscate your code.</p>
+
+<p>You will need to use your Android Market public key to perform the signature verification. The following procedure shows you how to retrieve Base64-encoded public key from the Android Market publisher site.</p>
+
+<ol>
+ <li>Log in to your <a href="http://market.android.com/publish">publisher account</a>.</li>
+ <li>On the upper left part of the page, under your name, click <strong>Edit profile</strong>.</li>
+ <li>On the Edit Profile page, scroll down to the Licensing & In-app Billing panel (see figure 2).</li>
+ <li>Copy your public key to the clipboard.</li>
+</ol>
+
+<p class="caution"><strong>Important</strong>: To keep your public key safe from malicious users and hackers, do not embed your public key as an entire literal string. Instead, construct the string at runtime from pieces or use bit manipulation (for example, XOR with some other string) to hide the actual key. The key itself is not secret information, but you do not want to make it easy for a hacker or malicious user to replace the public key with another key.</p>
+
+<div style="margin-bottom:2em;">
+
+<img src="{@docRoot}images/billing_public_key.png" style="text-align:left;margin-bottom:0;" />
+<div style="margin:0 2em;padding:0"><strong>Figure 2.</strong> The Licensing and In-app Billing
+panel of your account's Edit Profile page lets you see your public key.</div>
+</div>
+
+<h2 id="billing-implement">Modifying Your Application Code</h2>
+
+<p>After you finish adding in-app billing components to your project, you are ready to modify your application's code. For a typical implementation, like the one that is demonstrated in the sample application, this means you need to write code to do the following: </p>
+
+<ul>
+ <li>Create a storage mechanism for storing users' purchase information.</li>
+ <li>Create a user interface that lets users select items for purchase.</li>
+</ul>
+
+<p>The sample code in <code>Dungeons.java</code> shows you how to do both of these tasks.</p>
+
+<h3>Creating a storage mechanism for storing purchase information</h3>
+
+<p>You must set up a database or some other mechanism for storing users' purchase information. The sample application provides an example database (PurchaseDatabase.java); however, the example database has been simplified for clarity and does not exhibit the security best practices that we recommend. If you have a remote server, we recommend that you store purchase information on your server instead of in a local database on a device. For more information about security best practices, see <a href="{@docRoot}guide/market/billing/billing_best_practices.html">Security and Design</a>.</p>
+
+<p class="note"><strong>Note</strong>: If you store any purchase information on a device, be sure to encrypt the data and use a device-specific encryption key.</p>
+
+<h3>Creating a user interface for selecting items</h3>
+
+<p>You must provide users with a means for selecting items that they want to purchase. Android Market provides the checkout user interface (which is where the user provides a form of payment and approves the purchase), but your application must provide a control (widget) that invokes the <code>sendBillingRequest()</code> method when a user selects an item for purchase.</p>
+
+<p>You can render the control and trigger the <code>sendBillingRequest()</code> method any way you want. The sample application uses a spinner widget and a button to present items to a user and trigger a billing request (see <code>Dungeons.java</code>). The user interface also shows a list of recently purchased items.</p>
+
diff --git a/docs/html/guide/market/billing/billing_overview.jd b/docs/html/guide/market/billing/billing_overview.jd
new file mode 100755
index 0000000..675fe2a
--- /dev/null
+++ b/docs/html/guide/market/billing/billing_overview.jd
@@ -0,0 +1,267 @@
+page.title=Overview of In-app Billing
+@jd:body
+
+<style type="text/css">
+ #jd-content {
+ background:transparent url({@docRoot}assets/images/preliminary.png) repeat scroll 0 0;
+ }
+</style>
+
+<div id="qv-wrapper">
+<div id="qv">
+ <h2>In this document</h2>
+ <ol>
+ <li><a href="#billing-arch">In-app Billing Architecture</a></li>
+ <li><a href="#billing-msgs">In-app Billing Messages</a></li>
+ <ol>
+ <li><a href="#billing-request">Request messages</a></li>
+ <li><a href="#billing-response">Broadcast intents</a></li>
+ <li><a href="#billing-message-sequence">Messaging sequence</a></li>
+ <li><a href="#billing-action-notify">Handling ACTION_NOTIFY messages</a></li>
+ </ol>
+ <li><a href="#billing-security">Security Controls</a></li>
+ <li><a href="#billing-limitations">Requirements and Limitations</a></li>
+ </ol>
+ <h2>Downloads</h2>
+ <ol>
+ <li><a href="{@docRoot}guide/market/billing/billing_integrate.html#billing-download">Sample Application</a></li>
+ </ol>
+ <h2>See also</h2>
+ <ol>
+ <li><a href="{@docRoot}guide/market/billing/billing_integrate.html">Implementing In-app Billing</a></li>
+ <li><a href="{@docRoot}guide/market/billing/billing_best_practices.html">Security and Design</a></li>
+ <li><a href="{@docRoot}guide/market/billing/billing_testing.html">Testing In-app Billing</a></li>
+ <li><a href="{@docRoot}guide/market/billing/billing_admin.html">Administering In-app Billing</a></li>
+ <li><a href="{@docRoot}guide/market/billing/billing_reference.html">In-app Billing Reference</a></li>
+ </ol>
+</div>
+</div>
+
+<div class="special" style="margin-right:345px">
+ <p>This documentation provides an early look at the Android Market In-app Billing service. The documentation may change without notice.</p>
+</div>
+
+<p>The Android Market In-app Billing service is an Android Market feature that provides checkout processing for in-app purchases. To use the service, your application sends a billing request to the service for a specific in-app product. The service then handles all of the checkout details for the transaction, including requesting and validating the form of payment and processing the financial transaction. When the checkout process is complete, the service sends your application the purchase details, such as the order number, the order date and time, and the price paid. At no point does your application have to handle any financial transactions; that role is provided by the in-app billing service.</p>
+
+<h2 id="billing-arch">In-app Billing Architecture</h2>
+
+<p>In-app billing uses an asynchronous message loop to convey billing requests and billing responses between your application and the Android Market server. In practice, your application never directly communicates with the Android Market server (see figure 1). Instead, your application sends billing requests to the Android Market application over interprocess communication (IPC) and receives purchase responses from the Android Market application in the form of asynchronous broadcast intents. Your application does not manage any network connections between itself and the Android Market server or use any special APIs from the Android platform.</p>
+
+<p>Some in-app billing implementations may also use a private remote server to deliver content or validate transactions, but a remote server is not required to implement in-app billing. A remote server can be useful if you are selling digital content that needs to be delivered to a user's device, such as media files or photos. You might also use a remote server to store users' transaction history or perform various in-app billing security tasks, such as signature verification. Although you can handle all security-related tasks in your application, performing those tasks on a remote server is recommended because it helps make your application less vulnerable to security attacks.</p>
+
+<div class="figure" style="width:440px">
+<img src="{@docRoot}images/billing_arch.png" alt=""/>
+<p class="img-caption"><strong>Figure 1.</strong> Your application sends and receives billing messages through the Android Market application, which handles all communication with the Android Market server.</p>
+</div>
+
+<p>A typical in-app billing implementation relies on three components:</p>
+<ul>
+ <li>A {@link android.app.Service} (named <code>BillingService</code> in the sample application), which processes purchase messages from the application and sends billing requests to the in-app billing service.</li>
+ <li>A {@link android.content.BroadcastReceiver} (named <code>BillingReceiver</code> in the sample application), which receives all asynchronous billing responses from the Android Market application.</li>
+ <li>A security component (named <code>Security</code> in the sample application), which performs security-related tasks, such as signature verification and nonce generation. For more information about in-app billing security, see <a href="#billing-security">Security controls</a> later in this document.</li>
+</ul>
+
+<p>You may also want to incorporate two other components to support in-app billing:</p>
+<ul>
+ <li>A response {@link android.os.Handler} (named <code>ResponseHandler</code> in the sample application), which provides application-specific processing of purchase notifications, errors, and other status messages.</li>
+ <li>An observer (named <code>PurchaseObserver</code> in the sample application), which is responsible for sending callbacks to your application so you can update your user interface with purchase information and status.</li>
+</ul>
+
+<p>In addition to these components, your application must provide a way to store information about users' purchases and some sort of user interface that lets users select items to purchase. You do not need to provide a checkout user interface. When a user initiates an in-app purchase, the Android Market application presents the checkout user interface to your user. When the user completes the checkout process, your application resumes.</p>
+
+<h2 id="billing-msgs">In-app Billing Messages</h2>
+
+<p>When the user initiates a purchase, your application sends billing messages to the in-app billing service (named <code>MarketBillingService</code>) using simple IPC method calls. The Android Market application responds to all billing requests synchronously, providing your application with status notifications and other information. The Android Market application also responds to some billing requests asynchronously, providing your application with error messages and detailed transaction information. The following section describes the basic request-response messaging that takes place between your application and the Android Market application.</p>
+
+<h3 id="billing-request">In-app billing requests</h3>
+
+<p>Your application sends in-app billing requests by invoking a single IPC method (<code>sendBillingRequest()</code>), which is exposed by the <code>MarketBillingService</code> interface. This interface is defined in an <a href="{@docRoot}guide/developing/tools/aidl.html">Android Interface Definition Language</a> file (<code>IMarketBillingService.aidl</code>). You can download this AIDL file with the in-app billing sample application.</p>
+
+<p>The <code>sendBillingRequest()</code> method has a single {@link android.os.Bundle} parameter. The Bundle that you deliver must include several key-value pairs that specify various parameters for the request, such as the type of billing request you are making, the item that is being purchased, and the application that is making the request. For more information about the Bundle keys that are sent with a request, see <a href="{@docRoot}guide/market/billing/billing_reference.html#billing-interface">In-app Billing Service Interface</a>.
+
+<p>One of the most important keys that every request Bundle must have is the <code>BILLING_REQUEST</code> key. This key lets you specify the type of billing request you are making. The in-app billing service supports the following five types of billing requests:</p>
+
+<ul>
+ <li><code>CHECK_BILLING_SUPPORTED</code>
+ <p>This request verifies that the Android Market application supports in-app billing. You usually send this request when your application first starts up. This request is useful if you want to enable or disable certain UI features that are relevant only to in-app billing.</p>
+ </li>
+ <li><code>REQUEST_PURCHASE</code>
+ <p>This request sends a purchase message to the Android Market application and is the foundation of in-app billing. You send this request when a user indicates that he or she wants to purchase an item in your application. Android Market then handles the financial transaction by displaying the checkout user interface.</p>
+ </li>
+ <li><code>GET_PURCHASE_INFORMATION</code>
+ <p>This request retrieves the details of a purchase state change. A purchase changes state when a requested purchase is billed successfully or when a user cancels a transaction during checkout. It can also occur when a previous purchase is refunded. Android Market notifies your application when a purchase changes state, so you only need to send this request when there is transaction information to retrieve.</p>
+ </li>
+ <li><code>CONFIRM_NOTIFICATIONS</code>
+ <p>This request acknowledges that your application received the details of a purchase state change. Android Market sends purchase state change notifications to your application until you confirm that you received them.</p>
+ </li>
+ <li><code>RESTORE_TRANSACTIONS</code>
+ <p>This request retrieves a user's transaction status for managed purchases (see <a href="{@docRoot}guide/market/billing/billing_admin.html#billing-purchase-type">Choosing a Purchase Type</a> for more information). You should send this request only when you need to retrieve a user's transaction status, which is usually only when your application is reinstalled or installed for the first time on a device.</p>
+ </li>
+</ul>
+
+<h3 id="billing-response">In-app Billing Responses</h3>
+
+<p>The Android Market application responds to in-app billing requests with both synchronous and asynchronous responses. The synchronous response is a {@link android.os.Bundle} with the following three keys:</p>
+
+<ul>
+ <li><code>RESPONSE_CODE</code>
+ <p>This key provides status information and error information about a request.</p>
+ </li>
+ <li><code>PURCHASE_INTENT</code>
+ <p>This key provides a {@link android.app.PendingIntent}, which you use to launch the checkout activity.</p>
+ </li>
+ <li><code>REQUEST_ID</code>
+ <p>This key provides you with a request identifier, which you can use to match asynchronous responses with requests.</p>
+ </li>
+</ul>
+<p>Some of these keys are not relevant to every request. For more information, see <a href="#billing-message-sequence">Messaging sequence</a> later in this document.</p>
+
+<p>The asynchronous response messages are sent in the form of individual broadcast intents and include the following:</p>
+
+<ul>
+ <li><code>ACTION_RESPONSE_CODE</code>
+ <p>This response contains an Android Market server response code, and is sent after you make an in-app billing request. A server response code can indicate that a billing request was successfully sent to Android Market or it can indicate that some error occurred during a billing request. This response is <em>not</em> used to report any purchase state changes (such as refund or purchase information). For more information about the response codes that are sent with this response, see <a href="{@docRoot}guide/market/billing/billing_reference.html#billing-codes">Server Response Codes for In-app Billing</a>.</p>
+ </li>
+ <li><code>ACTION_NOTIFY</code>
+ <p>This response indicates that a purchase has changed state, which means a purchase succeeded, was canceled, or was refunded. This response contains one or more notification IDs. Each notification ID corresponds to a specific server-side message, and each messages contains information about one or more transactions. After your application receives an <code>ACTION_NOTIFY</code> broadcast intent, you send a <code>GET_PURCHASE_INFORMATION</code> request with the notification IDs to retrieve message details.</p>
+ </li>
+ <li><code>ACTION_PURCHASE_STATE_CHANGED</code>
+ <p>This response contains detailed information about one or more transactions. The transaction information is contained in a JSON string. The JSON string is signed and the signature is sent to your application along with the JSON string (unencrypted). To help ensure the security of your in-app billing messages, your application can verify the signature of this JSON string.</p>
+ </li>
+</ul>
+
+<p>The JSON string that is returned with the <code>ACTION_PURCHASE_STATE_CHANGED</code> intent provides your application with the details of one or more billing transactions. An example of this JSON string is shown below:</p>
+<pre class="no-pretty-print" style="color:black">
+{ "nonce" : 1836535032137741465,
+ "orders" :
+ { "notificationId" : "android.test.purchased",
+ "orderId" : "transactionId.android.test.purchased",
+ "packageName" : "com.example.dungeons",
+ "productId" : "android.test.purchased",
+ "developerPayload" : "bGoa+V7g/yqDXvKRqq+JTFn4uQZbPiQJo4pf9RzJ",
+ "purchaseTime" : 1290114783411,
+ "purchaseState" : 0 }
+}
+</pre>
+
+<p>The fields in the JSON string are described in the following table (see table 1):</p>
+
+<p class="table-caption"><strong>Table 1.</strong> Description of JSON fields that are returned with an <code>ACTION_PURCHASE_STATE_CHANGED</code> intent.</p>
+
+<table>
+
+<tr>
+<th>Field</th>
+<th>Description</th>
+</tr>
+<tr>
+ <td>nonce</td>
+ <td>A number used once. Your application generates the nonce and sends it with the <code>GET_PURCHASE_INFORMATION</code> request. Android Market sends the nonce back as part of the JSON string so you can verify the integrity of the message.</td>
+</tr>
+<tr>
+ <td>notificationId</td>
+ <td>A unique identifier that is sent with an <code>ACTION_NOTIFY</code> broadcast intent. Each <code>notificationId</code> corresponds to a specify message that is waiting to be retrieved on the Android Market server. Your application sends back the <code>notificationId</code> with the <code>GET_PURCHASE_INFORMATION</code> message so Android Market can determine which messages you are retrieving.</td>
+</tr>
+<tr>
+ <td>orderId</td>
+ <td>A unique order identifier for the transaction. This corresponds to the Google Checkout Order ID.</td>
+</tr>
+<tr>
+ <td>packageName</td>
+ <td>The application package from which the purchase originated.</td>
+</tr>
+<tr>
+ <td>productId</td>
+ <td>The item's product identifier. Every item has a product ID, which you must specify in the application's product list on the Android Market publisher site.</td>
+</tr>
+<tr>
+ <td>purchaseTime</td>
+ <td>The time the product was purchased, in milliseconds since the epoch (Jan 1, 1970).</td>
+</tr>
+
+<tr>
+ <td>purchaseState</td>
+ <td>The enum value for the purchase state, which indicates whether the purchase was successful, canceled, or refunded.</td>
+</tr>
+<tr>
+ <td>developerPayload</td>
+ <td>A developer-specified string that is associated with an order. This field is returned in the JSON string that contains transaction information for an order. You can use this field to send information with an order. For example, you can use this field to send index keys with an order, which is useful if you are using a database to store purchase information. We recommend that you do not use this field to send data or content.</td>
+</tr>
+</table>
+
+<h3 id="billing-message-sequence">Messaging sequence</h3>
+
+<p>The messaging sequence for a typical purchase request is shown in Figure 2. Request types for each <code>sendBillingRequest()</code> method are shown in <strong>bold</strong>, responses are shown in standard text. For clarity, Figure 2 does not show the <code>ACTION_RESPONSE_CODE</code> broadcast intents that are sent for every request. These responses provide status information or error information and are returned after each request.</p>
+
+<p>The basic message sequence for an in-app purchase request is as follows:</p>
+
+<ol>
+ <li>Your application sends a purchase request (<code>REQUEST_PURCHASE</code> type), specifying a product ID and other parameters.</li>
+ <li>The Android Market application sends your application a Bundle with a <code>RESPONSE_CODE</code>, <code>PURCHASE_INTENT</code>, and <code>REQUEST_ID</code>. The <code>PURCHASE_INTENT</code> provides a {@link android.app.PendingIntent}, which your application uses to start the checkout flow for the given product ID.</li>
+ <li>Your application launches the pending intent, which launches the checkout UI.</li>
+ <li>When the checkout flow finishes (that is, the user successfully purchases the item or cancels the purchase), Android Market sends your application a notification message (an <code>ACTION_NOTIFY</code> intent). The notification message includes a notification ID, which references the completed transaction.</li>
+ <li>Your application requests the transaction information by sending a <code>GET_PURCHASE_STATE_CHANGED</code> request, specifying the notification ID for the transaction.</li>
+ <li>The Android Market application sends a Bundle with a <code>RESPONSE_CODE</code> and a <code>REQUEST_ID</code>.
+ <li>Android Market sends the transaction information to your application in an <code>ACTION_PURCHASE_STATE_CHANGED</code> intent.</li>
+ <li>Your application confirms that you received the transaction information for the given notification ID by sending a confirmation message (<code>CONFIRM_NOTIFICATIONS</code> type), specifying the notification ID for which you received transaction information.</li>
+ <li>The Android Market applications sends your application a Bundle with a <code>RESPONSE_CODE</code> and a <code>REQUEST_ID</code>.</li>
+</ol>
+
+<p class="note"><strong>Note:</strong> You must launch the pending intent from an activity context and not an application context.</p>
+
+<div style="margin:2em 1em 1em 1em;">
+<img src="{@docRoot}images/billing_request_purchase.png" style="text-align:left;" />
+<div style="margin:.25em 1.25em;padding:0"><strong>Figure 2.</strong> Message sequence for a typical purchase request. Request types for each <code>sendBillingRequest()</code> method are shown in <strong>bold</strong> (<code>ACTION_RESPONSE_CODE</code> broadcast intents have been omitted).</div>
+</div>
+
+<p>The messaging sequence for a restore transaction request is shown in Figure 3. The request type for the <code>sendBillingRequest()</code> method is shown in <strong>bold</strong>, the responses are shown in standard text.</p>
+
+<div class="figure" style="width:490px">
+<img src="{@docRoot}images/billing_restore_transactions.png" alt=""/>
+<p class="img-caption"><strong>Figure 3.</strong> Message sequence for a restore transactions request.</p>
+</div>
+
+<p>The request triggers three responses. The first is a {@link android.os.Bundle} with a <code>RESPONSE_CODE</code> and a <code>REQUEST_ID</code>. Next, the Android Market application sends an <code>ACTION_RESPONSE_CODE</code> broadcast intent, which provides status information or error information about the request. As always, the <code>ACTION_RESPONSE_CODE</code> message references a specific request ID, so you can determine which request an <code>ACTION_RESPONSE_CODE</code> message pertains to.</p>
+
+<p>The <code>RESTORE_TRANSACTIONS</code> request type also triggers an <code>ACTION_PURCHASE_STATE_CHANGED</code> broadcast intent, which contains the same type of transaction information that is sent during a purchase request, although you do not need to respond to this intent with a <code>CONFIRM_NOTIFICATIONS</code> message.</p>
+
+<p>The messaging sequence for checking whether in-app billing is supported is shown in Figure 4. The request type for the <code>sendBillingRequest()</code> method is shown in <strong>bold</strong>, the response is shown in regular text.</p>
+
+<div class="figure" style="width:454px">
+<img src="{@docRoot}images/billing_check_supported.png" alt=""/>
+<p class="img-caption"><strong>Figure 4.</strong> Message sequence for checking whether in-app billing is supported.</p>
+</div>
+
+<p>The synchronous response for a <code>CHECK_BILLING_SUPPORTED</code> request provides a server response code. A <code>RESULT_OK</code> response code indicates that in-app billing is supported; a <code>RESULT_BILLING_UNAVAILABLE</code> response code indicates that the Android Market application does not support in-app billing and may need to be updated. A <code>SERVER_ERROR</code> can also be returned, indicating that there was a problem with the Android Market server. The <code>RESULT_BILLING_UNAVAILABLE</code> response code can also indicate that the user is ineligible for in-app billing (for example, the user resides in a country that does not allow in-app billing).</p>
+
+<h3 id="billing-action-notify">Handling ACTION_NOTIFY messages</h3>
+
+<p>Usually, your application receives an <code>ACTION_NOTIFY</code> intent from Android Market in response to a <code>REQUEST_PURCHASE</code> message (see figure 2). The <code>ACTION_NOTIFY</code> intent informs your application that the state of a requested purchase has changed. To retrieve the details of that state change, your application sends a <code>GET_PURCHASE_INFORMATION</code> request. Android Market responds with an <code>ACTION_PURCHASE_STATE_CHANGED</code> intent, which contains the details of the purchase state change. Your application then sends a <code>CONFIRM_NOTIFICATIONS</code> message, informing Android Market that you've received the purchase state change information.</p>
+
+<p>When Android Market receives a <code>CONFIRM_NOTIFICATIONS</code> message for a given message, it usually stops sending <code>ACTION_NOTIFY</code> intents for that message. However, there are some cases where Android Market may send repeated <code>ACTION_NOTIFY</code> intents for a message even though your application has sent a <code>CONFIRM_NOTIFICATIONS</code> message. This can occur if a device loses network connectivity while you are sending the <code>CONFIRM_NOTIFICATIONS</code> message. In this case, Android Market might not receive your <code>CONFIRM_NOTIFICATIONS</code> message and it could send multiple <code>ACTION_NOTIFY</code> messages until it receives acknowledgement that you received the message. Therefore, your application must be able to recognize that the subsequent <code>ACTION_NOTIFY</code> messages are for a previously processed transaction. You can do this by checking the <code>orderID</code> that's contained in the JSON string because every transaction has a unique <code>orderId</code>.</p>
+
+<p>Your application may also receive <code>ACTION_NOTIFY</code> intents even though your application has not sent a <code>REQUEST_PURCHASE</code> message. This can occur when a user has your application installed on two (or more) devices and the user makes an in-app purchase from one of the devices. In this case, Android Market sends an <code>ACTION_NOTIFY</code> message to the second device, informing the application that there is a purchase state change. Your application can handle this message the same way it handles the response from an application-initiated <code>REQUEST_PURCHASE</code> message, so that ultimately your application receives a purchase state change message that includes information about the item that's been purchased. This scenario applies only to items that have their <a href="{@docRoot}guide/market/billing/billing_admin.html#billing-purchase-type">purchase type</a> set to "managed per user account."</p>
+
+<h2 id="billing-security">Security Controls</h2>
+
+<p>To help ensure the integrity of the transaction information that is sent to your application, Android Market signs the JSON string that is contained in the <code>ACTION_PURCHASE_STATE_CHANGED</code> broadcast intent. Android Market uses the private key that is associated with your publisher account to create this signature. The publisher site generates an RSA key pair for each publisher account. You can find the public key portion of this key pair on your account's profile page. It is the same public key that is used with Android Market licensing.</p>
+
+<p>When Android Market signs a billing response, it includes the signed JSON string (unencrypted) and the signature. When your application receives this signed response you can use the public key portion of your RSA key pair to verify the signature. By performing signature verification you can help detect responses that have been tampered with or that have been spoofed. You can perform this signature verification step in your application; however, if your application connects to a secure remote server then we recommend that you perform the signature verification on that server.</p>
+
+<p>In-app billing also uses nonces (a random number used once) to help verify the integrity of the purchase information that's returned from Android Market. Your application must generate a nonce and send it with a <code>GET_PURCHASE_INFORMATION</code> request and a <code>RESTORE_TRANSACTIONS</code> request. When Android Market receives the request, it adds the nonce to the JSON string that contains the transaction information. The JSON string is then signed and returned to your application. When your application receives the JSON string, you need to verify the nonce as well as the signature of the JSON string.</p>
+
+<p>For more information about best practices for security and design, see <a href="{@docRoot}guide/market/billing/billing_best_practices.html">Security and Design</a>.</p>
+
+<h2 id="billing-limitations">In-app Billing Requirements and Limitations</h2>
+
+<p>Before you get started with in-app billing, be sure to review the following requirements and limitations.</p>
+
+<ul>
+ <li>In-app billing can be implemented only in applications that you publish through Android Market.</li>
+ <li>You must have a Google Checkout merchant account to use the in-app billing service.</li>
+ <li>An application can use in-app billing only if the current Android Market application is installed on its host device and the device is running Android 1.6 (API level 4) or higher.</li>
+ <li>A device must be running version 2.3.0 (or higher) of the Android Market application to support in-app billing.</li>
+ <li>You can use in-app billing to sell only digital content. You cannot use in-app billing to sell physical goods, personal services, or anything that requires physical delivery.</li>
+ <li>Android Market does not provide any form of content delivery. You are responsible for delivering the digital content that you sell in your applications.</li>
+ <li>You cannot implement in-app billing on a device that never connects to the network. To complete in-app purchase requests, a device must be able to access the Android Market server over the network. </li>
+</ul>
diff --git a/docs/html/guide/market/billing/billing_reference.jd b/docs/html/guide/market/billing/billing_reference.jd
new file mode 100755
index 0000000..357e58b
--- /dev/null
+++ b/docs/html/guide/market/billing/billing_reference.jd
@@ -0,0 +1,262 @@
+page.title=In-app Billing Reference
+@jd:body
+
+<style type="text/css">
+ #jd-content {
+ background:transparent url({@docRoot}assets/images/preliminary.png) repeat scroll 0 0;
+ }
+</style>
+
+<div id="qv-wrapper">
+<div id="qv">
+ <h2>In this document</h2>
+ <ol>
+ <li><a href="#billing-codes">Server Response Codes for In-app Billing</a></li>
+ <li><a href="#billing-interface">In-app Billing Service Interface</a></li>
+ <li><a href="#billing-intents">In-app Billing Broadcast Intents</a></li>
+
+ </ol>
+ <h2>Downloads</h2>
+ <ol>
+ <li><a href="{@docRoot}guide/market/billing/billing_integrate.html#billing-download">Sample Application</a></li>
+ </ol>
+ <h2>See also</h2>
+ <ol>
+ <li><a href="{@docRoot}guide/market/billing/billing_overview.html">Overview of In-app Billing</a></li>
+ <li><a href="{@docRoot}guide/market/billing/billing_integrate.html">Implementing In-app Billing</a></li>
+ <li><a href="{@docRoot}guide/market/billing/billing_best_practices.html">Security and Design</a></li>
+ <li><a href="{@docRoot}guide/market/billing/billing_testing.html">Testing In-app Billing</a></li>
+ <li><a href="{@docRoot}guide/market/billing/billing_admin.html">Administering In-app Billing</a></li>
+ </ol>
+</div>
+</div>
+
+<div class="special" style="margin-right:345px">
+ <p>This documentation provides an early look at the Android Market In-app Billing service. The documentation may change without notice.</p>
+</div>
+
+<p>The following document provides technical reference information for the following:</p>
+
+<ul>
+ <li><a href="#billing-codes">Android Market Server Response Codes for In-app Billing</a></li>
+ <li><a href="#billing-interface">In-app Billing Interface Parameters</a></li>
+ <li><a href="billing-intents">In-app Billing Broadcast Intents</a></li>
+</ul>
+
+<h2 id="billing-codes">Android Market Server Response Codes for In-app Billing</h2>
+
+<p>The following table lists all of the server response codes that are sent from Android Market to your application. Android Market sends these response codes asynchronously as <code>INAPP_RESPONSE_CODE</code> extras in the <code>ACTION_RESPONSE_CODE</code> broadcast intent. Your application must handle all of these response codes.</p>
+
+<p class="table-caption" id="response-codes-table"><strong>Table 1.</strong> Summary of response codes returned by Android Market.</p>
+
+<table>
+
+<tr>
+<th>Response Code</th>
+<th>Description</th>
+</tr>
+<tr>
+ <td><code>RESULT_OK</code></td>
+ <td>Indicates that the request was sent to the server successfully. When this code is returned in response to a <code>CHECK_BILLING_SUPPORTED</code> request, indicates that billing is supported.</td>
+</tr>
+<tr>
+ <td><code>RESULT_USER_CANCELED</code></td>
+ <td>Indicates that the user pressed the back button on the checkout page instead of buying the item.</td>
+</tr>
+<tr>
+ <td><code>RESULT_SERVICE_UNAVAILABLE</code></td>
+ <td>Indicates that the network connection is down.</td>
+</tr>
+<tr>
+ <td><code>RESULT_BILLING_UNAVAILABLE</code></td>
+ <td>Indicates that the <code>BILLING_API_VERSION</code> that you specified is not recognized by the Android Market application and that the Android Market application may have to be updated. Can also indicate that the user is ineligible for in-app billing. For example, the user resides in a country that does not allow in-app purchases.</td>
+</tr>
+<tr>
+ <td><code>RESULT_ITEM_UNAVAILABLE</code></td>
+ <td>Indicates that Android Market cannot find the requested item in the application's product list. This can happen if the product ID is misspelled in your <code>REQUEST_PURCHASE</code> request or if an item is unpublished in the application's product list.</td>
+</tr>
+<tr>
+ <td><code>RESULT_ERROR</code></td>
+ <td>Indicates an unexpected server error.</td>
+</tr>
+
+<tr>
+ <td><code>RESULT_DEVELOPER_ERROR</code></td>
+ <td>Indicates that an application is trying to make an in-app billing request but the application has not declared the com.android.vending.BILLING permission in its manifest. Can also indicate that an application is not properly signed, or that you sent a malformed request, such as a request with missing Bundle keys or a request that uses an unrecognized request type.</td>
+</tr>
+</table>
+
+<h2 id="billing-interface">In-app Billing Service Interface</h2>
+
+<p>The following section describes the interface for the Android Market In-app Billing service. The interface is defined in the <code>IMarketBillingService.aidl</code> file, which is included with the in-app billing <a href="{@docRoot}guide/market/billing/billing_integrate.html#billing-download">sample application</a>.</p>
+<p>The interface consists of a single request method <code>sendBillingRequest()</code>. This method takes a single {@link android.os.Bundle} parameter. The Bundle parameter includes several key-value pairs, which are summarized in Table 2.</p>
+
+<p class="table-caption"><strong>Table 2.</strong> Description of Bundle keys passed in a <code>sendBillingRequest()</code> request.</p>
+
+<table>
+
+<tr>
+<th>Key</th>
+<th>Type</th>
+<th>Possible Values</th>
+<th>Required?</th>
+<th>Description</th>
+</tr>
+<tr>
+ <td><code>BILLING_REQUEST</code></td>
+ <td>String</td>
+ <td><code>CHECK_BILLING_SUPPORTED</code>, <code>REQUEST_PURCHASE</code>, <code>GET_PURCHASE_INFORMATION</code>, <code>CONFIRM_NOTIFICATIONS</code>, or <code>RESTORE_TRANSACTIONS</code></td>
+ <td>Yes</td>
+ <td>The type of billing request you are making with the <code>sendBillingRequest()</code> request. The possible values are discussed more below this table.</td>
+</tr>
+<tr>
+ <td><code>BILLING_API_VERSION</code></td>
+ <td>int</td>
+ <td>0 (for alpha release); 1 (for beta release)</td>
+ <td>Yes</td>
+ <td>The version of the in-app billing service you are using.</td>
+</tr>
+<tr>
+ <td><code>PACKAGE_NAME</code></td>
+ <td>String</td>
+ <td>A valid package name.</td>
+ <td>Yes</td>
+ <td>The name of the application that is making the request.</td>
+</tr>
+<tr>
+ <td><code>ITEM_ID</code></td>
+ <td>String</td>
+ <td>Any valid product identifier.</td>
+ <td>Required for <code>REQUEST_PURCHASE</code> requests.</td>
+ <td>The product ID of the item you are making a billing request for. Every in-app item that you sell using the in-app billing service must have a unique product ID, which you specify on the Android Market publisher site.</td>
+</tr>
+<tr>
+ <td><code>NONCE</code></td>
+ <td>long</td>
+ <td>Any valid long value.</td>
+ <td>Required for <code>GET_PURCHASE_INFORMATION</code> and <code>RESTORE_TRANSACTIONS</code> requests.</td>
+ <td>A number used once. Your application must generate and send a nonce with each <code>GET_PURCHASE_INFORMATION</code> and <code>RESTORE_TRANSACTIONS</code> request. The nonce is returned with the <code>ACTION_PURCHASE_STATE_CHANGED</code> intent, so you can use this value to verify the integrity of transaction responses form Android Market.</td>
+</tr>
+<tr>
+ <td><code>NOTIFY_IDS</code></td>
+ <td>Array of long values</td>
+ <td>Any valid array of long values</td>
+ <td>Required for <code>GET_PURCHASE_INFORMATION</code> and <code>CONFIRM_NOTIFICATIONS</code> requests.</td>
+ <td>An array of notification identifiers. A notification ID is sent to your application in an <code>ACTION_NOTIFY</code> intent every time a purchase changes state. You use the notification to retrieve the details of the purchase state change.</td>
+</tr>
+<tr>
+ <td><code>DEVELOPER_PAYLOAD</code></td>
+ <td>String</td>
+ <td>Any valid String less than 256 characters long.</td>
+ <td>No</td>
+ <td>A developer-specified string that is associated with an order. This field is returned in the JSON string that contains transaction information for an order. You can use this field to send information with an order. For example, you can use this field to send index keys with an order, which is useful if you are using a database to store purchase information. We recommend that you do not use this field to send data or content.</td>
+</tr>
+</table>
+
+<p>The <code>BILLING_REQUEST</code> key can have the following values:</p>
+
+<ul>
+ <li><code>CHECK_BILLING_SUPPORTED</code>
+ <p>This request verifies that the Android Market application supports in-app billing. You usually send this request when your application first starts up. This request is useful if you want to enable or disable certain UI features that are relevant only to in-app billing.</p>
+ </li>
+ <li><code>REQUEST_PURCHASE</code>
+ <p>This request sends a purchase message to the Android Market application and is the foundation of in-app billing. You send this request when a user indicates that he or she wants to purchase an item in your application. Android Market then handles the financial transaction by displaying the checkout user interface.</p>
+ </li>
+ <li><code>GET_PURCHASE_INFORMATION</code>
+ <p>This request retrieves the details of a purchase state change. A purchase state change can occur when a purchase request is billed successfully or when a user cancels a transaction during checkout. It can also occur when a previous purchase is refunded. Android Market notifies your application when a purchase changes state, so you only need to send this request when there is transaction information to retrieve.</p>
+ </li>
+ <li><code>CONFIRM_NOTIFICATIONS</code>
+ <p>This request acknowledges that your application received the details of a purchase state change. That is, this message confirms that you sent a <code>GET_PURCHASE_INFORMATION</code> request for a given notification and that you received the purchase information for the notification.</p>
+ </li>
+ <li><code>RESTORE_TRANSACTIONS</code>
+ <p>This request retrieves a user's transaction status for managed purchases (see <a href="{@docRoot}guide/market/billing/billing_admin.html#billing-purchase-type">Choosing a Purchase Type</a> for more information). You should send this message only when you need to retrieve a user's transaction status, which is usually only when your application is reinstalled or installed for the first time on a device.</p>
+ </li>
+</ul>
+
+<p>Every in-app billing request generates a synchronous response. The response is a {@link android.os.Bundle} and can include one or more of the following keys:</p>
+
+<ul>
+ <li><code>RESPONSE_CODE</code>
+ <p>This key provides status information and error information about a request.</p>
+ </li>
+ <li><code>PURCHASE_INTENT</code>
+ <p>This key provides a {@link android.app.PendingIntent}, which you use to launch the checkout activity.</p>
+ </li>
+ <li><code>REQUEST_ID</code>
+ <p>This key provides you with a request identifier, which you can use to match asynchronous responses with requests.</p>
+ </li>
+</ul>
+
+<p>Some of these keys are not relevant to certain types of requests. Table 3 shows which keys are returned for each request type.</p>
+
+<p class="table-caption"><strong>Table 3.</strong> Description of Bundle keys that are returned with each in-app billing request type.</p>
+
+<table>
+
+<tr>
+<th>Request Type</th>
+<th>Keys Returned</th>
+<th>Possible Response Codes</th>
+</tr>
+<tr>
+ <td><code>CHECK_BILLING_SUPPORTED</code></td>
+ <td><code>RESPONSE_CODE</code></td>
+ <td><code>RESULT_OK</code>, <code>RESULT_BILLING_UNAVAILABLE</code>, <code>RESULT_ERROR</code>, <code>RESULT_DEVELOPER_ERROR</code></td>
+</tr>
+<tr>
+ <td><code>REQUEST_PURCHASE</code></td>
+ <td><code>RESPONSE_CODE</code>, <code>PURCHASE_INTENT</code>, <code>REQUEST_ID</code></td>
+ <td><code>RESULT_OK</code>, <code>RESULT_ERROR</code>, <code>RESULT_DEVELOPER_ERROR</code></td>
+</tr>
+<tr>
+ <td><code>GET_PURCHASE_INFORMATION</code></td>
+ <td><code>RESPONSE_CODE</code>, <code>REQUEST_ID</code></td>
+ <td><code>RESULT_OK</code>, <code>RESULT_ERROR</code>, <code>RESULT_DEVELOPER_ERROR</code></td>
+</tr>
+<tr>
+ <td><code>CONFIRM_NOTIFICATIONS</code></td>
+ <td><code>RESPONSE_CODE</code>, <code>REQUEST_ID</code></td>
+ <td><code>RESULT_OK</code>, <code>RESULT_ERROR</code>, <code>RESULT_DEVELOPER_ERROR</code></td>
+</tr>
+<tr>
+ <td><code>RESTORE_TRANSACTIONS</code></td>
+ <td><code>RESPONSE_CODE</code>, <code>REQUEST_ID</code></td>
+ <td><code>RESULT_OK</code>, <code>RESULT_ERROR</code>, <code>RESULT_DEVELOPER_ERROR</code></td>
+</tr>
+</table>
+
+<h2 id="billing-intents">In-app Billing Broadcast Intents</h2>
+
+<p>The following section describes the in-app billing broadcast intents that are sent by the Android Market application. These broadcast intents inform your application about in-app billing actions that have occurred. Your application must implement a {@link android.content.BroadcastReceiver} to receive these broadcast intents, such as the <code>BillingReceiver</code> that's shown in the in-app billing <a href="{@docRoot}guide/market/billing/billing_integrate.html#billing-download">sample application</a>.</p>
+
+<h4>ACTION_RESPONSE_CODE</h4>
+
+<p>This broadcast intent contains an Android Market response code, and is sent after you make an in-app billing request. A server response code can indicate that a billing request was successfully sent to Android Market or it can indicate that some error occurred during a billing request. This intent is not used to report any purchase state changes (such as refund or purchase information). For more information about the response codes that are sent with this response, see <a href="#billing-codes">Android Market Response Codes for In-app Billing</a>.</p>
+
+<h5>Extras</h5>
+
+<ul type="none">
+ <li><code>INAPP_REQUEST_ID</code>—a long representing a request ID. A request ID identifies a specific billing request and is returned by Android Market at the time a request is made.</li>
+ <li><code>INAPP_RESPONSE_CODE</code>—an int representing the Android Market server response code.</li>
+</ul>
+
+<h4>ACTION_NOTIFY</h4>
+
+<p>This response indicates that a purchase has changed state, which means a purchase succeeded, was canceled, or was refunded. This response contains one or more notification IDs. Each notification ID corresponds to a specific server-side message, and each messages contains information about one or more transactions. After your application receives an <code>ACTION_NOTIFY</code> broadcast intent, you send a <code>GET_PURCHASE_INFORMATION</code> request with the notification IDs to retrieve the message details.</p>
+
+<h5>Extras</h5>
+
+<ul type="none">
+ <li><code>NOTIFICATION_ID</code>—a string representing the notification ID for a given purchase state change. Android Market notifies you when there is a purchase state change and the notification includes a unique notification ID. To get the details of the purchase state change, you send the notification ID with the <code>GET_PURCHASE_INFORMATION</code> request.</li>
+</ul>
+
+<h4>ACTION_PURCHASE_STATE_CHANGED</h4>
+
+<p>This broadcast intent contains detailed information about one or more transactions. The transaction information is contained in a JSON string. The JSON string is signed and the signature is sent to your application along with the JSON string (unencrypted). To help ensure the security of your in-app billing messages, your application can verify the signature of this JSON string.</p>
+
+<h5>Extras</h5>
+
+<ul type="none">
+ <li><code>INAPP_SIGNED_DATA</code>—a string representing the signed JSON string.</li>
+ <li><code>INAPP_SIGNATURE</code>—a string representing the signature.</li>
+</ul>
\ No newline at end of file
diff --git a/docs/html/guide/market/billing/billing_testing.jd b/docs/html/guide/market/billing/billing_testing.jd
new file mode 100755
index 0000000..4a36588
--- /dev/null
+++ b/docs/html/guide/market/billing/billing_testing.jd
@@ -0,0 +1,180 @@
+page.title=Testing In-app Billing
+@jd:body
+
+<style type="text/css">
+ #jd-content {
+ background:transparent url({@docRoot}assets/images/preliminary.png) repeat scroll 0 0;
+ }
+</style>
+
+<div id="qv-wrapper">
+<div id="qv">
+ <h2>In this document</h2>
+ <ol>
+ <li><a href="#billing-testing-static">Testing in-app purchases with static responses</a></li>
+ <li><a href="#billing-testing-real">Testing in-app purchases using your own product IDs</a></li>
+
+ </ol>
+ <h2>Downloads</h2>
+ <ol>
+ <li><a href="{@docRoot}guide/market/billing/billing_integrate.html#billing-download">Sample Application</a></li>
+ </ol>
+ <h2>See also</h2>
+ <ol>
+ <li><a href="{@docRoot}guide/market/billing/billing_overview.html">Overview of In-app Billing</a></li>
+ <li><a href="{@docRoot}guide/market/billing/billing_integrate.html">Implementing In-app Billing</a></li>
+ <li><a href="{@docRoot}guide/market/billing/billing_best_practices.html">Security and Design</a></li>
+ <li><a href="{@docRoot}guide/market/billing/billing_admin.html">Administering In-app Billing</a></li>
+ <li><a href="{@docRoot}guide/market/billing/billing_reference.html">In-app Billing Reference</a></li>
+ </ol>
+</div>
+</div>
+
+<div class="special" style="margin-right:345px">
+ <p>This documentation provides an early look at the Android Market In-app Billing service. The documentation may change without notice.</p>
+</div>
+
+<p>The Android Market publisher site provides several tools that help you test your in-app billing implementation before it is published. You can use these tools to create test accounts and purchase special reserved items that send static billing responses to your application.</p>
+
+<p>To test in-app billing in an application you must install the application on an Android-powered device. You cannot use the Android emulator to test in-app billing. The device you use for testing must run a standard version of the Android 1.6 or later platform (API level 4 or higher), and have the most current version of the Android Market application installed. If a device is not running the most current Android Market application, your application won't be able to send in-app billing requests to Android Market. For general information about how to set up a device for use in developing Android applications, see <a
+href="{@docRoot}guide/developing/device.html">Developing on a Device</a>.</p>
+
+<p>The following section shows you how to set up and use the in-app billing test tools.</p>
+
+<p class="note"><strong>Note</strong>: Debug log messages are turned off by default in the sample application. You can turn them on by setting the variable <code>DEBUG</code> to <code>true</code> in the <code>Consts.java</code> file.</p>
+
+<h2 id="billing-testing-static">Testing in-app purchases with static responses</h2>
+
+<p>We recommend that you first test your in-app billing implementation using static responses from Android Market. This enables you to verify that your application is handling the primary Android Market responses correctly and that your application is able to verify the signature correctly.</p>
+
+<p>To test your implementation with static responses, you make an in-app billing request using a special item that has a reserved product ID. Each reserved product ID returns a specific static response from Android Market. No money is transferred when you make in-app billing requests with the reserved product IDs. Also, you cannot specify the form of payment when you make a billing request with a reserved product ID. Figure 1 shows the checkout flow for the reserved item that has the product ID android.test.purchased.</p>
+
+<div style="margin:2em 1em 1em 1em;">
+<img src="{@docRoot}images/billing_test_flow.png" style="text-align:left;" />
+<div style="margin:.25em 1.25em;padding:0"><strong>Figure 1.</strong> Checkout flow for the special reserved item android.test.purchased.</div>
+</div>
+
+<p>You do not need to list the reserved products in your application's product list. Android Market already knows about the reserved product IDs. Also, you do not need to upload your application to the publisher site to perform static response tests with the reserved product IDs. You can simply install your application on a device, log into the device, and make billing requests using the reserved product IDs.</p>
+
+<p>There are four reserved product IDs for testing static in-app billing responses:</p>
+
+<ul>
+ <li><strong>android.test.purchased</strong>
+ <p>When you make an in-app billing request with this product ID, Android Market responds as though you successfully purchased an item. The response includes a JSON string, which contains fake purchase information (for example, a fake order ID). In some cases, the JSON string is signed and the response includes the signature so you can test your signature verification implementation using these responses.</p>
+ </li>
+ <li><strong>android.test.canceled</strong>
+ <p>When you make an in-app billing request with this product ID Android Market responds as though the purchase was canceled. This can occur when an error is encountered in the order process, such as an invalid credit card, or when you cancel a user's order before it is charged.</p>
+ </li>
+ <li><strong>android.test.refunded</strong>
+ <p>When you make an in-app billing request with this product ID, Android Market responds as though the purchase was refunded. Refunds cannot be initiated through the in-app billing feature. Refunds must be initiated by you (the merchant). A refund message is sent to your app by Android Market only when Android Market gets notification from Google Checkout that a refund has been made.</p>
+ </li>
+ <li><strong>android.test.item_unavailable</strong>
+ <p>When you make an in-app billing request with this product ID Android Market responds as though the item being purchased was not listed in your app's product list.</p>
+ </li>
+</ul>
+
+<p>In some cases, the reserved items may return signed static responses, which lets you test signature verification in your application. To test signature verification with the special reserved product IDs, you may need to set up <a href="{@docRoot}guide/market/billing/billing_admin.html#billing-testing-setup">trusted tester accounts</a> or upload your application as a unpublished draft application. The following table (Table 1) shows you the conditions under which static responses are signed.</p>
+
+<p class="table-caption" id="static-responses-table"><strong>Table 1.</strong>
+Conditions under which static responses are signed.</p>
+
+<table>
+<tr>
+<th>Application ever been published?</th>
+<th>Draft application uploaded and unpublished?</th>
+<th>User who is running the application</th>
+<th>Static response signature</th>
+</tr>
+
+<tr>
+<td>No</td>
+<td>No</td>
+<td>Any</td>
+<td>Unsigned</td>
+</tr>
+
+<tr>
+<td>No</td>
+<td>No</td>
+<td>Developer</td>
+<td>Signed</td>
+</tr>
+
+<tr>
+<td>Yes</td>
+<td>No</td>
+<td>Any</td>
+<td>Unsigned</td>
+</tr>
+
+<tr>
+<td>Yes</td>
+<td>No</td>
+<td>Developer</td>
+<td>Signed</td>
+</tr>
+
+<tr>
+<td>Yes</td>
+<td>No</td>
+<td>Trusted tester</td>
+<td>Signed</td>
+</tr>
+
+<tr>
+<td>Yes</td>
+<td>Yes</td>
+<td>Any</td>
+<td>Signed</td>
+</tr>
+
+</table>
+
+<p>To make an in-app billing request with a reserved product ID, you simply construct a normal <code>REQUEST_PURCHASE</code> request, but instead of using a real product ID from your application's product list you use one of the reserved product IDs.</p>
+
+<p class="note"><strong>Note</strong>: Making in-app billing requests with the reserved product IDs overrides the usual Android Market production system. When you send an in-app billing request for a reserved product ID, the quality of service will not be comparable to the production environment.</p>
+
+<h2 id="billing-testing-real">Testing In-app Purchases Using Your Own Product IDs</h2>
+
+<p>After you finish your static response testing, and you verify that signature verification is working in your application, you can test your in-app billing implementation by making actual in-app purchases. Testing real in-app purchases enables you to test the end-to-end in-app billing experience, including the actual responses from Android Market and the actual checkout flow that users will experience in your application.</p>
+
+<p class="note"><strong>Note</strong>: You do not need to publish your application to do end-to-end testing. You only need to upload your draft application to perform end-to-end testing.</p>
+
+<p>To test your in-app billing implementation with actual in-app purchases, you will need to register at least one test account on the Android Market publisher site. You cannot use your developer account to test the complete in-app purchase process because Google Checkout does not let you buy items from yourself. If you have not set up test accounts before, see <a href="{@docRoot}guide/market/billing/billing_admin.html#billing-testing-setup">Setting up test accounts</a>.</p>
+
+<p>Also, a test account can purchase an item in your product list only if the item is published. The application does not need to be published, but the item does need to be published.</p>
+
+<p>When you use a test account to purchase items, the account is billed through Google Checkout and your Google Checkout merchant account receives a payout for the purchase. Therefore, you need to refund purchases that are made with test accounts, otherwise the purchases will show up as actual payouts to your merchant account.</p>
+
+<p>To test your in-app billing implementation with actual purchases, follow these steps:</p>
+
+<ol>
+ <li>Upload your application as a draft application to the publisher site. You do not need to publish your application to perform end-to-end testing with real product IDs.</li>
+ <li>Add items to the application's product list. Make sure that you publish the items (the application can remain unpublished).
+ <p>See <a href="{@docRoot}guide/market/billing/billing_admin.html#billing-catalog">Creating a product list</a> to learn how to do this.</p>
+ </li>
+ <li>Install your application on an Android-powered device.
+ <p>See <a href="{@docRoot}guide/developing/device.html">Developing on a Device</a> for more information about how to do this.</p>
+ </li>
+ <li>Sign in to the device using one of the <a href="{@docRoot}guide/market/billing/billing_admin.html#billing-testing-setup">trusted tester accounts</a> that you registered on the Android Market site.
+ <p>We recommend that you make the test account the primary account on the device. To sign in to a device, do the following:</p>
+ <ol>
+ <li>Open Settings > Accounts & sync</li>
+ <li>Select <strong>Add Account</strong> and choose to add a "Google" account.</li>
+ <li>Select <strong>Next</strong> and then <strong>Sign in</strong>.</li>
+ <li>Enter the username and password of the test account.</li>
+ <li>Select <strong>Sign in</strong>. The system signs you in to the new account.</li>
+ </ol>
+ </li>
+ <li>Make in-app purchases in your application.</li>
+</ol>
+
+<p class="note"><strong>Note:</strong> The only way to change the primary account on a device is to do a factory reset, making sure you log on with your primary account first.</p>
+
+<p>When you are finished testing your in-app billing implementation, you are ready to
+publish your application on Android Market. You can follow the normal steps for <a
+href="{@docRoot}guide/publishing/preparing.html">preparing</a>, <a
+href="{@docRoot}guide/publishing/app-signing.html">signing</a>, and <a
+href="{@docRoot}guide/publishing/publishing.html">publishing your application</a>.
+</p>
+
diff --git a/docs/html/guide/market/billing/index.jd b/docs/html/guide/market/billing/index.jd
new file mode 100755
index 0000000..f5d001d
--- /dev/null
+++ b/docs/html/guide/market/billing/index.jd
@@ -0,0 +1,67 @@
+page.title=Adding In-app Billing to Your Applications
+@jd:body
+
+<style type="text/css">
+ #jd-content {
+ background:transparent url({@docRoot}assets/images/preliminary.png) repeat scroll 0 0;
+ }
+</style>
+
+<div id="qv-wrapper">
+<div id="qv">
+
+ <h2>Topics</h2>
+ <ol>
+ <li><a href="{@docRoot}guide/market/billing/billing_overview.html">Overview of In-app Billing</a></li>
+ <li><a href="{@docRoot}guide/market/billing/billing_integrate.html">Implementing In-app Billing</a></li>
+ <li><a href="{@docRoot}guide/market/billing/billing_best_practices.html">Security and Design</a></li>
+ <li><a href="{@docRoot}guide/market/billing/billing_testing.html">Testing In-app Billing</a></li>
+ <li><a href="{@docRoot}guide/market/billing/billing_admin.html">Administering In-app Billing</a></li>
+ </ol>
+ <h2>Reference</h2>
+ <ol>
+ <li><a href="{@docRoot}guide/market/billing/billing_reference.html">In-app Billing Reference</a></li>
+ </ol>
+ <h2>Downloads</h2>
+ <ol>
+ <li><a href="{@docRoot}guide/market/billing/billing_integrate.html#billing-download">Sample Application</a></li>
+ </ol>
+</div>
+</div>
+
+<div class="special" style="margin-right:345px">
+ <p>This documentation provides an early look at the Android Market In-app Billing service. The documentation may change without notice.</p>
+</div>
+
+<p>In-app billing is an Android Market service that lets you sell digital content in your applications. You can use the service to sell a wide range of content, including downloadable content such as media files or photos, and virtual content such as game levels or potions.</p>
+
+<p>When you use the Android Market In-app Billing service to sell an item, Android Market handles all checkout details so your application never has to directly process any financial transactions. Android Market uses the same checkout service that is used for application purchases, so your users experience a consistent and familiar purchase flow (see figure 1). Also, the transaction fee for in-app purchases is the same as the transaction fee for application purchases (30%).</p>
+
+<p>Any application that you publish through Android Market can implement in-app billing. No special account or registration is required other than an Android Market publisher account and a Google Checkout merchant account. Also, because the service uses no dedicated framework APIs, you can add in-app billing to any application that uses a minimum API level of 4 or higher.</p>
+
+<p>To help you integrate in-app billing into your application, the Android SDK provides a sample application that demonstrates a simple implementation of in-app billing. The sample application contains examples of billing-related classes you can use to implement in-app billing in your application. It also contains examples of the database, user interface, and business logic you might use to implement in-app billing.</p>
+
+<p class="caution"><strong>Important</strong>: Although the sample application is a working example of how you can implement in-app billing, we <em>strongly recommend</em> that you modify and obfuscate the sample code before you use it in a production application. For more information, see <a href="{@docRoot}guide/market/billing/billing_best_practices.html">Security and Design</a>.</p>
+
+<div style="margin:2em 1em 1em 1em;">
+<img src="{@docRoot}images/billing_checkout_flow.png" style="text-align:left;" />
+<div style="margin:.25em 1.25em;padding:0"><strong>Figure 1.</strong> Applications initiate in-app billing requests through their own UI (first screen). Android Market responds to the request by providing the checkout user interface (middle screen). When checkout is complete, the application resumes.</div>
+</div>
+
+<p>To learn more about the in-app billing service and start integrating in-app billing into your applications, read the following documents:</p>
+
+<dl>
+ <dt><strong><a href="{@docRoot}guide/market/billing/billing_overview.html">Overview of In-app Billing</a></strong></dt>
+ <dd>Learn how the service works and what a typical in-app billing implementation looks like.</dd>
+ <dt><strong><a href="{@docRoot}guide/market/billing/billing_integrate.html">Implementing In-app Billing</a></strong></dt>
+ <dd>Use this step-by-step guide to start incorporating in-app billing into your application.</dd>
+ <dt><strong><a href="{@docRoot}guide/market/billing/billing_best_practices.html">Security and Design</a></strong></dt>
+ <dd>Review these best practices to help ensure that your in-app billing implementation is secure and well designed.</dd>
+ <dt><strong><a href="{@docRoot}guide/market/billing/billing_testing.html">Testing In-app Billing</a></strong></dt>
+ <dd>Understand how the in-app billing test tools work and learn how to test your in-app billing implementation.</dd>
+ <dt><strong><a href="{@docRoot}guide/market/billing/billing_admin.html">Administering In-app Billing</a></strong></dt>
+ <dd>Learn how to set up your product list, register test accounts, and handle refunds.</dd>
+ <dt><strong><a href="{@docRoot}guide/market/billing/billing_reference.html">In-app Billing Reference</a></strong></dt>
+ <dd>Get detailed information about Android Market response codes and the in-app billing interface.</dd>
+</dl>
+
diff --git a/docs/html/images/billing_arch.png b/docs/html/images/billing_arch.png
new file mode 100755
index 0000000..afbc3f0
--- /dev/null
+++ b/docs/html/images/billing_arch.png
Binary files differ
diff --git a/docs/html/images/billing_check_supported.png b/docs/html/images/billing_check_supported.png
new file mode 100755
index 0000000..d661f7f
--- /dev/null
+++ b/docs/html/images/billing_check_supported.png
Binary files differ
diff --git a/docs/html/images/billing_checkout_flow.png b/docs/html/images/billing_checkout_flow.png
new file mode 100755
index 0000000..5b446be
--- /dev/null
+++ b/docs/html/images/billing_checkout_flow.png
Binary files differ
diff --git a/docs/html/images/billing_list_form.png b/docs/html/images/billing_list_form.png
new file mode 100755
index 0000000..ee30de3
--- /dev/null
+++ b/docs/html/images/billing_list_form.png
Binary files differ
diff --git a/docs/html/images/billing_package.png b/docs/html/images/billing_package.png
new file mode 100755
index 0000000..ec04c2d
--- /dev/null
+++ b/docs/html/images/billing_package.png
Binary files differ
diff --git a/docs/html/images/billing_product_list.png b/docs/html/images/billing_product_list.png
new file mode 100755
index 0000000..5b8d174
--- /dev/null
+++ b/docs/html/images/billing_product_list.png
Binary files differ
diff --git a/docs/html/images/billing_public_key.png b/docs/html/images/billing_public_key.png
new file mode 100755
index 0000000..a0620f8
--- /dev/null
+++ b/docs/html/images/billing_public_key.png
Binary files differ
diff --git a/docs/html/images/billing_request_purchase.png b/docs/html/images/billing_request_purchase.png
new file mode 100755
index 0000000..e8a1b30
--- /dev/null
+++ b/docs/html/images/billing_request_purchase.png
Binary files differ
diff --git a/docs/html/images/billing_restore_transactions.png b/docs/html/images/billing_restore_transactions.png
new file mode 100755
index 0000000..116aa0e
--- /dev/null
+++ b/docs/html/images/billing_restore_transactions.png
Binary files differ
diff --git a/docs/html/images/billing_test_flow.png b/docs/html/images/billing_test_flow.png
new file mode 100755
index 0000000..9db8cd9
--- /dev/null
+++ b/docs/html/images/billing_test_flow.png
Binary files differ
