Publishing Gmail Add-ons

Publishing add-ons allows them to be used by other users, who can access and install them from Gmail and from the G Suite Marketplace.

You can publish your add-on publicly, so that any Gmail user can find and install it. You can also publish add-ons privately, for users in a specific domain only. If you are a G Suite domain administrator, you can install published add-ons—whether public or private—for your domain users.

Once you've successfully published an add-on, you can continue to improve it—see Managing Published Add-ons for more information.

In addition to published add-ons, you can also install an unpublished add-on—this lets you test it or just use it youself without publishing. You can also install unpublished add-ons created by other users in your domain if they give you the add-on's deployment ID.

Before you begin

Before you begin the publication process, it is important to understand your publishing options.

Visibility

When configuring your add-on for publication, you must choose to publish it as either a Private or Public add-on. This is the add-on's visibility.

Private add-ons

Private add-ons are only visible to users in the same domain as the add-on publishing account. They can't be installed by outside users. Private add-ons do not require add-on review.

Public add-ons

Public add-ons are visible globally in the G Suite Marketplace. Anyone can see and install them if their domain policies allow it. Public add-ons must go through the add-on review process before they are published. This review process can take a few days to complete, and may require you to make changes to your add-on code.

Collaboration

When you colloborate with others in developing an add-on, the add-on project is owned by a single user account. When you publish an add-on, a single user account acts as the publisher. The publishing account must have edit access to the add-on script project, but it doesn't need to be project owner.

We encourage you to use Team Drives when you collaborate on an add-on. This allows you to avoid losing access to your add-on's code and console settings because a member of your team left your organization. Alternatively, create a common team account to serve as the owner and publisher of the script project.

Publishing requirements

Before add-ons can be published publicly, they must be submitted to Google for add-on review. This process ensures that the add-ons available in the G Suite Marketplace meet quality and user protection guidelines.

Use the checklist below to make sure that your add-on will pass the add-on review process. If you are publishing your add-on privately, you can still use this checklist to ensure your add-on provides a good user experience.

General requirements

Make sure your add-on meets the following general requirements before attempting to publish:

  • Completeness. The add-on must be fully functional. It can't be a “work in progress.”
  • Testing. The script has been tested with multiple active users as an unpublished add-on.
  • Naming. The script's project name is the same as the name intended for publication (the script name appears in the authorization dialog).
  • OAuth client verification. You have requested OAuth verification for add-on script project. This requires that you show ownership of a domain and that you have a privacy policy hosted within that domain.
  • Style. Follow the recommendations in the add-on style guide.

Technical requirements

Make sure your add-on meets the following technical requirements before attempting to publish:

  • Manifest. The add-on script project must include a well-defined manifest.
  • Trigger function. If your add-on script uses a contextual trigger, it must have a well-defined trigger function implemented and specified in the project manifest.
  • Universal actions. Any universal actions defined in your add-on script must specified in the manifest and relate to context-independent actions.
  • OAuth flow. If your add-on connects to non-Google services using OAuth, ensure it handles the OAuth authorization flow correctly.
  • Libraries. The add-on does not use libraries unnecessarily, which can cause the add-on to run slowly in some cases.
  • Error handling. The add-on script has error-handling, shows relevant error messages to the user, and uses error cards where appropriate.
  • Hosted images. All users of the add-on can access any hosted image used in your add-on.
  • Versioned deployment. The add-on has a versioned deployment to be used for publication. Do not use head deployments for published add-ons. When you update your add-on, create a new script project version and edit the versioned deployment to use that version number.

User data protection requirements

The following requirements help to ensure that user data is protected while they use your add-on. Any add-on that fails to sufficiently protect user information cannot pass review for publication. In addition, if your script code fetches or opens URLs that aren't whiteisted, you can't create or edit versioned deployments of your add-on.

  • Scopes. You must set explicit scopes in the add-on manifest, choosing the narrowest scopes possible. Never have the add-on ask the user for more permissions than it actually needs. See the Gmail add-on scopes section for a list of scopes often used with Gmail add-ons. Most of these require a temporary access token.

  • URLFetch whitelist. If the add-on script uses UrlFetch to retrieve data, you must whitelist the URLs it accesses using the urlFetchWhitelist field in the add-on manifest. Restrict the URLs the add-on fetches to:

    • Legitimate third-party APIs,
    • Sets of private endpoints you control, and
    • Authorization endpoints that enable OAuth flows.

    If your add-on functionality demands it, you can use a * character as wildcard in the whitelist.

  • Open link whitelist. If your add-on script makes use of OpenLink actions, you must whitelist the URLs it opens using the gmail.openLinkUrlPrefixes field in the add-on manifest. This whitelist restricts what URLs the add-on can open. If your add-on functionality demands it, you can use a * character as wildcard in the whitelist.

Graphic asset requirements

In order to build your listing in the G Suite Marketplace, you must provide the following image assets for your add-on. If desired, you can update the add-on graphic assets after publication by editing the listing.

Required assets

The following additional graphic assets are required to build the G Suite Marketplace listing for your add-on:

  • An application banner image. Sized to 220 x 140 pixels.
  • A screenshot of your add-on. At least one is required, sized to 640 x 400 pixels.
  • Icon images. Two are required, one sized to 128 x 128 pixels and the other to 32 x 32 pixels.

Optional assets

The following additional graphic assets are optional and are used to enrich the G Suite Marketplace listing for your add-on:

  • Additional icon images. Two additional versions of the icon image, one sized to 48 x 48 pixels and the other to 96 x 96 pixels.
  • Additional screenshots. Sized to 640 x 400 pixels; three to five screenshots are recommended.
  • Hosted product logo image URL. The logo can be no larger than 120 x 120 pixels.

Text asset requirements

In addition to graphics, you must provide the following text descriptions and URLs to build your add-on's G Suite Marketplace listing. You can update these assets after publication by editing the listing.

Required text assets

  • Application name. The name of the add-on shown in the listing. This must be the same as the add-on name you specified in your add-on script project manifest. Make sure you follow the branding guidelines when choosing a name. Limit this string to 15 characters or less to ensure it displays well in the G Suite Marketplace listing.
  • Short application description. A short summary of what your add-on does. Limit this to 200 characters or less to ensure it displays well.
  • Detailed application description. A longer description of what your add-on can do for the user. It is presented in the Overview section of the G Suite Marketplace listing, under the screenshots you provide. Limit this to less than 16,000 characters.
  • Terms of Service URL. A URL to a web page that describes your add-on's terms of service.
  • Developer website URL. A URL to a web page that identifies you (or your organization) as the developer of the add-on.
  • Support email. An email address that developers can contact for support. This address should be a Google Group support forum within your domain, such as my-company-support@mydomain.com. The managing account for the Google Group must be the same used to publish the add-on.
  • Privacy policy URL. A link to a web page that describes your add-on's privacy policy. This is required for client OAuth verification, and you can also use it in your add-on's G Suite Marketplace listing.

Enrich your G Suite Marketplace listing with the following optional information:

  • Developer name. The name you want listed as the author of the add-on. Recommended.
  • Developer email. An email address that is used as point of contact for the add-on. This email address is not included in the G Suite Marketplace listing; rather, it is used if Google needs to contact the add-on developer.
  • Application website URL. A link to a web site that describes your add-on. This is distinct from the above developer website URL, which is a page that describes you or your organization.
  • YouTube video URL. A link to a YouTube video that describes your add-on and shows it in action.
  • Setup URL. A link to a web page that describes how to set up your add-on after it is first installed. Only recommended if the add-on requires configuration that cannot be explained well within the add-on itself.
  • Admin config URL. A link to a web page that describes how domain administrators must configure the add-on for use by their users. Unnecessary unless the add-on requires a domain-level configuration.
  • Support URL. A link to a web page that describes how your users can get support from you if they are having issues with the add-on. Recommended.
  • Deletion policy URL. A link to a web page describing how and when user data that your add-on uses is deleted. Strongly recommended if the add-on collects and stores user data for use later.

Publish an add-on

Once you have fulfilled all the publication requirements for your add-on, you can publish it by completing the following steps:

Step 1: Create a versioned deployment

Create a versioned deployment of your add-on using the version of the code you want to publish. Your add-on can only have one versioned deployment, but you can change the script project version that it uses. Do not attempt to publish using a head deployment.

Once you've created a versioned deployment, select the Get ID link for that deployment in the Deployments dialog. This shows a new dialog containing the deployment description and the deployment ID.

During add-on authorization, users see a dialog that describes the requested permissions. You can customize this dialog to some extent by using the following steps:

  1. Open your add-on in the script editor.
  2. Select Resources > Cloud Platform project from the editor menu. In the dialog that appears, click the name of the project your script is associated with.
  3. In the console's left navigation, select APIs & services to open the API dashboard.
  4. In the left nav, select Credentials to open the credentials control panel.
  5. In the credential control panel, select the OAuth consent screen tab.
  6. Under the Email address field, enter the Support email you want to use for support questions. On some platforms, this email address is shown with the developer info.
  7. Under the Product name shown to users field, enter the Application name for your add-on.
  8. The remaining fields are optional, but you create a better user experience by providing them. Provide a Homepage URL, Privacy policy URL, and Terms of service URL in the corresponding fields. These should match, respectively, the Application website URL, Privacy policy URL, and Terms of Service URL assets you collected.
  9. Under the Product logo URL field, optionally provide a URL to a hosted product logo. The logo can be at most 120 x 120 pixels.
  10. Click Save to record your selections.

You have now configured the OAuth consent screen.

Step 3: Enable the Marketplace SDK

The G Suite Marketplace SDK lets you configure the appearance of your Marketplace listing. Enable the SDK in your add-on script project by doing the following:

  1. If you have not done so already, open your add-on's Cloud Platform console:
    1. Open your add-on in the script editor.
    2. Select Resources > Cloud Platform project from the editor menu. In the dialog that appears, click the name of the project your script is associated with.
  2. In the console's left navigation, select APIs & services to open the API dashboard.
  3. In the API dashboard, select the Enable APIs and Services button.
  4. In the Search for APIs & services search bar, type "Google Apps Marketplace SDK". Select this API.
  5. In the API listing that opens, click the Enable button. After a moment the SDK overview control panel opens.

You have now enabled the G Suite Marketplace SDK for your script project. Now you can use the SDK control panel to configure the SDK.

Step 4: Configure the Marketplace SDK

The G Suite Marketplace SDK control panel has four tabs: Overview, Configuration, Publish, and Usage. You first need to provide information in the Configuration tab and then in the Publish tab.

Configuration tab

  1. Open the Marketplace SDK control panel if it isn't open already. Select the Configuration tab. This panel contains a form where you add information about your add-on.
  2. Fill in the Application info section as follows:
    • Provide the Application name and Short application description assets. Provide these assets for each language you intend to publish the add-on in.
    • Check the Enable individual install checkbox if you want to allow individuals to install your add-on. Leave it unchecked if you want the Marketplace SDK to only allow domain administrators to install the add-on for their domains.
    • Provide the icon assets. You can click Preview to verify the look and resolution of the uploaded files.
  3. Fill in the Support URLs section using the Terms of Service URL and other URLs for your add-on.
  4. Fill in the OAuth Scopes section with each scope your add-on uses. You must add every scope listed in your add-on project's manifest file. The userinfo.email and userinfo.profile are included by default and cannot be removed.
  5. Fill in the Extensions section as follows:
    • Leave all three checkboxes in the Extensions section unchecked. They do not apply to Gmail add-ons.
    • Check the Gmail add-on extension checkbox in the Add-on extensions subsection. This causes a textbox to appear. In this textbox, enter the deployment ID for the versioned deployment you created.
  6. Fill in the Visibility subsection by selecting Public or Private visibility for your add-on.
  7. Verify that the information you have entered in the form is correct, then click Save changes.

Publish tab

After saving the Configuration tab settings, you must finalize the G Suite Marketplace SDK configuration in the Publish tab:

  1. If you haven't already, select the Publish tab. This panel contains a form where you can add the remaining information about your add-on.
  2. Fill in the Detailed Description subsection using your add-on's Detailed application description. Provide the description for each language you intend to publish the add-on in.
  3. Fill in the Application banner subsection by providing the application banner image. You can click Preview to verify the look and resolution of the uploaded file.
  4. Fill in the Screenshots subsection by uploading each screenshot image. You can click Preview to verify the look and resolution of the uploaded files.
  5. Fill in the Links and information section with the requested URLs and text assets. The Developer website URL is required and the others are optional.
  6. Fill in the Reach section as follows:
    • Use the Categeory dropdown menu to select an appropriate category for your add-on. This can help users find your add-on in the G Suite Marketplace.
    • Select the regions and countries for the add-on. Your add-on is included in the internationalized version of the G Suite Marketplace for each region you select. If you include a region, it's a good idea to ensure the add-on and its text assets are internationalized to the languages used in that region.
  7. Review the information you have entered into the Publish tab. Once it is all correct, click the Publish button.

Once you have completed these steps your add-on is fully configured for publishing. If you selected Private visbility for you add-on, the publication process completes in a few minutes, after which the add-on is available for install by your domain administrator or by users in your domain.

If you have selected Public visibility for your add-on, clicking the Publish button saves your configuration and starts a request for an add-on review. While your add-on is under review, the fields in the Publish tab of the SDK control panel cannot be changed.

Add-on review

When you complete the publication steps for a public add-on, a request for add-on review is automatically sent to the Google review team. A review team member then examines your add-on and its listing to ensure it is designed well, follows the add-on style guidelines, takes the appropriate steps to protect user data, and does not include any malicious code or unacceptable content.

After the review team member makes their initial assessment, you will receive an email communicating whether your add-on has been approved (and has been automatically added to the G Suite Marketplace) or if it requires additional work before it is publicly available.

If your add-on requires additional work, you will receive a review document containing specific information about what aspects of the add-on need improvement. Address all highlighted issues and follow the provided instructions to resumbit your add-on. Many developers are required to improve their add-ons prior to public release; some may be required to do this multiple times. You may always contact our review team for more information and guidance with this process. Once the review team's concerns are satisfied, you will be informed and your add-on will be automatically added the G Suite Marketplace.