Publishing an editor add-on

Publishing add-ons lets them to be used by other users. When you publish, you set the add-on visibility to determine who is able to install the add-on.

When you publish an editor add-on, it appears in the G Suite Marketplace. The add-on listings appear in the editor Get add-ons... interfaces as well as in the G Suite Marketplace.

This guide describes the process of publishing editor add-ons to the G Suite Marketplace.

Before you begin

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

Visibility

See Published add-on visibility for details on who can use your published add-ons.

Collaboration

When you colloborate with others in developing an add-on, the add-on project is owned by a single user account or shared drive. 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.

Before you begin publication, be sure to review and configure your project collaborator access settings.

Development checklist

Prior to publishing, your should verify that your editor add-on is functioning well. Use the checklist below to determine if your add-on is ready for publication.

General

  • The editor add-on must be fully functional—it can't be a “work in progress.”
  • The script has been tested with multiple active users.
  • The design adheres to the UI style guide.
  • If you want to publish your add-on publicly, request verification before starting the publishing process.
  • Public add-ons should use the narrowest scopes possible to protect user data.

Technical

  • The add-on script project must use a standard Cloud Platform (GCP) project. If the script project currently uses a default GCP project, you must switch to a standard GCP project. All collaborators working on the add-on should have access to the standard GCP project.
  • It is preferable to develop add-ons in a standalone script. Be sure to test your add-on to ensure the add-on is behaving correctly in Sheets, Docs, Slides, or Forms as appropriate. Verify the menus and functionality behave as expected for different states of installed and enabled.
  • The script project's name is the same as the name intended for publication, as the script project name appears in the authorization dialog.
  • The add-on has error-handling code and only shows appropriate error messages to the user.
  • The add-on does not log debug information to the JavaScript console; use Stackdriver logging instead.
  • The add-ons script project includes an onInstall(e) function that populates the menu, usually by calling onOpen(e).
  • To comply with the limitations of the AuthMode.NONE, the script project's global code and the AuthMode.NONE path of the onOpen(e) function should not contain calls to services that require authentication.
  • The script should not use libraries excessively, because libraries can cause the add-on to lose performance.

Required assets

Before you can publish your add-on, you must construct a listing for the G Suite Marketplace. The listing consist of several assets: images, URLs, and text. Some assets are required for the listings, and others are optional but can help provide users with more information about your add-on.

Before you begin the publishing process, make sure you assemble all required assets listed in the G Suite Marketplace SDK guide.

Publishing instructions

Once you have reviewed the development checklist and ensured your add-on is ready to publish and that you have all the required assets, you can start the publishing process. To publish an editor add-on for the first time, follow the steps below.

Step 1: Create a script version

Create a version of your add-on. This version is the snapshot of code that your published add-on uses. Record the version number—it is required when configuring the G Suite Marketplace listing.

During add-on authorization, users see a dialog that describes the requested permissions. You can customize this dialog to some extent by configuring the add-on's OAuth consent screen using the assets you collected. Some of the form elements are optional, but providing them can improve your add-on's user experience.

Step 3: Enable the G Suite Marketplace SDK

The G Suite Marketplace SDK lets you configure the appearance of your G Suite Marketplace listing. Be sure to enable the "G Suite Marketplace SDK" in your add-on script project.

You may be prompted during this process to accept the Google APIs Terms of Service and the G Suite Marketplace SDK Terms of Service. Read the terms carefully, then check the box and click Accept to continue the publishing procedure.

Once you have enabled the G Suite Marketplace SDK for your script project, you can use the SDK control panel to configure the SDK.

Step 4: Configure the G Suite Marketplace SDK

The G Suite Marketplace SDK settings page has four panels: Overview, Configuration, Publish, and Usage. To define your editor add-on's listing and start a publication request, you must do the following:

  1. If it isn't open already, open your add-on's Cloud Platform project and, in the G Suite Marketplace SDK settings, select the Configuration panel. This panel contains a form where you provide information about your add-on.
  2. Fill in the configuration form using the corresponding assets you collected. Some of the form elements are optional, but providing them can improve your add-on's user experience. Do the following as you are completing the form:

    • Where indicated, provide localized assets for each language you intend to publish the add-on in.
    • Make sure the Enable individual install checkbox is checked if you want to allow individual installs.
    • Where indicated, include every scope your add-on script project uses. If you have set explicit scopes, include all the scopes listed in your add-on project's manifest.
    • In the Extensions section, check the add-on extension checkbox for the type corresponding to your add-on (do not check the other boxes). This causes text fields to appear. In these text fields enter the script project key and version number.
    • If your are publishing from a domain account, select your add-on's visibility where indicated. Selecting My Domain makes your add-on a private add-on.

  3. Verify that the information you have entered in the form is correct, then click Save changes.

This completes the process of creating a G Suite Marketplace listing for your add-on.

If you selected Private visibility for the add-on, the add-on should become available for use after a few minutes. If you selected the Public visibility setting, however, your add-on requires review. See Add-on review for more information.

Bundling with an existing G Suite Marketplace app

If you have already developed and published a G Suite Marketplace app that is closely related to your add-on, you can bundle your add-on with the Marketplace app. This creates a joint listing in the G Suite Marketplace. When administrators install and authorize your app, the add-on is installed and authorized at the same time.

Bundling requires you to have edit access to the Marketplace app's Cloud Platform (GCP) project so that you can make adjustments to its settings.

To bundle your add-on with an existing Marketplace app, do the following:

  1. Switch your add-on to use the Marketplace app's GCP project.
  2. Next, you need to update the G Suite Marketplace listing for the existing app to include information about the add-on, as described in Step 4: Configure the Marketplace SDK. Since you already have a Marketplace listing for your existing app, you edit the listing instead of creating a new one.
  3. In the Marketplace listing, make sure that the description explains that installing this app also installs an add-on.
  4. Make sure that the OAuth scopes section lists all scopes required by the Marketplace app and the add-on. If you need to add any scopes to support the add-on, remember that admins who have previously installed the Marketplace app need to reauthorize it.
  5. Check the box next to Enable Docs Add-on extension, Enable Sheets Add-on extension, Enable Slides Add-on extension, or Enable Forms Add-on extension, as appropriate and fill out the resulting text fields.
  6. Click Save changes. If there are no error messages, close the SDK configuration form.

Bundling add-ons together

It is possible to bundle add-ons of different types together. This requires them to share a GCP project and G Suite Marketplace listing, as described above. Choose a standard GCP project to use for the bundled add-ons, and switch each add-on to use that GCP project.