Google Apps Platform

Testing Your Application

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.

Installable listings allow users to install the application directly from the Google Marketplace using the "Add it Now" box available directly from your listing.

Before submitting your installable application to the Google Apps Marketplace, it is important to review use cases and thoroughly test your application's integration to ensure users have a great experience. The following checklist identifies the major areas you should be sure to test and check.

Completing this checklist does not necessarily guarantee that your installable listing will be accepted into the Marketplace. However, failing to address any of these issues will cause your listing to be rejected. For a more information, see the Listing Approval page on the Developer Program Site.

Once your testing is complete and you're ready to launch, you may submit your application for approval.

Pre-submission Testing Checklist

OpenID and Single Sign On

Support OpenID with Google Apps accounts

Google uses two separate namespaces for user accounts—Google Apps and Google Accounts—and both have separate OpenID endpoints.

All installable applications in the marketplace must support OpenID for Google Apps users.

Information on the two endpoints can be found here:

Applications that support both businesses and individual consumers may choose to support both endpoints along with other popular OpenID providers.

Whitelist OpenID realm for seamless Single Sign-On

Marketplace applications that are installed by an administrator should not prompt users about OpenID requests.

In most non-Marketplace implementations of OpenID, applications generally prompt users for confirmation when the application makes OpenID requests to Google. However, Marketplace applications that are installed by a domain administrator should bypass this step because we can assume that the administrator has the authority to grant access on behalf of users.

Instead of displaying a confirmation page, your application should match the value of the openid.realm parameter in the OpenID request against the value declared in the application's manifest. As long as the values match exactly, the user is seamlessly signed on to the application.

Ensuring this is implemented correctly can be a bit tricky. If your application prompts the user with a screen like the following screenshot, you know you have a problem.

If you see a prompt like this, it means your application has an OpenID realm mismatch and needs to be fixed before your installable listing can be accepted into the Marketplace.

Important! Even if you don't see this prompt, you may still have a realm mismatch issue without realizing it. Note in the screenshot that the "Remember this approval" checkbox is checked by default. This means you may have saved approvals left over from a previous testing session that will cause the application to skip displaying the prompt even if you have a realm mismatch. This will mask the underlying realm mismatch issue.

Before testing, be sure to clear any saved authorizations:

  1. Depending on the type of account you have, go to one of the following URLs:
    • https://www.google.com/a/your-domain-here/IssuedAuthSubTokens
    • https://www.google.com/accounts/IssuedAuthSubTokens
  2. Click "Revoke Access" on the items for which you want to clear saved authentications.

An alternative approach to testing for a domain mismatch would be to use a new Google Apps domain for your final testing to ensure that there are no saved approvals that might mask a realm mismatch.

Handle both GET and POST responses from Google's OpenID endpoint

Applications must be able to handle OpenID responses from Google using both GET and POST requests. The OpenID endpoint changes methods based on the length of the response (see step 8 here), using POST once the length exceeds a certain threshold. Applications that use attribute exchange to fetch user attributes are likely to generate responses that exceed this threshold. It is important to handle both GET and POST requests to ensure all authentication requests are successful.

Support users that navigate directly to your application

While installable applications benefit from being just a click away in Google's universal navigation, users may sometimes go directly to your application in the browser. Your application should make it clear how Google Apps users can proceed to log in and use the application when not coming directly from a Google application. Suggestions on user interfaces for handling federated login on your site can be found in our user experience research site as well as by evaluating existing applications in the marketplace.

OAuth & Data Access

Use HTTPS when accessing the Google Data APIs and OpenID

Google takes the security and privacy of customer data seriously, and so should applications in the marketplace. In order for your installable listing to be accepted into the marketplace, your application must use HTTPS for OpenID and Google Data feeds.

Your application's openid.return_to URL should also use HTTPS. This prevents security warnings which may appear if OpenID does a POST back to your site (See Handle both GET and POST responses from Google's OpenID endpoint above).

Declare data access scopes correctly in the manifest

If using 2-legged OAuth to access data in Google Apps, verify the scopes are declared correctly in the manifest with clear reasons for usage. The application shown here illustrates two common pitfalls in declaring scopes.

This application makes two common mistakes:

  • The Docs API does not include a valid <Reason> element in the manifest, so this dialog displays no explanatory text in the field that should explain to the user why access should be allowed.
  • The Calendar API scope is specified using the wrong URL and is not recognized as one of the standard APIs. The correct URL to use here is https://www.google.com/calendar/feeds/.

Ensure the production instance is configured using the correct key and secret

Prior to submitting your installable listing, verify that your production environment is configured with the correct key and secret and that the values are protected from theft or abuse. We know it is common for developers to create multiple listings in the marketplace to represent different development and staging environments and that each application listing has a unique OAuth key and secret. This is why it's important to verify that your final listing uses the correct key and secret, and that they are protected before submitting your installable listing.

You can verify that you're using the correct key by testing on a brand new Google Apps domain that has the application installed directly from your production listing.

Setup & User Experience

Promptly return users to the control panel when using the optional setup URL

Applications that use the optional application-specific configuration step during installation are required to return users back to Google Apps in order to complete the installation process. The URL specified in the manifest for this step will automatically be appended with a query parameter named callback with a URL as the value. Once the setup is completed on the application the user should be redirected back to this URL. Any setup or configuration done at this stage should use a wizard style approach that guides the user through a sequence of steps with a defined goal.

If the user is not returned back to this URL the application will remain in a disabled state and the application will not be displayed in the universal navigation menu unless the administrator manually returns to the control panel to enable the application.

Welcome both new and existing customers

The Google Apps Marketplace is a great way to reach new customers, but don't forget about existing customers either. If you have existing customers that are Google Apps users they can often provide excellent feedback as to what integrations are most useful. They're also more likely to be the early adopters of your product in the marketplace, driving installations and reviews. We recommend adding options during the installation process so existing customers can quickly and easily associate their existing users and data with their Google Apps domain.

Authentication required

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

Signing you in...

Google Developers needs your permission to do that.