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.
This document explains the common contexts in which users and administrators will interact with Marketplace applications.
Updated 2011-08-12: The installation flow no longer requires a separate "Enable" step. The application will be enabled by default when you install it. We believe this is what most people expect after installation and we hope that this change improves the installation process. Administrators can still disable an application through the app's settings page.
For a demonstration of the application install process, please watch the screencast on the right.
Step 1: Present Terms of Service
Upon choosing to install an application, the domain administrator will be presented with the Terms of Service for the application. These terms were supplied by the application's author while creating the listing.
After the domain administrator accepts the terms, the application will be able to query the licensing API and determine that the domain has installed the application. The notification entry provided via the licensing API will also include the administrator's email address so that he or she may be contacted by the application's author if there are problems in the setup flow.
Step 2: Grant Data Access
If the application's author has defined any scopes in the manifest file to get 2-legged OAuth access to APIs, these are listed, and the domain administrator is prompted to grant access.
Step 3 (Optional): Application-specific Configuration
Application authors may optionally provide a URL for domain administrators to click to finish application setup. When a domain administrator clicks on the 'Configure __APPLICATION__' link, the application should authenticate the domain administrator with OpenID to determine his or her name, email address and domain name for use in application's provisioning process.
Applications will be installed and enabled for all users on the domain. If the application manifest provides a link for Google's universal navigation, it will appear to all users by default, but can be disabled for a subset of users. If the application is Licensed on a per-user basis (named licenses), applications can use this setup step to allow a domain administrator to assign roles/licenses to individual users. In order to make this process more efficient, application authors may use the Provisioning API to query the users and groups on the domain. If application authors choose to allow only a subset of the users to be licensed, the application will need to enforce the licensing and provide reasonable instructions to unlicensed end-users who access the app.
Alternately, users can be provisioned and licensed on an ad-hoc basis when they first log in and access the application.
Resuming the installation
After the administrator configures the application, he or she must be returned to Google Apps and instructed to enable the application. To facilitate this, Google will append an additional query parameter to the application setup URL named "callback". The value of this parameter is a URL to redirect the user to after the additional settings have been completed.
An example setup URL looks like the following:
Upon completion, the application would redirect the administrator back to:
We strongly recommend that the administrator be directed through a short, linear series of actions and returned to Google quickly so additional users can start using the application.
End-user Daily Use
End-users will typically enter installed Marketplace applications via a link in Google's universal navigation.
Configuration of the link for Google's universal navigation is handled by the application manifest. After clicking on the application name in the universal navigation, users will be automatically signed in to the application via OpenID Single Sign-On.
Domain Administrator Additional Configuration
After an application is installed, a domain administrator can see the application listed in the Google Apps dashboard (http://www.google.com/a/<domain>/). This leads to an app settings page for the application.
From the setting page, administrators can adjust additional sittings by clicking on a "manage" URL provided by the application in the manifest. This URL points to the application's website, and the domain administrator will need to be authenticated via OpenID upon visiting that page. The application can keep track of its own set of administrators to allow access to or can use the Google Apps Provisioning API to allow access to all Google Apps admins on the domain.
A domain administrator can disable an application at any time using the Google Apps control panel. When an application is disabled from the control panel, the links will be removed for all users from Google's universal navigation and access to the APIs granted via 2-legged OAuth will be revoked. The links to re-enable the application and configure the application will remain in the control panel. An application can detect if it has been disabled using the licensing API and may take any action necessary as a result.
A domain administrator can choose to delete an application at any time using the Google Apps control panel. Before the application is deleted, the domain administrator will be presented with a link describing the data/service retention policies of the application, as provided in the application manifest. After the application is deleted, all references to the application will be removed from Google's universal navigation and access to the APIs granted via 2-legged OAuth will be revoked. An application should provide some way for domain administrators to claim their data and/or login after the application is deleted. An application can detect if it has been deleted using the licensing API and may take any action necessary as a result.