play/licensing/setting-up.jd

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 Google
Play 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 Google Play, you need to register for one
using your Google account and agree to the terms of service on the Google Play publisher site:</p>

<p style="margin-left:2em;"><a
href="http://play.google.com/apps/publish">http://play.google.com/apps/publish</a>
</p>

<p>For more information, see <a
href="{@docRoot}distribute/googleplay/publish/register.html">Get Started with Publishing</a>.</p>

<p>If you already have a publisher account on Google Play, use your existing
account to set up licensing.</p>

<p>Using your publisher account on Google Play, 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 Google Play 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/google/play/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
Google Play application and initiating a license check request. The Google
Play 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 Google Play 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 Google Play 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 Google Play client application
is preinstalled. </li>
</ul>

<p>If Google Play is not preinstalled in the system image, your application won't
be able to communicate with the Google Play licensing server. </p>

<p>For general information about how to set up a device for use in developing
Android applications, see <a
href="{@docRoot}tools/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 Google Play, 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 Google Play client.
However, it does provide: </p>

<ul>
<li>An Google Play 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 Google APIs add-on are available through the SDK Manager, but only
the version for Android 2.2 and higher includes the necessary Google
Play services.</p>

<p>To set up an emulator for adding licensing to an application, follow
these steps: </p>

<ol>
  <li>Launch the Android SDK Manager (available under the Eclipse <strong>Window</strong>
menu or by executing {@code &lt;sdk>/tools/android sdk}).</li>
  <li>Select and download <strong>Google APIs</strong> for the Android version you'd like to target
(must be Android 2.2 or higher).</li>
  <li>When the download is complete, open the AVD Manager (available under the Eclipse
<strong>Window</strong>
menu or by executing {@code &lt;sdk>/tools/android avd}).</li>
  <li>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 <strong>Google APIs</strong> 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}tools/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 package of the Android SDK. The
package 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 package into your development environment, use the
Android SDK Manager. Launch the Android SDK Manager and then
select the <strong>Google Market Licensing</strong> package, as shown in figure 2.
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 2.</strong> The 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 packess into your SDK, see the
<a href="{@docRoot}sdk/exploring.html">Exploring the SDK</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
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}tools/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}tools/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/google/play/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}tools/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 3.</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}tools/projects/projects-cmdline.html#SettingUpLibraryProject">
Setting up a Library Project</a>.</p>


<h2 id="test-env">Setting Up the Testing Environment</h2>

<p>The Google Play 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 Google Play
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>Google Play 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/google/play/licensing/licensing-reference.html#server-response-codes">Server
Response Codes</a> in the <a
href="{@docRoot}guide/google/play/licensing/licensing-reference.html">Licensing Reference</a>.</p>

<img src="{@docRoot}images/licensing_test_response.png" alt=""/>
<p class="img-caption"><strong>Figure 4.</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/google/play/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 Google Play 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 4, 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 Google
Play 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 Google Play 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/google/play/licensing/adding-licensing.html">Adding Licensing to Your App</a>.</p>