Android/frameworks_base
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

am 4143781c: docs: add docs for market OBB includes splitting the Licensing dev guide into multiple pages; Turned original licensing doc into a redirect to the new files that are under guide/market/licensing/; Fix all links pointing to app licensing

Browse Source 
* commit '4143781cdea0741ce6e87967c4ab903288c3e4c3':
  docs: add docs for market OBB includes splitting the Licensing dev guide into multiple pages; Turned original licensing doc into a redirect to the new files that are under guide/market/licensing/; Fix all links pointing to app licensing
This commit is contained in:
Scott Main
2012-03-02 16:40:00 -08:00
committed by Android Git Automerger
parent 3e72c93b16 4143781cde
commit 9ad705ce0b
16 changed files with 3825 additions and 2397 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
docs/html/guide/appendix/install-location.jd
View File

@@ -174,7 +174,7 @@ external storage, it can never receive this broadcast.</dd>
<dt>Copy Protection</dt> <dt>Copy Protection</dt>
<dd>Your application cannot be installed to a device's SD card if it uses Android Market's <dd>Your application cannot be installed to a device's SD card if it uses Android Market's
Copy Protection feature. However, if you use Android Market's Copy Protection feature. However, if you use Android Market's
<a href="{@docRoot}guide/publishing/licensing.html">Application Licensing</a> instead, your <a href="{@docRoot}guide/market/licensing/index.html">Application Licensing</a> instead, your
application <em>can</em> be installed to internal or external storage, including SD cards.</dd> application <em>can</em> be installed to internal or external storage, including SD cards.</dd>
</dl> </dl>

2
docs/html/guide/developing/tools/proguard.jd
View File

@@ -39,7 +39,7 @@ parent.link=index.html
sized <code>.apk</code> file that is more difficult to reverse engineer. Because ProGuard makes your sized <code>.apk</code> file that is more difficult to reverse engineer. Because ProGuard makes your
application harder to reverse engineer, it is important that you use it application harder to reverse engineer, it is important that you use it
when your application utilizes features that are sensitive to security like when you are when your application utilizes features that are sensitive to security like when you are
<a href="{@docRoot}guide/publishing/licensing.html">Licensing Your Applications</a>.</p> <a href="{@docRoot}guide/market/licensing/index.html">Licensing Your Applications</a>.</p>
<p>ProGuard is integrated into the Android build system, so you do not have to invoke it <p>ProGuard is integrated into the Android build system, so you do not have to invoke it
manually. ProGuard runs only when you build your application in release mode, so you do not manually. ProGuard runs only when you build your application in release mode, so you do not

22
docs/html/guide/guide_toc.cs
View File

@@ -451,8 +451,24 @@
<li><a href="<?cs var:toroot ?>guide/publishing/publishing.html"> <li><a href="<?cs var:toroot ?>guide/publishing/publishing.html">
<span class="en">Publishing on Android Market</span> <span class="en">Publishing on Android Market</span>
</a></li> </a></li>
<li><a href="<?cs var:toroot ?>guide/publishing/licensing.html"> <li class="toggle-list">
<div><a href="<?cs var:toroot ?>guide/market/licensing/index.html">
<span class="en">Application Licensing</span></a> <span class="en">Application Licensing</span></a>
</div>
<ul>
<li><a href="<?cs var:toroot?>guide/market/licensing/overview.html">
<span class="en">Licensing Overview</span></a>
</li>
<li><a href="<?cs var:toroot?>guide/market/licensing/setting-up.html">
<span class="en">Setting Up for Licensing</span></a>
</li>
<li><a href="<?cs var:toroot?>guide/market/licensing/adding-licensing.html">
<span class="en">Adding Licensing to Your App</span></a>
</li>
<li><a href="<?cs var:toroot?>guide/market/licensing/licensing-reference.html">
<span class="en">Licensing Reference</span></a>
</li>
</ul>
</li> </li>
<li class="toggle-list"> <li class="toggle-list">
<div><a href="<?cs var:toroot?>guide/market/billing/index.html"> <div><a href="<?cs var:toroot?>guide/market/billing/index.html">
@@ -485,6 +501,10 @@
<li><a href="<?cs var:toroot ?>guide/market/publishing/multiple-apks.html"> <li><a href="<?cs var:toroot ?>guide/market/publishing/multiple-apks.html">
<span class="en">Multiple APK Support</span></a> <span class="en">Multiple APK Support</span></a>
</li> </li>
<li><a href="<?cs var:toroot ?>guide/market/expansion-files.html">
<span class="en">APK Expansion Files</span></a>
<span class="new">new!</span>
</li>
</ul> </ul>
</li> </li>

1259
docs/html/guide/market/expansion-files.jd Normal file
View File

File diff suppressed because it is too large Load Diff

1072
docs/html/guide/market/licensing/adding-licensing.jd Normal file
View File

File diff suppressed because it is too large Load Diff

61
docs/html/guide/market/licensing/index.jd Normal file
View File

@@ -0,0 +1,61 @@
page.title=Application Licensing
@jd:body
<p>Android Market offers a licensing service that lets you enforce licensing policies for
applications that you publish on Android Market. With Android Market Licensing, your application can
query Android Market at run time to obtain the licensing status for the current user, then allow or
disallow further use as appropriate. </p>
<p>Using the service, you can apply a flexible licensing policy on an application-by-application
basis&mdash;each application can enforce licensing in the way most appropriate for it. If necessary,
an application can apply custom constraints based on the licensing status obtained from Android
Market. For example, an application can check the licensing status and then apply custom constraints
that allow the user to run it unlicensed for a specific validity period. An application can also
restrict use of the application to a specific device, in addition to any other constraints. </p>
<p>The licensing service is a secure means of controlling access to your applications. When an
application checks the licensing status, the Android Market server signs the licensing status
response using a key pair that is uniquely associated with the publisher account. Your application
stores the public key in its compiled <code>.apk</code> file and uses it to verify the licensing
status response.</p>
<p>Any application that you publish through Android Market can use the Android Market Licensing
service. No special account or registration is needed. Additionally, because the service uses no
dedicated framework APIs, you can add licensing to any application that uses a minimum API level of
3 or higher.</p>
<p class="note"><strong>Note:</strong> The Android Market Licensing service is primarily intended
for paid applications that wish to verify that the current user did in fact pay for the application
on Android Market. However, any application (including free apps) may use the licensing service
to initiate the download of an APK expansion file. In which case, the request that your application
sends to the licensing service is not to check whether the user paid for the app, but to request the
URL of the expansion files. For information about downloading expansion files for your application,
read the guide to <a href="{@docRoot}guide/market/expansion-files.html">APK Expansion Files</a>.</p>
<p>To learn more about Android Market's application licensing service and start integrating it into
your applications, read the following documents:</p>
<dl>
<dt><strong><a href="{@docRoot}guide/market/licensing/overview.html">Licensing
Overview</a></strong></dt>
<dd>Describes how the service works and what a typical licensing implementation looks
like.</dd>
<dt><strong><a href="{@docRoot}guide/market/licensing/setting-up.html">Setting Up for
Licensing</a></strong></dt>
<dd>Explains how to set up your Android Market account, development environment, and
testing environment in order to add licensing to your app.</dd>
<dt><strong><a href="{@docRoot}guide/market/licensing/adding-licensing.html">Adding
Licensing to Your App</a></strong></dt>
<dd>Provides a step-by-step guide to add licensing verification to your application.</dd>
<dt><strong><a href="{@docRoot}guide/market/licensing/licensing-reference.html">Licensing
Reference</a></strong></dt>
<dd>Provides detailed information about the licensing library's classes and the service response
codes.</dd>
</dl>

439
docs/html/guide/market/licensing/licensing-reference.jd Normal file
View File

@@ -0,0 +1,439 @@
page.title=Licensing Reference
parent.title=Application Licensing
parent.link=index.html
@jd:body
<div id="qv-wrapper">
<div id="qv">
<h2>In this document</h2>
<ol>
<li><a href="#lvl-summary">LVL Classes and Interfaces</a></li>
<li><a href="#server-response-codes">Server Response Codes</a></li>
<li><a href="#extras">Server Response Extras</a></li>
</ol>
</div>
</div>
<h2 id="lvl-summary">LVL Classes and Interfaces</h2>
<p>Table 1 lists all of the source files in the License Verification
Library (LVL) available through the Android SDK. All of the files are part of
the <code>com.android.vending.licensing</code> package.</p>
<p class="table-caption"><strong>Table 1.</strong> Summary of LVL library
classes and interfaces.</p>
<div style="width:99%">
<table width="100%">
<tr>
<th width="15%">Category</th>
<th width="20%">Name</th>
<th width="100%">Description</th>
</tr>
<tr>
<td rowspan="2">License check and result</td>
<td>LicenseChecker</td>
<td>Class that you instantiate (or subclass) to initiate a license check.</td>
</tr>
<tr>
<td><em>LicenseCheckerCallback</em></td>
<td>Interface that you implement to handle result of the license check.</td>
</tr>
<tr>
<td rowspan="3" width="15%">Policy</td>
<td width="20%"><em>Policy</em></td>
<td width="100%">Interface that you implement to determine whether to allow
access to the application, based on the license response. </td>
</tr>
<tr>
<td>ServerManagedPolicy</td>
<td width="100%">Default {@code Policy} implementation. Uses settings provided by the
licensing server to manage local storage of license data, license validity,
retry.</td>
</tr>
<tr>
<td>StrictPolicy</td>
<td>Alternative {@code Policy} implementation. Enforces licensing based on a direct
license response from the server only. No caching or request retry.</td>
</tr>
<tr>
<td rowspan="2" width="15%">Data obfuscation <br><em>(optional)</em></td>
<td width="20%"><em>Obfuscator</em></td>
<td width="100%">Interface that you implement if you are using a {@code Policy} (such as
ServerManagedPolicy) that caches license response data in a persistent store.
Applies an obfuscation algorithm to encode and decode data being written or
read.</td>
</tr>
<tr>
<td>AESObfuscator</td>
<td>Default Obfuscator implementation that uses AES encryption/decryption
algorithm to obfuscate/unobfuscate data.</td>
</tr>
<tr>
<td rowspan="2" width="15%">Device limitation<br><em>(optional)</em></td>
<td width="20%"><em>DeviceLimiter</em></td>
<td width="100%">Interface that you implement if you want to restrict use of an
application to a specific device. Called from LicenseValidator. Implementing
DeviceLimiter is not recommended for most applications because it requires a
backend server and may cause the user to lose access to licensed applications,
unless designed with care.</td>
</tr>
<tr>
<td>NullDeviceLimiter</td>
<td>Default DeviceLimiter implementation that is a no-op (allows access to all
devices).</td>
</tr>
<tr>
<td rowspan="6" width="15%">Library core, no integration needed</td>
<td width="20%">ResponseData</td>
<td width="100%">Class that holds the fields of a license response.</td>
</tr>
<tr>
<td>LicenseValidator</td>
<td>Class that decrypts and verifies a response received from the licensing
server.</td>
</tr>
<tr>
<td>ValidationException</td>
<td>Class that indicates errors that occur when validating the integrity of data
managed by an Obfuscator.</td>
</tr>
<tr>
<td>PreferenceObfuscator</td>
<td>Utility class that writes/reads obfuscated data to the system's
{@link android.content.SharedPreferences} store.</td>
</tr>
<tr>
<td><em>ILicensingService</em></td>
<td>One-way IPC interface over which a license check request is passed to the
Android Market client.</td>
</tr>
<tr>
<td><em>ILicenseResultListener</em></td>
<td>One-way IPC callback implementation over which the application receives an
asynchronous response from the licensing server.</td>
</tr>
</table>
</div>
<h2 id="server-response-codes">Server Response Codes</h2>
<p>Table 2 lists all of the license response codes supported by the
licensing server. In general, an application should handle all of these response
codes. By default, the LicenseValidator class in the LVL provides all of the
necessary handling of these response codes for you. </p>
<p class="table-caption"><strong>Table 2.</strong> Summary of response codes
returned by the Android Market server in a license response.</p>
<table>
<tr>
<th>Response Code</th>
<th>Description</th>
<th>Signed?</th>
<th>Extras</th>
<th>Comments</th>
</tr>
<tr>
<td>{@code LICENSED}</td>
<td>The application is licensed to the user. The user has purchased the
application or the application only exists as a draft.</td>
<td>Yes</td>
<td><code>VT</code>,&nbsp;<code>GT</code>, <code>GR</code></td>
<td><em>Allow access according to {@code Policy} constraints.</em></td>
</tr>
<tr>
<td>{@code LICENSED_OLD_KEY}</td>
<td>The application is licensed to the user, but there is an updated application
version available that is signed with a different key. </td>
<td>Yes </td>
<td><code>VT</code>, <code>GT</code>, <code>GR</code>, <code>UT</code></td>
<td><em>Optionally allow access according to {@code Policy} constraints.</em>
<p style="margin-top:.5em;">Can indicate that the key pair used by the installed
application version is invalid or compromised. The application can allow access
if needed or inform the user that an upgrade is available and limit further use
until upgrade.</p>
</td>
</tr>
<tr>
<td>{@code NOT_LICENSED}</td>
<td>The application is not licensed to the user.</td>
<td>No</td>
<td></td>
<td><em>Do not allow access.</em></td>
</tr>
<tr>
<td>{@code ERROR_CONTACTING_SERVER}</td>
<td>Local error &mdash; the Android Market application was not able to reach the
licensing server, possibly because of network availability problems. </td>
<td>No</td>
<td></td>
<td><em>Retry the license check according to {@code Policy} retry limits.</em></td>
</tr>
<tr>
<td>{@code ERROR_SERVER_FAILURE}</td>
<td>Server error &mdash; the server could not load the publisher account's key
pair for licensing.</td>
<td>No</td>
<td></td>
<td><em>Retry the license check according to {@code Policy} retry limits.</em>
</td>
</tr>
<tr>
<td>{@code ERROR_INVALID_PACKAGE_NAME}</td>
<td>Local error &mdash; the application requested a license check for a package
that is not installed on the device. </td>
<td>No </td>
<td></td>
<td><em>Do not retry the license check.</em>
<p style="margin-top:.5em;">Typically caused by a development error.</p>
</td>
</tr>
<tr>
<td>{@code ERROR_NON_MATCHING_UID}</td>
<td>Local error &mdash; the application requested a license check for a package
whose UID (package, user ID pair) does not match that of the requesting
application. </td>
<td>No </td>
<td></td>
<td><em>Do not retry the license check.</em>
<p style="margin-top:.5em;">Typically caused by a development error.</p>
</td>
</tr>
<tr>
<td>{@code ERROR_NOT_MARKET_MANAGED}</td>
<td>Server error &mdash; the application (package name) was not recognized by
Android Market. </td>
<td>No</td>
<td></td>
<td><em>Do not retry the license check.</em>
<p style="margin-top:.5em;">Can indicate that the application was not published
through Android Market or that there is an development error in the licensing
implementation.</p>
</td>
</tr>
</table>
<p class="note"><strong>Note:</strong> As documented in <a
href="{@docRoot}guide/market/licensing/setting-up.html#test-env">
Setting Up The Testing Environment</a>, the response code can be manually
overridden for the application developer and any registered test users via the
Android Market publisher site.
<br/><br/>
Additionally, as noted above, applications that are in draft mode (in other
words, applications that have been uploaded but have <em>never</em> been
published) will return {@code LICENSED} for all users, even if not listed as a test
user. Since the application has never been offered for download, it is assumed
that any users running it must have obtained it from an authorized channel for
testing purposes.</p>
<h2 id="extras">Server Response Extras</h2>
<p>To assist your application in managing access to the application across the application refund
period and provide other information, The licensing server includes several pieces of
information in the license responses. Specifically, the service provides recommended values for the
application's license validity period, retry grace period, maximum allowable retry count, and other
settings. If your application uses <a href="{@docRoot}guide/market/expansion-files.html">APK
expansion files</a>, the response also includes the file names, sizes, and URLs. The server appends
the settings as key-value pairs in the license response "extras" field. </p>
<p>Any {@code Policy} implementation can extract the extras settings from the license
response and use them as needed. The LVL default {@code Policy} implementation, <a
href="{@docRoot}guide/market/licensing/adding-licensing.html#ServerManagedPolicy">{@code
ServerManagedPolicy}</a>, serves as a working
implementation and an illustration of how to obtain, store, and use the
settings. </p>
<p class="table-caption"><strong>Table 3.</strong> Summary of
license-management settings supplied by the Android Market server in a license
response.</p>
<table>
<tr>
<th>Extra</th><th>Description</th>
</tr>
<tr>
<td>{@code VT}</td>
<td>License validity timestamp. Specifies the date/time at which the current
(cached) license response expires and must be rechecked on the licensing server. See the section
below about <a href="#VT">License validity period</a>.
</td>
</tr>
<tr>
<td>{@code GT}</td>
<td>Grace period timestamp. Specifies the end of the period during which a
Policy may allow access to the application, even though the response status is
{@code RETRY}. <p>The value is managed by the server, however a typical value would be 5
or more days. See the section
below about <a href="#GTGR">Retry period and maximum retry count</a>.</p></td>
</tr>
<tr>
<td>{@code GR}</td>
<td>Maximum retries count. Specifies how many consecutive {@code RETRY} license checks
the {@code Policy} should allow, before denying the user access to the application.
<p>The value is managed by the server, however a typical value would be "10" or
higher. See the section
below about <a href="#GTGR">Retry period and maximum retry count</a>.</p></td>
</tr>
<tr>
<td>{@code UT}</td>
<td>Update timestamp. Specifies the day/time when the most recent update to
this application was uploaded and published. <p>The server returns this extra
only for {@code LICENSED_OLD_KEYS} responses, to allow the {@code Policy} to determine how much
time has elapsed since an update was published with new licensing keys before
denying the user access to the application. </p></td>
</tr>
<!-- APK EXPANSION FILE RESPONSES -->
<tr>
<td>{@code FILE_URL1} or {@code FILE_URL2}</td>
<td>The URL for an expansion file (1 is for the main file, 2 is the patch file). Use this to
download the file over HTTP.</td>
</tr>
<tr>
<td>{@code FILE_NAME1} or {@code FILE_NAME2}</td>
<td>The expansion file's name (1 is for the main file, 2 is the patch file). You must use this
name when saving the file on the device.</td>
</tr>
<tr>
<td>{@code FILE_SIZE1} or {@code FILE_SIZE2}</td>
<td>The size of the file in bytes (1 is for the main file, 2 is the patch file). Use this to
assist with downloading and to ensure that enough space is available on the device's shared
storage location before downloading.</td>
</tr>
</table>
<h4 id="VT">License validity period</h4>
<p>The Android Market licensing server sets a license validity period for all
downloaded applications. The period expresses the interval of time over which an
application's license status should be considered as unchanging and cacheable by
a licensing {@code Policy} in the application. The licensing server includes the
validity period in its response to all license checks, appending an
end-of-validity timestamp to the response as an extra under the key {@code VT}. A
{@code Policy} can extract the VT key value and use it to conditionally allow access to
the application without rechecking the license, until the validity period
expires. </p>
<p>The license validity signals to a licensing {@code Policy} when it must recheck the
licensing status with the licensing server. It is <em>not</em> intended to imply
whether an application is actually licensed for use. That is, when an
application's license validity period expires, this does not mean that the
application is no longer licensed for use &mdash; rather, it indicates only that
the {@code Policy} must recheck the licensing status with the server. It follows that,
as long as the license validity period has not expired, it is acceptable for the
{@code Policy} to cache the initial license status locally and return the cached license
status instead of sending a new license check to the server.</p>
<p>The licensing server manages the validity period as a means of helping the
application properly enforce licensing across the refund period offered by
Android Market for paid applications. It sets the validity period based on
whether the application was purchased and, if so, how long ago. Specifically,
the server sets a validity period as follows:</p>
<ul>
<li>For a paid application, the server sets the initial license validity period
so that the license response remains valid for as long as the application is
refundable. A licensing {@code Policy} in the application may cache the
result of the initial license check and does not need to recheck the license
until the validity period has expired.</li>
<li>When an application is no longer refundable, the server
sets a longer validity period &mdash; typically a number of days. </li>
<!-- TODO: Verify the following behavior is still true w/ OBB: -->
<li>For a free application, the server sets the validity period to a very high
value (<code>long.MAX_VALUE</code>). This ensures that, provided the {@code Policy} has
cached the validity timestamp locally, it will not need to recheck the
license status of the application in the future.</li>
</ul>
<p>The {@code ServerManagedPolicy} implementation uses the extracted timestamp
(<code>mValidityTimestamp</code>) as a primary condition for determining whether
to recheck the license status with the server before allowing the user access to
the application. </p>
<h4 id="GTGR">Retry period and maximum retry count</h4>
<p>In some cases, system or network conditions can prevent an application's
license check from reaching the licensing server, or prevent the server's
response from reaching the Android Market client application. For example, the
user might launch an application when there is no cell network or data
connection available&mdash;such as when on an airplane&mdash;or when the
network connection is unstable or the cell signal is weak. </p>
<p>When network problems prevent or interrupt a license check, the Android
Market client notifies the application by returning a {@code RETRY} response code to
the {@code Policy}'s <code>processServerResponse()</code> method. In the case of system
problems, such as when the application is unable to bind with Android Market's
{@code ILicensingService} implementation, the {@code LicenseChecker} library itself calls the
Policy <code>processServerResonse()</code> method with a {@code RETRY} response code.
</p>
<p>In general, the {@code RETRY} response code is a signal to the application that an
error has occurred that has prevented a license check from completing.
<p>The Android Market server helps an application to manage licensing under
error conditions by setting a retry "grace period" and a recommended maximum
retries count. The server includes these values in all license check responses,
appending them as extras under the keys {@code GT} and {@code GR}. </p>
<p>The application {@code Policy} can extract the {@code GT} and {@code GR} extras and use them to
conditionally allow access to the application, as follows:</p>
<ul>
<li>For a license check that results in a {@code RETRY} response, the {@code Policy} should
cache the {@code RETRY} response code and increment a count of {@code RETRY} responses.</li>
<li>The {@code Policy} should allow the user to access the application, provided that
either the retry grace period is still active or the maximum retries count has
not been reached.</li>
</ul>
<p>The {@code ServerManagedPolicy} uses the server-supplied {@code GT} and {@code GR} values as
described above. The example below shows the conditional handling of the retry
responses in the <code>allow()</code> method. The count of {@code RETRY} responses is
maintained in the <code>processServerResponse()</code> method, not shown. </p>
<pre>
public boolean allowAccess() {
long ts = System.currentTimeMillis();
if (mLastResponse == LicenseResponse.LICENSED) {
// Check if the LICENSED response occurred within the validity timeout.
if (ts &lt;= mValidityTimestamp) {
// Cached LICENSED response is still valid.
return true;
}
} else if (mLastResponse == LicenseResponse.RETRY &amp;&amp;
ts &lt; mLastResponseTime + MILLIS_PER_MINUTE) {
// Only allow access if we are within the retry period or we haven't used up our
// max retries.
return (ts &lt;= mRetryUntil || mRetryCount &lt;= mMaxRetries);
}
return false;
}</pre>

245
docs/html/guide/market/licensing/overview.jd Normal file
View File

@@ -0,0 +1,245 @@
page.title=Licensing Overview
parent.title=Application Licensing
parent.link=index.html
@jd:body
<div id="qv-wrapper">
<div id="qv">
<h2>Quickview</h2>
<ul>
<li>Licensing allows you to verify your app was purchased from Android Market</li>
<li>Your app maintains control of how it enforces its licensing status</li>
<li>The service is free for all developers who publish on Android Market</li>
</ul>
<h2>In this document</h2>
<ol>
<li><a href="#Secure">License Responses are Secure</a></li>
<li><a href="#LVL">Licensing Verification Library</a></li>
<li><a href="#Reqs">Requirements and Limitations</a></li>
<li><a href="#CopyProtection">Replacement for Copy Protection</a></li>
</ol>
</div>
</div>
<p>Android Market Licensing is a network-based service that lets an application query a trusted
Android Market licensing server to determine whether the application is licensed to the current
device user. The licensing service is based on the capability of the Android Market licensing server
to determine whether a given user is licensed to use a given application. Android Market considers a
user to be licensed if the user is a recorded purchaser of the application.</p>
<p>The request starts when your application makes a request to a service hosted by
the Android Market client application. The Android Market application then sends a request to
the licensing server and receives the result. The Android Market application sends
the result to your application, which can allow or disallow further use of the
application as needed.</p>
<p class="note"><strong>Note:</strong> If a paid application has been uploaded to Android Market but
saved only as a draft application (the app is unpublished), the licensing server considers all users
to be licensed users of the application (because it's not even possible to purchase the app).
This exception is necessary in order for you to perform testing of your licensing
implementation.</p>
<div class="figure" style="width:469px">
<img src="{@docRoot}images/licensing_arch.png" alt=""/>
<p class="img-caption"><strong>Figure 1.</strong> Your application initiates a
license check through the License Verification Library and the Android Market
client, which handles communication with the Market server.</p>
</div>
<p>To properly identify the user and determine the license status, the licensing server requires
information about the application and user&mdash;your application and the Android Market client work
together to assemble the information and the Android Market client passes it to the server. </p>
<p>To help you add licensing to your application, the Android SDK provides a downloadable set of
library sources that you can include in your application project: the "Google Market Billing
package." The License Verification Library (LVL) is a library you can add to your application that
handles all of the licensing-related communication with the Android Market licensing service. With
the LVL added to your application, your application can determine its licensing status for the
current user by simply calling a method and implementing a callback that receives the status
response.</p>
<p>Your application does not query the licensing server
directly, but instead calls the Android Market client over remote IPC to
initiate a license request. In the license request:</p>
<ul>
<li>Your application provides: its package name, a nonce that is later used to
validate any response from the server, and a callback over which the
response can be returned asynchronously.</li>
<li>The Android Market client collects the necessary information about the user and the device,
such as the device's primary Google account username, IMSI, and other
information. It then sends the license check request to the server on behalf of
your application.</li>
<li>The Android Market server evaluates the request using all available information, attempting
to establish the user's identity to a sufficient level of confidence. The server
then checks the user identity against purchase records for your application and
returns a license response, which the Android Market client returns to your
application over the IPC callback.</li>
</ul>
<p>You can choose when, and how often, you want your application to check its
license and you have full control over how it handles the response, verifies the
signed response data, and enforces access controls.</p>
<p>Notice that during a license check, your application does not manage any
network connections or use any licensing related APIs in the Android platform.</p>
<h2 id="Secure">License Responses are Secure</h2>
<p>To ensure the integrity of each license query, the server signs the license
response data using an RSA key pair that is shared exclusively between the Android Market
server and you.</p>
<p>The licensing service generates a single licensing key pair for each
publisher account and exposes the public key in your account's profile page. You must copy the
public key from the web site and embed it in your application source code. The server retains the
private key internally and uses it to sign license responses for the applications you
publish with that account.</p>
<p>When your application receives a signed response, it uses the embedded public
key to verify the data. The use of public key cryptography in the licensing
service makes it possible for the application to detect responses that have been
tampered with or that are spoofed.</p>
<h2 id="LVL">Licensing Verification Library</h2>
<p>The Android SDK provides a downloadable component called the "Google Market Licensing package,"
which includes the License Verification Library (LVL). The LVL greatly simplifies the process of
adding licensing to your application and helps ensure a more secure, robust implementation for your
application. The LVL provides internal classes that handle most of the standard operations of a
license query, such as contacting the Android Market client to initiate a license request and
verifying and validating the responses. It also exposes interfaces that let you easily plug in your
custom code for defining licensing policy and managing access as needed by your application. The key
LVL interfaces are: </p>
<dl>
<dt>{@code Policy}</dt>
<dd>Your implementation determines whether to allow access to the
application, based on the license response received from the server and any
other data available (such as from a backend server associated with your
application). The implementation can evaluate the various fields of the license
response and apply other constraints, if needed. The implementation also lets
you manage the handling of license checks that result in errors, such as network
errors.</dd>
<dt>{@code LicenseCheckerCallback}</dt>
<dd>Your implementation manages access to the
application, based on the result of the {@code Policy} object's handling of the license
response. Your implementation can manage access in any way needed, including
displaying the license result in the UI or directing the user to purchase the
application (if not currently licensed).</dd>
</dl>
<p>To help you get started with a {@code Policy}, the LVL provides two fully complete
{@code Policy} implementations that you can use without modification or adapt to your
needs:</p>
<dl>
<dt><a href="adding-licensing.html#ServerManagedPolicy">{@code ServerManagedPolicy}</a></dt>
<dd>A flexible {@code Policy}
that uses settings provided by the licensing server to manage response caching
and access to the application while the device is offline (such as when the
user is on an airplane). For most applications, the use of
{@code ServerManagedPolicy} is highly recommended.</dd>
<dt><a href="adding-licensing.html#StrictPolicy">{@code StrictPolicy}</a></dt>
<dd>A restrictive {@code Policy} that
does not cache any response data and allows the application access <em>only</em>
when the server returns a licensed response.</dd>
</dl>
<p>The LVL is available as a downloadable component of the Android SDK. The
component includes both the LVL itself and an example application that shows how
the library should be integrated with your application and how your application
should manage response data, UI interaction, and error conditions. </p>
<p>The LVL sources are provided as an Android <em>library project</em>, which
means that you can maintain a single set of library sources and share them
across multiple applications. A full test environment is also available through
the SDK, so you can develop and test the licensing implementation in your
applications before publishing them, even if you don't have access to a
physical device.</p>
<h2 id="Reqs">Requirements and Limitations</h2>
<p>Android Market Licensing is designed to let you apply license controls to
applications that you publish through Android Market. The service is not
designed to let you control access to applications that are not published
through Android Market or that are run on devices that do not offer the Android
Market client. </p>
<p>Here are some points to keep in mind as you implement licensing in your
application: </p>
<ul>
<li>An application can use the service only if the Android Market client is
installed on its host device and the device is running Android 1.5 (API level 3)
or higher.</li>
<li>To complete a license check, the licensing server must be accessible over
the network. You can implement license caching behaviors to manage access to your application when
there is no network connectivity. </li>
<li>The security of your application's licensing controls ultimately relies on
the design of your implementation itself. The service provides the building
blocks that let you securely check licensing, but the actual enforcement and
handling of the license are factors are up to you. By following the best
practices in the following documents, you can help ensure that your implementation will be
secure.</li>
<li>Adding licensing to an application does not affect the way the application
functions when run on a device that does not offer Android Market.</li>
<li>You can implement licensing controls for a free app, but only if you're using the service to
provide <a
href="{@docRoot}guide/market/expansion-files.html">APK expansion files</a>.</li>
</ul>
<h2 id="CopyProtection">Replacement for Copy Protection</h2>
<p>Android Market Licensing is a flexible, secure mechanism for controlling
access to your applications. It effectively replaces the Copy Protection
mechanism offered on Android Market and gives you wider distribution
potential for your applications. </p>
<ul>
<li>A limitation of the legacy Copy Protection mechanism on Android Market is
that applications using it can be installed only on compatible devices that
provide a secure internal storage environment. For example, a copy-protected
application cannot be downloaded from Market to a device that provides root
access, and the application cannot be installed to a device's SD card. </li>
<li>With Android Market licensing, you can move to a license-based model in
which access is not bound to the characteristics of the host device, but to your
publisher account on Android Market and the licensing policy that you define.
Your application can be installed and controlled on any compatible device on
any storage, including SD card.</li>
</ul>
<p>Although no license mechanism can completely prevent all unauthorized use,
the licensing service lets you control access for most types of normal usage,
across all compatible devices, locked or unlocked, that run Android 1.5 or
higher version of the platform.</p>
<p>To begin adding application licensing to your application, continue to <a
href="{@docRoot}guide/market/licensing/setting-up.html">Setting Up for Licensing</a>.</p>

707
docs/html/guide/market/licensing/setting-up.jd Normal file
View File

@@ -0,0 +1,707 @@
page.title=Setting Up for Licensing
parent.title=Application Licensing
parent.link=index.html
@jd:body
<div id="qv-wrapper">
<div id="qv">
<h2>In this document</h2>
<ol>
<li><a href="#account">Setting Up a Publisher Account</a></li>
<li><a href="#dev-setup">Setting Up the Development Environment</a>
<ol>
<li><a href="#runtime-setup">Setting up the runtime environment</a></li>
<li><a href="#download-lvl">Downloading the LVL</a></li>
<li><a href="#lvl-setup">Setting Up the Licensing Verification Library</a></li>
<li><a href="#add-library">Including the LVL library project sources in your
application</a></li>
</ol>
</li>
<li><a href="#test-env">Setting Up the Testing Environment</a>
<ol>
<li><a href="#test-response">Setting test responses for license checks</a></li>
<li><a href="#test-acct-setup">Setting up test accounts</a></li>
<li><a href="#acct-signin">Signing in to an authorized account in the runtime
environment</a></li>
</ol>
</li>
</ol>
</div>
</div>
<p>Before you start adding license verification to your application, you need to set up your Android
Market publishing account, your development environment, and test accounts required to verify
your implementation.</p>
<h2 id="account">Setting Up a Publisher Account</h2>
<p>If you don't already have a publisher account for Android Market, you need to register for one
using your Google account and agree to the terms of service on the Android Market publisher site:</p>
<p style="margin-left:2em;"><a
href="http://market.android.com/publish">http://market.android.com/publish</a>
</p>
<p>For more information, see <a
href="{@docRoot}guide/publishing/publishing.html">Publishing on Android Market</a>.</p>
<p>If you already have a publisher account on Android Market, use your existing
account to set up licensing.</p>
<p>Using your publisher account on Android Market, you can:</p>
<ul>
<li>Obtain a public key for licensing</li>
<li>Debug and test an application's licensing implementation, prior to
publishing the application</li>
<li>Publish the applications to which you have added licensing support</li>
</ul>
<h4>Administrative settings for licensing</h4>
<p>You can manage several
administrative controls for Android Market licensing on the publisher site. The controls are available
in the Edit Profile page, in the "Licensing" panel, shown in figure 1. The controls
let you: </p>
<ul>
<li>Set up multiple "test accounts," identified by email address. The licensing
server allows users signed in to test accounts on a device or emulator to send
license checks and receive static test responses.</li>
<li>Obtain the account's public key for licensing. When you are implementing
licensing in an application, you must copy the public key string into the
application.</li>
<li>Configure static test responses that the server sends, when it receives a
license check for an application uploaded to the publisher account, from a user
signed in to the publisher account or a test account.</li>
</ul>
<img src="{@docRoot}images/licensing_public_key.png" alt=""/>
<p class="img-caption"><strong>Figure 1.</strong> The Licensing
panel of your account's Edit Profile page lets you manage administrative
settings for licensing.</p>
<p>For more information about how to work with test accounts and static test
responses, see <a href="#test-env">Setting Up a Testing Environment</a>, below.
<h2 id="dev-setup">Setting Up the Development Environment</h2>
<p>Setting up your environment for licensing involves these tasks:</p>
<ol>
<li><a href="#runtime-setup">Setting up the runtime environment</a> for development</li>
<li><a href="#download-lvl">Downloading the LVL</a> into your SDK </li>
<li><a href="#lvl-setup">Setting up the Licensing Verification Library</a></li>
<li><a href="#add-library">Including the LVL library project in your application</a></li>
</ol>
<p>The sections below describe these tasks. When you are done with setup,
you can begin <a href="{@docRoot}guide/market/licensing/adding-licensing.html">Adding
Licensing to Your App</a>.</p>
<p>To get started, you need to set up a proper runtime environment on which
you can run, debug, and test your application's implementation of license
checking and enforcement. </p>
<h3 id="runtime-setup">Setting up the runtime environment</h3>
<p>As described earlier, applications check licensing status not by contacting
the licensing server directly, but by binding to a service provided by the
Android Market application and initiating a license check request. The Android
Market service then handles the direct communication with the licensing server
and finally routes the response back to your application. To debug and test
licensing in your application, you need to set up a runtime environment that
includes the necessary Android Market service, so that your application is able
to send license check requests to the licensing server. </p>
<p>There are two types of runtime environment that you can use: </p>
<ul>
<li>An Android-powered device that includes the Android Market application, or</li>
<li>An Android emulator running the Google APIs Add-on, API level 8 (release 2)
or higher</li>
</ul>
<h4 id="runtime-device">Running on a device</h4>
<p>To use an Android-powered device for
debugging and testing licensing, the device must:</p>
<ul>
<li>Run a compatible version of Android 1.5 or later (API level
3 or higher) platform, <em>and</em> </li>
<li>Run a system image on which the Android Market client application
is preinstalled. </li>
</ul>
<p>If Android Market is not preinstalled in the system image, your application won't
be able to communicate with the Android Market licensing server. </p>
<p>For general information about how to set up a device for use in developing
Android applications, see <a
href="{@docRoot}guide/developing/device.html">Using Hardware Devices</a>.</p>
<h4 id="runtime-emulator">Running on an Android emulator</h4>
<p>If you don't have a device available, you can use an Android emulator for debugging and testing
licensing.</p>
<p>Because the Android platforms provided in the Android SDK <em>do
not</em> include Android Market, you need to download the Google APIs Add-On
platform, API level 8 (or higher), from the SDK repository. After downloading
the add-on, you need to create an AVD configuration that uses that system image.
</p>
<p>The Google APIs Add-On does not include the full Android Market client.
However, it does provide: </p>
<ul>
<li>An Android Market background service that implements the
<code>ILicensingService</code> remote interface, so that your application can
send license checks over the network to the licensing server. </li>
<li>A set of underlying account services that let you add an a Google account on
the AVD and sign in using your publisher account or test account credentials.
<p>Signing in using your publisher or test account enables you to debug and test
your application without having publish it. For more information see <a
href="#acct-signin">Signing in to an authorized account</a>, below.</p></li>
</ul>
<p>Several versions of the add-on are available through the SDK Manager, but only
<strong>Google APIs Add-On, API 8 (release 2) or higher</strong> includes the necessary Android
Market services.</p>
<img src="{@docRoot}images/licensing_gapis_8.png" alt=""/>
<p class="img-caption"><strong>Figure 2.</strong> Google APIs
Add-On, API 8 (release 2) or higher lets you debug and test your licensing
implementation in an emulator.</p>
<p>To set up an emulator for adding licensing to an application, follow
these steps: </p>
<ol>
<li>Launch the Android SDK Manager. </li>
<li>In the <strong>Available Packages</strong> panel, select and download the
SDK component "Google APIs (Google Inc.) - API Level 8" (or higher) from the SDK
repository, as shown in figure 2.
<p>When the download is complete, use the Android SDK Manager to
create a new AVD based on that component, described next.</p></li>
<li>In the <strong>Virtual
Devices</strong> panel of the Android SDK Manager, click
<strong>New</strong> and set the configuration details for the new AVD. </li>
<li>In the dialog that appears, assign a descriptive name to the AVD and then
use the "Target" menu to choose the "Google APIs (Google Inc.) - API Level 8" as
the system image to run on the new AVD. Set the other configuration details as
needed and then click <strong>Create AVD</strong> to finish. The SDK tools
create the new AVD configuration, which then appears in the list of available
Android Virtual Devices.</li>
</ol>
<p>If you are not familiar with AVDs or how to use them, see <a
href="{@docRoot}guide/developing/devices/index.html">Managing Virtual Devices</a>.</p>
<h4 id="project-update">Updating your project configuration</h4>
<p>After you set up a runtime environment that meets the requirements described
above &mdash; either on an actual device or on an emulator &mdash; make sure to
update your application project or build scripts as needed, so that your compiled
<code>.apk</code> files that use licensing are deployed into that environment.
In particular, if you are developing in Eclipse, make sure that you set up a
Run/Debug Configuration that targets the appropriate device or AVD. </p>
<p>You do not need to make any changes to your application's
build configuration, provided that the project is already configured to compile
against a standard Android 1.5 (API level 3) or higher library. For example:
<ul>
<li>If you have an existing application that is compiled against
the Android 1.5 library, you do not need to make any changes to your
build configuration to support licensing. The build target meets the minimum
requirements for licensing, so you would continue building
against the same version of the Android platform.</li>
<li>Similarly, if you are building against Android 1.5 (API level 3) but
are using an emulator running the Google APIs Add-On API 8 as the application's
runtime environment, there is no need to change your application's build
configuration. </li>
</ul>
<p>In general, adding licensing to an application should have no impact
whatsoever on the application's build configuration.</p>
<h3 id="download-lvl">Downloading the LVL</h3>
<p>The License Verification Library (LVL) is a collection of helper classes that
greatly simplify the work that you need to do to add licensing to your
application. In all cases, we recommend that you download the LVL and use it as
the basis for the licensing implementation in your application.</p>
<p>The LVL is available as a downloadable component of the Android SDK. The
component includes: </p>
<ul>
<li>The LVL sources, stored inside an Android library project. </li>
<li>An example application called "sample" that depends on the LVL library
project. The example illustrates how an application uses the library helper
classes to check and enforce licensing.</li>
</ul>
<p>To download the LVL component into your development environment, use the
Android SDK Manager. Launch the Android SDK Manager and then
select the "Market Licensing" component, as shown in figure 3.
Accept the terms and click <strong>Install Selected</strong> to begin the download. </p>
<img src="{@docRoot}images/licensing_package.png" alt=""/>
<p class="img-caption"><strong>Figure 3.</strong> The Market Licensing package contains the LVL and
the LVL sample application.</p>
<p>When the download is complete, the Android SDK Manager installs both
the LVL library project and the example application into these directories: </p>
<p style="margin-left:2em"><code>&lt;<em>sdk</em>&gt;/extras/google/market_licensing/library/</code>
&nbsp;&nbsp;(the LVL library project)<br />
<code>&lt;<em>sdk</em>&gt;/extras/google/market_licensing/sample/</code>&nbsp;&nbsp;(the example
application)</p>
<p>If you aren't familiar with how to download components into your SDK, see the
<a href="{@docRoot}sdk/adding-components.html">Adding SDK Components</a>
document. </p>
<h3 id="lvl-setup">Setting Up the Licensing Verification Library</h3>
<p>After downloading the LVL to your computer, you need to set it up in your
development environment, either as an Android library project or by
copying (or importing) the library sources directly into your existing
application package. In general, using the LVL as a library project is recommended,
since it lets you reuse your licensing code across multiple applications and
maintain it more easily over time. Note that the LVL is not designed to be
compiled separately and added to an application as a static .jar file. </p>
<h4>Moving the library sources to a new location</h4>
<p>Because you will be customizing the LVL sources to some extent, you should
make sure to <em>move or copy</em> the library sources (the entire
directory at <code>&lt;<em>sdk</em>&gt;/market_licensing/library/</code>)
to a working directory outside of the SDK. You should then use the relocated
sources as your working set. If you are using a source-code management
system, add and track the sources that are in the working location rather
than those in default location in the SDK. </p>
<p>Moving the library sources is important is because, when you later update the
Market licensing package, the SDK installs the new files to the same location as
the older files. Moving your working library files to a safe location ensures
that your work won't be inadvertently overwritten should you download a new
version of the LVL.</p>
<h4>Creating the LVL as a library project</h4>
<div class="sidebox-wrapper">
<div class="sidebox">
<h2>Working with library projects</h2>
<p>The LVL is provided as an Android library project, which means that you can
share its code and resources across multiple applications. </p>
<p style="margin-top:.5em;">If you aren't familiar with library projects or how
to use them, see <a href="{@docRoot}guide/developing/projects/index.html#LibraryProjects">
Managing Projects</a>.
</p>
</div>
</div>
<p>The recommended way of using the LVL is setting it up as a new Android
<em>library project</em>. A library project is a type of development project
that holds shared Android source code and resources. Other Android application
projects can reference the library project and, at build time, include its
compiled sources in their <code>.apk</code> files. In the context of licensing,
this means that you can do most of your licensing development once, in a library
project, then include the library sources in your various application projects.
In this way, you can easily maintain a uniform implementation of licensing
across all of your projects and maintain it centrally. </p>
<p>The LVL is provided as a configured library project &mdash; once you have
downloaded it, you can start using it right away. </p>
<p>If you are working in Eclipse with ADT, you need to add the LVL to your
workspace as a new development project, in the same way as you would a new
application project. </p>
<ol>
<li>Use the New Project Wizard to create a new
project from existing sources. Select the LVL's <code>library</code> directory
(the directory containing the library's AndroidManifest.xml file) as the project
root.</li>
<li>When you are creating the library project, you can select any application
name, package, and set other fields as needed. </li>
<li>For the library's build target, select Android 1.5 (API level 3) or higher.</li>
</ol>
<p> When created, the project is
predefined as a library project in its <code>project.properties</code> file, so
no further configuration is needed. </p>
<p>For more information about how to create an application project or work with
library projects in Eclipse, see <a
href="{@docRoot}guide/developing/projects/projects-eclipse.html">Managing Projects from
Eclipse with ADT</a>.</p>
<h4>Copying the LVL sources to your application</h4>
<p>As an alternative to adding the LVL as a library project, you can copy the
library sources directly into your application. To do so, copy (or import) the
LVL's <code>library/src/com</code> directory into your application's
<code>src/</code> directory.</p>
<p>If you add the LVL sources directly to your application, you can skip the
next section and start working with the library, as described in <a
href="{@docRoot}guide/market/licensing/adding-licensing.html">Adding
Licensing to Your App</a>.</p>
<h3 id="add-library">Including the LVL library project sources in your
application</h3>
<p>If you want to use the LVL sources as a library project, you need to add a
reference to the LVL library project in your application project properties. This tells
build tools to include the LVL library project sources in your application at
compile time. The process for adding a reference to a library project depends
on your development environment, as described below.</p>
<p> If you are developing in Eclipse with ADT, you should already have added the
library project to your workspace, as described in the previous section. If you
haven't done that already, do it now before continuing. </p>
<p>Next, open the application's project properties window, as shown below.
Select the "Android" properties group and click <strong>Add</strong>, then
choose the LVL library project (com_android_vending_licensing) and click
<strong>OK</strong>. For more information, see
<a href="{@docRoot}guide/developing/projects/projects-eclipse.html#SettingUpLibraryProject">
Managing Projects from Eclipse with ADT</a></p>.
<img src="{@docRoot}images/licensing_add_library.png" alt=""/>
<p class="img-caption"><strong>Figure 4.</strong> If you are
working in Eclipse with ADT, you can add the LVL library project to your
application from the application's project properties.</p>
<p>If you are developing using the SDK command-line tools, navigate to the
directory containing your application project and open the
<code>project.properties</code> file. Add a line to the file that specifies the
<code>android.library.reference.&lt;n&gt;</code> key and the path to the
library. For example: </p>
<pre>android.library.reference.1=path/to/library_project</pre>
<p>Alternatively, you can use this command to update the project
properties, including the reference to the library project:</p>
<pre class="no-pretty-print" style="color:black">android update lib-project
--target <em>&lt;target_ID&gt;</em> \
--path <em>path/to/my/app_project</em> \
--library <em>path/to/my/library_project</em>
</pre>
<p>For more information about working with library projects,
see <a href="{@docRoot}guide/developing/projects/projects-cmdline.html#SettingUpLibraryProject">
Setting up a Library Project</a>.</p>
<h2 id="test-env">Setting Up the Testing Environment</h2>
<p>The Android Market publisher site provides configuration tools that let you
and others test licensing on your application before it is published. As you are
implementing licensing, you can make use of the publisher site tools to test
your application's Policy and handling of different licensing responses and
error conditions.</p>
<p>The main components of the test environment for licensing include: </p>
<ul>
<li>A "Test response" configuration in your publisher account that lets you
set the static licensing response returned, when the server processes a
license check for an application uploaded to the publisher account, from a user
signed in to the publisher account or a test account.</li>
<li>An optional set of test accounts that will receive the static test
response when they check the license of an application that you have uploaded
(regardless whether the application is published or not).</li>
<li>A runtime environment for the application that includes the Android Market
application or Google APIs Add-On, on which the user is signed in to the
publisher account or one of the test accounts.</li>
</ul>
<p>Setting up the test environment properly involves:</p>
<ol>
<li><a href="#test-response">Setting static test responses</a> that are returned by the licensing server.</li>
<li><a href="#test-acct-setup">Setting up test accounts</a> as needed.</li>
<li><a href="#acct-signin">Signing in</a> properly to an emulator or device, before initiating a license check test.</li>
</ol>
<p>The sections below provide more information.</p>
<h3 id="test-response">Setting test responses for license checks</h3>
<p>Android Market provides a configuration setting in your publisher account
that lets you override the normal processing of a license check and return a
specified static response code. The setting is for testing only and applies
<em>only</em> to license checks for applications that you have uploaded, made by
any user signed in to an emulator or device using the credentials of the
publisher account or a registered test account. For other users, the server
always processes license checks according to normal rules. </p>
<p>To set a test response for your account, sign in to your publisher account
and click "Edit Profile". In the Edit Profile page, locate the Test Response
menu in the Licensing panel, shown below. You can select from the full set of
valid server response codes to control the response or condition you want to
test in your application.</p>
<p>In general, you should make sure to test your application's licensing
implementation with every response code available in the Test Response menu.
For a description of the codes, see <a
href="{@docRoot}guide/market/licensing/licensing-reference.html#server-response-codes">Server
Response Codes</a> in the <a
href="{@docRoot}guide/market/licensing/licensing-reference.html">Licensing Reference</a>.</p>
<img src="{@docRoot}images/licensing_test_response.png" alt=""/>
<p class="img-caption"><strong>Figure 5.</strong> The Licensing
panel of your account's Edit Profile page, showing the Test Accounts field and the
Test Response menu.</p>
<p>Note that the test response that you configure applies account-wide &mdash;
that is, it applies not to a single application, but to <em>all</em>
applications associated with the publisher account. If you are testing multiple
applications at once, changing the test response will affect all of those
applications on their next license check (if the user is signed in to
the emulator or device using the publisher account or a test account).</p>
<p>Before you can successfully receive a test response for a license check,
you must sign in to the device or emulator on which the application
is installed, and from which it is querying the server. Specifically, you must
sign using either your publisher account or one of the test accounts that you
have set up. For more information about test accounts, see the next section.</p>
<p>See <a
href="{@docRoot}guide/market/licensing/licensing-reference.html#server-response-codes">Server
Response Codes</a> for a list of
test responses available and their meanings. </p>
<h3 id="test-acct-setup">Setting up test accounts</h3>
<p>In some cases, you might want to let multiple teams of developers test
licensing on applications that will ultimately be published through your
publisher account, but without giving them access to your publisher account's
sign-in credentials. To meet that need, the Android Market publisher site lets
you set up one or more optional <em>test accounts</em> &mdash; accounts that are
authorized to query the licensing server and receive static test responses from
your publisher account.</p>
<p>Test accounts are standard Google accounts that you register on your
publisher account, such that they will receive the test response for
applications that you have uploaded. Developers can then sign in to their
devices or emulators using the test account credentials and initiate license
checks from installed applications. When the licensing server receives a license
check from a user of a test account, it returns the static test response
configured for the publisher account. </p>
<p>Necessarily, there are limitations on the access and permissions given to
users signed in through test accounts, including:</p>
<ul>
<li>Test account users can query the licensing server only for applications that
are already uploaded to the publisher account. </li>
<li>Test account users do not have permission to upload applications to your
publisher account.</li>
<li>Test account users do not have permission to set the publisher account's
static test response.</li>
</ul>
<p>The table below summarizes the differences in capabilities, between the
publisher account, a test account, and any other account.</p>
<p class="table-caption" id="acct-types-table"><strong>Table 1.</strong>
Differences in account types for testing licensing.</p>
<table>
<tr>
<th>Account Type</th>
<th>Can check license before upload?</th>
<th>Can receive test response?</th>
<th>Can set test response?</th>
</tr>
<tr>
<td>Publisher account</td>
<td>Yes</td>
<td>Yes</td>
<td>Yes</td>
</tr>
<tr>
<td>Test account</td>
<td>No</td>
<td>Yes</td>
<td>No</td>
</tr>
<tr>
<td>Other</td>
<td>No</td>
<td>No</td>
<td>No</td>
</tr>
</table>
<h4 id="reg-test-acct">Registering test accounts on the publisher account</h4>
<p>To get started, you need to register each test account in your publisher
account. As shown in Figure 5, you
register test accounts in the Licensing panel of your publisher account's Edit
Profile page. Simply enter the accounts as a comma-delimited list and click
<strong>Save</strong> to save your profile changes.</p>
<p>You can use any Google account as a test account. 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>
<h4 id="test-app-upload">Handling application upload and distribution for test
account users</h4>
<p>As mentioned above, users of test accounts can only receive static test
responses for applications that are uploaded to the publisher account. Since
those users do not have permission to upload applications, as the publisher you
will need to work with those users to collect apps for upload and distribute
uploaded apps for testing. You can handle collection and distribution in any way
that is convenient. </p>
<p>Once an application is uploaded and becomes known to the licensing server,
developers and testers can continue modify the application in their local
development environment, without having to upload new versions. You only need to
upload a new version if the local application increments the
<code>versionCode</code> attribute in the manifest file. </p>
<h4 id="test-key">Distributing your public key to test account users</h4>
<p>The licensing server handles static test responses in the normal way,
including signing the license response data, adding extras parameters, and so
on. To support developers who are implementing licensing using test accounts,
rather than the publisher account, you will need to distribute
your public key to them. Developers without access to the publisher site do not
have access to your public key, and without the key they won't be able to
verify license responses. </p>
<p>Note that if you decide to generate a new licensing key pair for your account
for some reason, you need to notify all users of test accounts. For
testers, you can embed the new key in the application package and distribute it
to users. For developers, you will need to distribute the new key to them
directly. </p>
<h3 id="acct-signin">Signing in to an authorized account in the runtime
environment</h3>
<p>The licensing service is designed to determine whether a given user is
licensed to use a given application &mdash; during a license check, the Android
Market application gathers the user ID from the primary account on the system
and sends it to the server, together with the package name of the application
and other information. However, if there is no user information available, the
license check cannot succeed, so the Android Market application terminates the
request and returns an error to the application. </p>
<p>During testing, to ensure that your application can successfully query the
licensing server, you must make sure that you sign in to an account <em>on the
device or emulator</em> using:</p>
<ul>
<li>The credentials of a publisher account, or</li>
<li>The credentials of a test account that is registered with a publisher
account</li>
</ul>
<div class="sidebox-wrapper">
<div class="sidebox">
<h2>Signing in to a Google account on an emulator</h2>
<p>If you are testing licensing on an emulator, you need to sign in to a Google
account on the emulator. If you do not see an option to create a new Google
account, the problem might be that your AVD is running a standard Android system
image, rather than the Google APIs Add-On, API 8 (release 2) or higher. </p>
<p style="margin-top:.5em;">For more information, see <a
href="#runtime-setup">Setting up the runtime environment</a>, above.</p>
</div>
</div>
<p>Signing in using a publisher account offers the advantage of letting your
applications receive static test responses even before the applications are
uploaded to the publisher site.</p>
<p>If you are part of a larger organization or are working with external groups
on applications that will be published through your site, you will more likely
want to distribute test accounts instead, then use those to sign in during
testing. </p>
<p>To sign in on a device or emulator, follow the steps below. The preferred
approach is to sign in as the primary account &mdash; however, if there are
other accounts already in use on the device or emulator, you can create an
additional account and sign in to it using the publisher or test account
credentials. </p>
<ol>
<li>Open Settings &gt; Accounts &amp; 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 either the publisher account or a test
account that is registered in the publisher account.</li>
<li>Select <strong>Sign in</strong>. The system signs you in to the new
account.</li>
</ol>
<p>Once you are signed in, you can begin testing licensing in your application
(if you have completed the LVL integration steps above). When your application
initiates a license check, it will receive a response containing the static test
response configured on the publisher account. </p>
<p>Note that, if you are using an emulator, you will need to sign in to the
publisher account or test account each time you wipe data when restarting the
emulator.</p>
<p>Once you've completed the setup procedures, continue to <a
href="{@docRoot}guide/market/licensing/adding-licensing.html">Adding Licensing to Your App</a>.</p>

11
docs/html/guide/publishing/licensing.html Normal file
View File

@@ -0,0 +1,11 @@
<html>
<head>
<meta http-equiv="refresh"
content="0;url=http://developer.android.com/guide/market/licensing/index.html">
<title>Redirecting...</title>
</head>
<body>
<p>You should have been redirected. Please <a
href="http://developer.android.com/guide/market/licensing/index.html">click here</a>.</p>
</body>
</html>

2388
docs/html/guide/publishing/licensing.jd
View File

File diff suppressed because it is too large Load Diff

3
docs/html/guide/publishing/preparing.jd
View File

@@ -291,7 +291,8 @@ current user has purchased it. Using Android Market Licensing is optional even i
releasing your app through Android Market.</p> releasing your app through Android Market.</p>
<p>For more information about Android Market Licensing Service and how to use it in your <p>For more information about Android Market Licensing Service and how to use it in your
application, see <a href="{@docRoot}guide/publishing/licensing.html">Application Licensing</a>.</p> application, see <a href="{@docRoot}guide/market/licensing/index.html">Application
Licensing</a>.</p>
<h2 id="publishing-build">Building Your Application for Release</h2> <h2 id="publishing-build">Building Your Application for Release</h2>

4
docs/html/guide/publishing/publishing.jd
View File

@@ -74,7 +74,7 @@ Android Market you have access to a suite of developer tools that let you analyz
identify market trends, and control who your applications are being distributed to. You also have identify market trends, and control who your applications are being distributed to. You also have
access to several revenue-enhancing features, such as <a access to several revenue-enhancing features, such as <a
href="{@docRoot}guide/market/billing/index.html">in-app billing</a> and href="{@docRoot}guide/market/billing/index.html">in-app billing</a> and
<a href="{@docRoot}guide/publishing/licensing.html">application licensing</a>.</p> <a href="{@docRoot}guide/market/licensing/index.html">application licensing</a>.</p>
<p>Before you can publish applications on Android Market, you need to <a <p>Before you can publish applications on Android Market, you need to <a
href="http://market.android.com/publish">register</a> as an Android Market developer. During the href="http://market.android.com/publish">register</a> as an Android Market developer. During the
@@ -254,7 +254,7 @@ higher.</p>
<p>For complete information about Android Market Licensing Service and how to <p>For complete information about Android Market Licensing Service and how to
use it in your application, read <a use it in your application, read <a
href="{@docRoot}guide/publishing/licensing.html">Application Licensing</a>.</p> href="{@docRoot}guide/market/licensing/index.html">Application Licensing</a>.</p>
<h2 id="marketinappbilling">Using Android Market In-app Billing</h2> <h2 id="marketinappbilling">Using Android Market In-app Billing</h2>

3
docs/html/guide/publishing/publishing_overview.jd
View File

@@ -130,7 +130,8 @@ Android Market you have access to a suite of developer tools that let you analyz
identify market trends, and control who your applications are being distributed to. You also have identify market trends, and control who your applications are being distributed to. You also have
access to several revenue-enhancing features that are not available anywhere else, such as <a access to several revenue-enhancing features that are not available anywhere else, such as <a
href="{@docRoot}guide/market/billing/index.html">in-app billing</a> and <a href="{@docRoot}guide/market/billing/index.html">in-app billing</a> and <a
href="{@docRoot}guide/publishing/licensing.html">application licensing</a>. This rich array of tools href="{@docRoot}guide/market/licensing/index.html">application licensing</a>. This rich array of
tools
and features, coupled with numerous end-user community features, makes Android Market the premier and features, coupled with numerous end-user community features, makes Android Market the premier
marketplace for selling and buying Android applications.</p> marketplace for selling and buying Android applications.</p>

2
docs/html/guide/topics/manifest/manifest-element.jd
View File

@@ -152,7 +152,7 @@ either internal or external storage through the system settings.</td>
<p class="caution"><strong>Caution:</strong> If your application uses the Android Market's Copy <p class="caution"><strong>Caution:</strong> If your application uses the Android Market's Copy
Protection feature, it cannot be installed to a device's SD card. However, if you use Android Protection feature, it cannot be installed to a device's SD card. However, if you use Android
Market's <a href="{@docRoot}guide/publishing/licensing.html">Application Licensing</a> instead, Market's <a href="{@docRoot}guide/market/licensing/index.html">Application Licensing</a> instead,
your application <em>can</em> be installed to internal or external storage, including SD cards.</p> your application <em>can</em> be installed to internal or external storage, including SD cards.</p>
<p class="note"><strong>Note:</strong> By default, your application will be installed on the <p class="note"><strong>Note:</strong> By default, your application will be installed on the

2
docs/html/sitemap.txt
View File

@@ -108,7 +108,7 @@ http://developer.android.com/guide/topics/testing/activity_testing.html
http://developer.android.com/guide/topics/testing/contentprovider_testing.html http://developer.android.com/guide/topics/testing/contentprovider_testing.html
http://developer.android.com/guide/topics/testing/service_testing.html http://developer.android.com/guide/topics/testing/service_testing.html
http://developer.android.com/guide/topics/testing/what_to_test.html http://developer.android.com/guide/topics/testing/what_to_test.html
http://developer.android.com/guide/publishing/licensing.html http://developer.android.com/guide/market/licensing/index.html
http://developer.android.com/guide/market/billing/index.html http://developer.android.com/guide/market/billing/index.html
http://developer.android.com/guide/market/billing/billing_about.html http://developer.android.com/guide/market/billing/billing_about.html
http://developer.android.com/guide/market/billing/billing_overview.html http://developer.android.com/guide/market/billing/billing_overview.html