From 6519ca0c5f8748e49b629ab482b4c8c3882adccb Mon Sep 17 00:00:00 2001 From: Robert Ly Date: Wed, 14 Nov 2012 13:26:28 -0800 Subject: docs: add new GMS landing and reference Change-Id: I48c75dd5924bdf297b5368887084d148efcd66ba --- docs/html/google/play/licensing/setting-up.jd | 701 ++++++++++++++++++++++++++ 1 file changed, 701 insertions(+) create mode 100644 docs/html/google/play/licensing/setting-up.jd (limited to 'docs/html/google/play/licensing/setting-up.jd') diff --git a/docs/html/google/play/licensing/setting-up.jd b/docs/html/google/play/licensing/setting-up.jd new file mode 100644 index 0000000..80a4419 --- /dev/null +++ b/docs/html/google/play/licensing/setting-up.jd @@ -0,0 +1,701 @@ +page.title=Setting Up for Licensing +parent.title=Application Licensing +parent.link=index.html +@jd:body + + +
+ +
+ +

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.

+ + +

Setting Up a Publisher Account

+ +

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:

+ +

http://play.google.com/apps/publish +

+ +

For more information, see Get Started with Publishing.

+ +

If you already have a publisher account on Google Play, use your existing +account to set up licensing.

+ +

Using your publisher account on Google Play, you can:

+ + + +

Administrative settings for licensing

+ +

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:

+ + + + + +

Figure 1. The Licensing +panel of your account's Edit Profile page lets you manage administrative +settings for licensing.

+ +

For more information about how to work with test accounts and static test +responses, see Setting Up a Testing Environment, below. + + + +

Setting Up the Development Environment

+ +

Setting up your environment for licensing involves these tasks:

+ +
    +
  1. Setting up the runtime environment for development
    2. +
  2. Downloading the LVL into your SDK
    3. +
  3. Setting up the Licensing Verification Library
    4. +
  4. Including the LVL library project in your application
    5. +
+ +

The sections below describe these tasks. When you are done with setup, +you can begin Adding +Licensing to Your App.

+ +

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.

+ + +

Setting up the runtime environment

+ +

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.

+ +

There are two types of runtime environment that you can use:

+ + + +

Running on a device

+ +

To use an Android-powered device for +debugging and testing licensing, the device must:

+ + + +

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

+ +

For general information about how to set up a device for use in developing +Android applications, see Using Hardware Devices.

+ +

Running on an Android emulator

+ +

If you don't have a device available, you can use an Android emulator for debugging and testing +licensing.

+ +

Because the Android platforms provided in the Android SDK do +not 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. +

+ +

The Google APIs Add-On does not include the full Google Play client. +However, it does provide:

+ + + +

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.

+ +

To set up an emulator for adding licensing to an application, follow +these steps:

+ +
    +
  1. Launch the Android SDK Manager (available under the Eclipse Window +menu or by executing {@code <sdk>/tools/android sdk}).
    2. +
  2. Select and download Google APIs for the Android version you'd like to target +(must be Android 2.2 or higher).
    3. +
  3. When the download is complete, open the AVD Manager (available under the Eclipse +Window +menu or by executing {@code <sdk>/tools/android avd}).
    4. +
  4. Click +New and set the configuration details for the new AVD.
    5. +
  5. In the dialog that appears, assign a descriptive name to the AVD and then +use the Target menu to choose the Google APIs as +the system image to run on the new AVD. Set the other configuration details as +needed and then click Create AVD to finish. The SDK tools +create the new AVD configuration, which then appears in the list of available +Android Virtual Devices.
    6. +
+ +

If you are not familiar with AVDs or how to use them, see Managing Virtual Devices.

+ +

Updating your project configuration

+ +

After you set up a runtime environment that meets the requirements described +above — either on an actual device or on an emulator — make sure to +update your application project or build scripts as needed, so that your compiled +.apk 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.

+ +

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: + +

+ +

In general, adding licensing to an application should have no impact +whatsoever on the application's build configuration.

+ + +

Downloading the LVL

+ +

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.

+ +

The LVL is available as a downloadable package of the Android SDK. The +package includes:

+ + + +

To download the LVL package into your development environment, use the +Android SDK Manager. Launch the Android SDK Manager and then +select the Google Market Licensing package, as shown in figure 2. +Accept the terms and click Install Selected to begin the download.

+ + +

Figure 2. The Licensing package contains the LVL and +the LVL sample application.

+ +

When the download is complete, the Android SDK Manager installs both +the LVL library project and the example application into these directories:

+ +

<sdk>/extras/google/market_licensing/library/ +  (the LVL library project)
+<sdk>/extras/google/market_licensing/sample/  (the example +application)

+ +

If you aren't familiar with how to download packess into your SDK, see the +Exploring the SDK +document.

+ + +

Setting Up the Licensing Verification Library

+ +

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.

+ +

Moving the library sources to a new location

+ +

Because you will be customizing the LVL sources to some extent, you should +make sure to move or copy the library sources (the entire +directory at <sdk>/market_licensing/library/) +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.

+ +

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.

+ +

Creating the LVL as a library project

+ +
+
+

Working with library projects

+ +

The LVL is provided as an Android library project, which means that you can +share its code and resources across multiple applications.

+ +

If you aren't familiar with library projects or how +to use them, see +Managing Projects. +

+
+
+ +

The recommended way of using the LVL is setting it up as a new Android +library project. 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 .apk 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.

+ +

The LVL is provided as a configured library project — once you have +downloaded it, you can start using it right away.

+ +

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.

+ +
    +
  1. Use the New Project Wizard to create a new +project from existing sources. Select the LVL's library directory +(the directory containing the library's AndroidManifest.xml file) as the project +root.
    2. +
  2. When you are creating the library project, you can select any application +name, package, and set other fields as needed.
    3. +
  3. For the library's build target, select Android 1.5 (API level 3) or higher.
    4. +
+ +

When created, the project is +predefined as a library project in its project.properties file, so +no further configuration is needed.

+ +

For more information about how to create an application project or work with +library projects in Eclipse, see Managing Projects from +Eclipse with ADT.

+ + +

Copying the LVL sources to your application

+ +

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 library/src/com directory into your application's +src/ directory.

+ +

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 Adding +Licensing to Your App.

+ + +

Including the LVL library project sources in your +application

+ +

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.

+ +

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.

+ +

Next, open the application's project properties window, as shown below. +Select the "Android" properties group and click Add, then +choose the LVL library project (com_android_vending_licensing) and click +OK. For more information, see + +Managing Projects from Eclipse with ADT

. + + + +

Figure 3. If you are +working in Eclipse with ADT, you can add the LVL library project to your +application from the application's project properties.

+ + +

If you are developing using the SDK command-line tools, navigate to the +directory containing your application project and open the +project.properties file. Add a line to the file that specifies the +android.library.reference.<n> key and the path to the +library. For example:

+ +
android.library.reference.1=path/to/library_project
+ +

Alternatively, you can use this command to update the project +properties, including the reference to the library project:

+ +
android update lib-project
+--target <target_ID> \
+--path path/to/my/app_project \
+--library path/to/my/library_project
+
+ +

For more information about working with library projects, +see +Setting up a Library Project.

+ + + + + + + + + + + + + + + + + + + + + +

Setting Up the Testing Environment

+ +

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.

+ +

The main components of the test environment for licensing include:

+ + + +

Setting up the test environment properly involves:

+ +
    +
  1. Setting static test responses that are returned by the licensing server.
    2. +
  2. Setting up test accounts as needed.
    3. +
  3. Signing in properly to an emulator or device, before initiating a license check test.
    4. +
+ +

The sections below provide more information.

+ + +

Setting test responses for license checks

+ +

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 +only 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.

+ +

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.

+ +

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 Server +Response Codes in the Licensing Reference.

+ + +

Figure 4. The Licensing +panel of your account's Edit Profile page, showing the Test Accounts field and the +Test Response menu.

+ +

Note that the test response that you configure applies account-wide — +that is, it applies not to a single application, but to all +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).

+ +

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.

+ +

See Server +Response Codes for a list of +test responses available and their meanings.

+ + +

Setting up test accounts

+ +

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 test accounts — accounts that are +authorized to query the licensing server and receive static test responses from +your publisher account.

+ +

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.

+ +

Necessarily, there are limitations on the access and permissions given to +users signed in through test accounts, including:

+ + + +

The table below summarizes the differences in capabilities, between the +publisher account, a test account, and any other account.

+ +

Table 1. +Differences in account types for testing licensing.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Account TypeCan check license before upload?Can receive test response?Can set test response?
Publisher accountYesYesYes
Test accountNoYesNo
OtherNoNoNo
+ +

Registering test accounts on the publisher account

+ +

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 +Save to save your profile changes.

+ +

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.

+ +

Handling application upload and distribution for test +account users

+ +

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.

+ +

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 +versionCode attribute in the manifest file.

+ +

Distributing your public key to test account users

+ +

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.

+ +

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.

+ + +

Signing in to an authorized account in the runtime +environment

+ +

The licensing service is designed to determine whether a given user is +licensed to use a given application — 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.

+ +

During testing, to ensure that your application can successfully query the +licensing server, you must make sure that you sign in to an account on the +device or emulator using:

+ + + + +
+
+

Signing in to a Google account on an emulator

+ +

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.

+ +

For more information, see Setting up the runtime environment, above.

+ +
+
+ +

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.

+ +

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.

+ +

To sign in on a device or emulator, follow the steps below. The preferred +approach is to sign in as the primary account — 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.

+ +
    +
  1. Open Settings > Accounts & sync
    2. +
  2. Select Add Account and choose to add a Google account. +
    3. +
  3. Select Next and then Sign in.
    4. +
  4. Enter the username and password of either the publisher account or a test +account that is registered in the publisher account.
    5. +
  5. Select Sign in. The system signs you in to the new +account.
    6. +
+ +

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.

+ +

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.

+ +

Once you've completed the setup procedures, continue to Adding Licensing to Your App.

+ + + -- cgit v1.1