Licensing Reference

LVL Classes and Interfaces

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 com.android.vending.licensing package.

Table 1. Summary of LVL library classes and interfaces.

Server Response Codes

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.

Table 2. Summary of response codes returned by the Google Play server in a license response.

Note: As documented in Setting Up The Testing Environment, the response code can be manually overridden for the application developer and any registered test users via the Google Play publisher site.

Additionally, as noted above, applications that are in draft mode (in other words, applications that have been uploaded but have never been published) will return 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.

Server Response Extras

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 APK expansion files, 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.

Any Policy implementation can extract the extras settings from the license response and use them as needed. The LVL default Policy implementation, ServerManagedPolicy, serves as a working implementation and an illustration of how to obtain, store, and use the settings.

Table 3. Summary of license-management settings supplied by the Google Play server in a license response.

License validity period

The Google Play 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 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 VT. A 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.

The license validity signals to a licensing Policy when it must recheck the licensing status with the licensing server. It is not 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 — rather, it indicates only that the 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 Policy to cache the initial license status locally and return the cached license status instead of sending a new license check to the server.

The licensing server manages the validity period as a means of helping the application properly enforce licensing across the refund period offered by Google Play 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:

• 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 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.
• When an application is no longer refundable, the server sets a longer validity period — typically a number of days.
• For a free application, the server sets the validity period to a very high value (long.MAX_VALUE). This ensures that, provided the Policy has cached the validity timestamp locally, it will not need to recheck the license status of the application in the future.

The ServerManagedPolicy implementation uses the extracted timestamp (mValidityTimestamp) as a primary condition for determining whether to recheck the license status with the server before allowing the user access to the application.

Retry period and maximum retry count

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 Google Play client application. For example, the user might launch an application when there is no cell network or data connection available—such as when on an airplane—or when the network connection is unstable or the cell signal is weak.

When network problems prevent or interrupt a license check, the Google Play client notifies the application by returning a RETRY response code to the Policy's processServerResponse() method. In the case of system problems, such as when the application is unable to bind with Google Play's ILicensingService implementation, the LicenseChecker library itself calls the Policy processServerResonse() method with a RETRY response code.

In general, the RETRY response code is a signal to the application that an error has occurred that has prevented a license check from completing.

The Google Play 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 GT and GR.

The application Policy can extract the GT and GR extras and use them to conditionally allow access to the application, as follows:

• For a license check that results in a RETRY response, the Policy should cache the RETRY response code and increment a count of RETRY responses.
• The 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.

The ServerManagedPolicy uses the server-supplied GT and GR values as described above. The example below shows the conditional handling of the retry responses in the allow() method. The count of RETRY responses is maintained in the processServerResponse() method, not shown.

    
public boolean allowAccess() {
    long ts = System.currentTimeMillis();
    if (mLastResponse == LicenseResponse.LICENSED) {
        // Check if the LICENSED response occurred within the validity timeout.
        if (ts <= mValidityTimestamp) {
            // Cached LICENSED response is still valid.
            return true;
        }
    } else if (mLastResponse == LicenseResponse.RETRY &&
                ts < 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 <= mRetryUntil || mRetryCount <= mMaxRetries);
    }
    return false;
}