Google Marketplace, Google AppEngine and Python

Lately I was struggling with integrating my web app with Google Marketplace. I'd like to describe how to do it using Google AppEngine with Python.

The plan. What should be done to integrate your web app that is working on Google AppEngine to be available on Google Marketplace:

Enable OpenID authenticating on your web app
Become a vendor on Google Marketplace
Prepare manifest
Create a listing
Prepare integration for installation of your web app to Google Apps domain of your customer
Test it

The overview of integration also can be found in Google Marketplace developer pages: http://developer.googleapps.com/marketplace/getting-started.

OpenId

OpenId is needed to bring single sign-on for a customer. It enables smoth moving between Google Apps and your web app.

This can be done quite easy but won't work fully correctly. Native, experimental support for OpenID have been added to AppEngine a few months ago. So it can be just enabled from AppEngine administration console on Application Settings page. Change 'Authentication Options' from 'Google Accounts API' to '(Experimental) Federated Login'.

Doing so introduces one regression: remote_api will stop working. Google did not prepared it to be working with OpenID enabled. There is a workaround that brings it back. You can read about it on Nick's blog. MY_SECRET_KEY is just a password that must be passed in your authenticating function in your script that uses remote_api.

Becoming a Google Marketplace vendor

It is quite well described on getting-started page. Visit Google Marketplace home page, sign in and prepare your vendor profile.

Web app manifest

The manifest is an integration specification between your web app and Google Marketplace. This is a place where you define how to interact with your app to make it working with Google Apps. In a manifest, there should be provided:

URL for web app setup as an optional redirect during the install (setup)
URL for web app configuration, accessed from Google Apps settings page in the control panel (manage)
URL explaining how customers get support (support)
URL that is displayed to admins during the deletion process, to specify policies such as data retention, how to claim accounts, etc. (deletion policy)
Name and description of your web app
Link to your web app that will be available on customer's Google Apps pages
OpenID realm - it should be exactly the domain of your web app that is used during OpenID authentication process
any rights that are needed to get access to customer's resources like e.g. calendar

Example of manifest can be found on Google Code pages.

Creating a listing

When manifest is ready then a web app listing can be created. You have to go to your vendor profile on Google Marketplace and click "Create a new listing" button. This leads you to listing configuration page. You can create any number of listings you want. You will have to pay $100 for publicizing a listing.

On listing configuration page, first check "My product may be directly installed into Google Apps domains". This will allow you posting your newly created manifest. If you miss it you will not be able to include your manifest in this listing any more and you will have to prepare a new one (this is one time decision).

Then select category of your web app, type in your web app name, summary, full overview, and then your manifest following with pricing summary and terms of service. Later you will be able altering all of this fields.

Installing a web app to Google Apps

In web app manifest there were defined several links to the web app. Google Apps visits setup link during installation. This is a point where a web app can prepare itself for customer's Google Apps. During installation, after customer selected a web app, customers goes through wizard.

Add it now

Let's start from the beginning. Installation is started by clicking on 'Add it now' button on web app listing page. Customer just has to enter here his Google Apps domain name.

Terms of Use

Second step is agreeing with terms of use. Web app provider can either display on this page whole terms of use text or just put a link to this document. This is configured on listing configuration page.

Starting setup step

Third step presents information about web app configuration page. When customer clicks 'Configure Application' then he will land on your setup page that was indicated in application manifest. If this setup step was not set in the manifest then it will be skipped.

Setup step

Next step, forth, is a setup step that is made in your web app. Now you get control on installation wizzard. You can ask customer about additional information, and then prepare web app for his Google Apps e.g. create account. During entering setup page, it's handler receive one parameter from Google in HTTP GET request in URL: callback. It should be used to come back to Google's installation wizard.

During setup you should use AppEngine's OpenID facilities for getting information about user that is installing your web app. It can be done as follows:

        callback = self.request.get("callback")
        user = users.get_current_user()
        # if user is not logged in then use OpenID to log in
        if user == None:
            fi = "https://www.google.com/accounts/o8/site-xrds?hd=" + domain
            url = users.create_login_url("/gaps/setup/%s?callback=%s" % (domain, urllib.quote(callback)), _auth_domain=None, federated_identity=fi)
            self.redirect(url)
            return

         # now user is logged via OpenID, you can create an internal account for him
         # and prepare web app for his Google Apps domain

         # after completing whole setup redirect user back to Google's wizard
         self.redirect(callback)
         return

The way domain variable is passed to setup page handler depends on your setting in manifest. You can pass it as HTTP GET parameter in URL or just as a part of URL.

The place where you have to send user to be authenticated in OpenID process is following URL fi = "https://www.google.com/accounts/o8/site-xrds?hd=" + domain

In function create_login_url as a first argument you pass your url to which OpenID will redirect after authenticating user.

Then you can just prepare web app for customer Google Apps. At the end of setup step you must redirect customer's browser back to Google's installation wizard.

Enabling

Fifth step is enabling web app in customer's Google Apps. This step ends installation wizard. After clicking 'Enable app now' user will be redirected to your web app settings page in Google Apps.

Settings on Google Apps

On Google Apps on web app settings page customer can:

enable or disable your web app
go once again to setup step
visit admin or support pages that were indicated in manifest
delete you application from Google Apps

Testing

To test if integration succeeded go to customer's email account on Google Apps and look on navigation menu on top, click 'more' drop down menu and check if a name of your web app is present here. If it's there you can click it. This will open new tab in your browser with the page of your web app that was indicated in application manifest as navLink. Now your web app should automatically authenticate customer user using OpenID (using the same way as in setup page) and then present your web app content to user.

Next steps

Retrieving email addresses of Google Apps users using 2-legged oauth authentication method.
Checking if customer enabled your web app on his Google Apps using Licensing API (http://code.google.com/googleapps/marketplace/licensing.html)

Godfryd's Blog