Google Apps Platform

Licensing Developer's Guide v2

Note: There's a new Google Apps Marketplace experience! Beginning November 19, 2013, new listings may only be created using the new version: existing developers may need to create a new Chrome Web Store account to publish new listings. Refer to the new documentation for more information.

The licensing API provides information regarding installation activity for your application. It supports both an event feed of all activity for your application as well as a query mechanism to determine if a domain or user has installed your application. Client libraries are available in several languages. While using a client library is recommended (if one is available for your language), it is not required. Developers that wish to connect without using a client library should refer to the Reference Guide.

The following document is intended to demonstrate how you can use the Google API Client library in several languages (currently Java, Python, and Ruby) for accessing licensing data.

Contents

  1. Setup
  2. Modelling data representation classes
  3. Instantiating the client
  4. Interacting with the API
    1. Retrieving a customer license
    2. Retrieving a user license
    3. Retrieving license notifications

Setup

Setup of the Client Library is language specific. Please select the tab for the language you will use for development.

Java

Using the Google API Client Library for Java requires two .jar files. Download these files and include them in your build path:

google-api-client-1.2.1-alpha.jarThe Google API Client Library, where 1.2.1 in this example is the version number. This file is available on the project page.
appsmarket-2010_12_3.jarThe service and data objects for the licensing APIs, where 2010_12_3 is the release date of the most recent version. This file is available on the Apps Marketplace Resources project page.

Note: This documentation has been written for and tested with version 1.2.1 of the Google API Client library which can be downloaded here. The latest version is not guaranteed to be backward compatible with this one.

You can now import the classes you will need using the following import statements:

import com.google.api.client.http.HttpResponseException;
import com.google.api.client.sample.appsmarket.model.CustomerLicense;
import com.google.api.client.sample.appsmarket.model.Debug;
import com.google.api.client.sample.appsmarket.model.LicenseNotification;
import com.google.api.client.sample.appsmarket.model.LicenseNotificationList;
import com.google.api.client.sample.appsmarket.model.UserLicense;
Python

Using the Google API Client Library for Python requires that you download the Python source. In the future, packages will be provided. Refer to the project page for more details.

Run the following commands to download and install the source:

$ hg clone https://google-api-python-client.googlecode.com/hg/ google-api-python-client
$ cd google-api-python-client
$ sudo python setup.py install

You can now import the classes you will need using the following import statements:

from apiclient.discovery import build
from apiclient.oauth import OAuthCredentials

import httplib2
import oauth2 as oauth
Ruby

We recommend using RVM to configure and manage your Ruby and gem installation. Once you have RVM installed, proceed to install the google-api-client gem:

gem install google-api-client

You can now import the classes you will need using the following import statements:

require 'rubygems'
require 'google/api_client'

Modelling data representation classes

One of the main tasks of the Google API Client Library is translating JSON to native objects and back. In the Java library, this is done by a set of classes provided by the appsmarket .jar file. In Python and Ruby, JSON is converted directly into a dictionary or hash, respectively.

Instantiating the client

You must instantiate a client to make requests to the API. All requests to the licensing APIs require authentication using OAuth, specifically 2-legged OAuth. The Client Libraries will handle authentication for you, but you will need to provide your consumer key and consumer secret. These are the consumer key and secret generated for your application by the Marketplace, and presented to you in your vendor profile. The following code demonstrates how to configure your client and authenticate with the APIs. This example connects to the production endpoint. If you would like to connect, instead, to the sandbox, replace v2 in the examples with v2sandbox.

Java
AppsMarketService service = new AppsMarketService();
service.appId = YOUR_APPLICATION_ID;
service.appName = YOUR_APPLICATION_NAME;
service.endpoint = "https://www.googleapis.com/appsmarket/v2/";
service.consumerKey = service.appId + ".apps.googleusercontent.com";
service.consumerSecret = YOUR_CONSUMER_SECRET;
service.authorize();
Python
http = httplib2.Http()
consumer = oauth.Consumer(YOUR_CONSUMER_KEY, YOUR_CONSUMER_SECRET)
token = oauth.Token('', '')
credentials = OAuthCredentials(consumer, token, YOUR_APPLICATION_NAME)
http = credentials.authorize(http)

service = build(serviceName='appsmarket', version='v2', http=http)
Ruby
client = Google::APIClient.new(:authorization => :two_legged_oauth_1)
client.authorization.client_credential_key = YOUR_APPLICATION_ID + '.apps.googleusercontent.com'
client.authorization.client_credential_secret = YOUR_CONSUMER_SECRET
client.discovery_uri = 'http://www.googleapis.com/discovery/0.1/describe?api=appsmarket'
service = client.discovered_service('appsmarket', 'v2')

Interacting with the API

Now your client is ready to begin making calls to the API. The following sections demonstrate connecting to each of the methods of the API.

Retrieving a customer license

The customer license API allows you to retrieve the license status of a customer, identified by the customer's domain. The response to a call to this API will include the customer's licensing state and any editions to which the customer currently subscribes. For a complete description of all response fields and possible values for those fields, see the reference.

The following request retrieves the customer license for example.com.

Java
String customerId = "example.com";
CustomerLicense license = service.getCustomerLicense(customerId);
Python
customer_license = service.customerLicense().get(applicationId=YOUR_APPLICATION_ID, customerId='example.com').execute()
Ruby
status, headers, body = client.execute(service.customer_license.get, 'applicationId' => YOUR_APPLICATION_ID, 'customerId' => 'example.com')
customer_license = JSON.parse(body.join)

Note: If you query for a customer that installed your application prior to the launch of the licensing APIs, the customer will appear to have a site license for an edition named default_edition.

Retrieving a user license

The user license API allows you to retrieve the license status of an individual user, identified by his or her email address. The response to a call to this API will include the user's licensing state, whether or not the application is enabled for the user, and the edition to which he or she is subscribed. For a complete description of all response fields and possible values for those fields, see the reference.

The following request retrieves the user license for admin@example.com.

Java
String userId = "admin@example.com";
UserLicense license = service.getUserLicense(userId);
Python
user_license = service.userLicense().get(applicationId=YOUR_APPLICATION_ID, userId='admin@example.com').execute()
Ruby
status, headers, body = client.execute(service.user_license.get, 'applicationId' => YOUR_APPLICATION_ID, 'userId' => 'admin@example.com')
user_license = JSON.parse(body.join)

Note: If you query for a user that installed your application prior to the launch of the licensing APIs, the user will appear to have a license (as part of a site license) for an edition named default_edition.

Retrieving license notifications

The license notifications API allows you to retrieve a list of license-related events that have occurred for customers of your application. These events may be of four types:

  • provisions — A new license of the application has been provisioned.
  • expiries — A license of the application has expired.
  • deletions — An application has been deleted from a domain.
  • reassignments — An administrator has assigned or revoked a seat license for the application on the provided domain.

The license notification API allows several optional parameters:

  • timestamp — The time, measured in milliseconds since the UNIX epoch, to begin querying for notifications. The API will return results that occurred approximately after this time, but occasionally may return results that occurred prior to the timestamp. If you must have a list of notifications that only contains results after the timestamp, it is recommended that you apply a second filter in your code. The timestamp may not be used simultaneously with a start-token.
  • start-token — A continuation token, returned from a previous query, that may be used to continue retrieving notifications after the previous result set stopped. The start-token may not be used simultaneously with a timestamp.
  • max-results — The maximum number of notifications to return.

For a complete description of all response fields and possible values for those fields, see the reference.

The following example retrieves all license notifications for the application, batched in groups of 10.

Java
int maxResults = 10;
LicenseNotificationList list = service.getLicenseNotifications(maxResults, 0);
String token = "";
while (list.notifications != null) {
  for (LicenseNotification notification : list.notifications) {
    // Do something with the notification
  }
  if (!token.equals(list.nextPageToken)) {
    token = list.nextPageToken;
    list = service.getLicenseNotifications(maxResults, list.nextPageToken);
  } else {
    break;
  }
}
Python
license_notifications = service.licenseNotification().list(applicationId=YOUR_APPLICATION_ID, timestamp=0, max_results=10).execute()
token = ''
while license_notifications.has_key('notifications'):
  for notification in license_notifications['notifications']:
    # Do something with the notification
  if token != license_notifications['nextPageToken']:
    token = license_notifications['nextPageToken']
    license_notifications = service.licenseNotification().list(applicationId=YOUR_APPLICATION_ID, start_token=license_notifications['nextPageToken'], max_results=5).execute()
  else:
    break
Ruby
status, headers, body = client.execute(service.license_notification.list, 'applicationId' => YOUR_APPLICATION_ID, 'max-results' => '10', 'timestamp' => '0')
license_notifications = JSON.parse(body.join)
token = ""
while license_notifications['notifications']
  for notification in license_notifications['notifications']
    # Do something with the notification
  end
  if token != license_notifications['nextPageToken']
    token = license_notifications['nextPageToken']
    status, headers, body = client.execute(service.license_notification.list, 'applicationId' => YOUR_APPLICATION_ID, 'max-results' => '10', 'start-token' => license_notifications['nextPageToken'])
    license_notifications = JSON.parse(body.join)
  else
    break
  end
end

Note: The results from the license notifications API will contain only events that occurred after the launch of the licensing APIs. Events that occured prior to launch will not appear. However, the events that appear will be for both new and existing customers. The net effect of this is that you may see a deletion notification for an application, without a matching provision notification if a domain installed an application before the launch and deleted it after.

Authentication required

You need to be signed in with Google+ to do that.

Signing you in...

Google Developers needs your permission to do that.