Upgrading your published add-ons

If you've already built and published an add-on to extend Gmail or Calendar, you can upgrade it into a G Suite add-on. The instructions in this page detail how to add G Suite functionality to your existing Gmail or Calendar add-ons and then publish your upgraded add-on so it can be discovered and installed.

You can transfer the new functionality into your original add-on to retain your G Suite Marketplace listing, installs, and users. Upgrading also allows you to take advantage of new G Suite add-on features such as homepages.

Step 1: Make a copy of your add-on Apps Script project

Your upgraded add-on uses the same Google Cloud project as your published add-on, but it's important to create and use a copy of the underlying Apps Script project so that your existing users aren't affected while you're testing the upgraded version. Upgrading a copy of the original script project also means you can always access the original code, and can redeploy it later if necessary.

  1. Open your existing Gmail add-on or Calendar conferencing add-on Apps Script project.
  2. At the top, click File > Make a copy.
  3. At the top of the copied Apps Script project, click Resources > Cloud Platform project.
  4. Enter the same project number associated with your existing, published add-on Apps Script project.
  5. Click Set project > Close.

Step 2: Integrate G Suite add-on features

You must design and implement any G Suite add-on features you want to add to your add-on.

  1. Plan what content to show in your add-on's homepage cards and whether they should appear in Gmail, Calendar, Drive, or any combination of the three hosts. If you want a homepage in more than one host, decide whether if it can be the same homepage or if you want custom homepage cards for each host.
  2. In your copied add-on Apps Script project, build your homepage cards with homepageTrigger functions. Make sure to include any supporting functions or logic needed to control your new homepage interfaces.
  3. Consider adding contextual cards triggered by a user's action, like opening a Gmail message thread or Calendar event.

  4. Update any accessing of event objects in your add-on (in widget callback functions or in contextual trigger functions) to use the updated event object structure. The new structure still contains the same event object fields used by Gmail and Calendar conferencing add-ons, but those original fields are deprecated and will eventually be removed.

Step 3: Update your add-on's manifest

The way in which configuration information is stored in the manifest structure of G Suite add-ons has changed considerably from the structure Gmail add-ons and Calendar conferencing add-ons use. As you upgrade your add-on, you must update your add-on's Apps Script project's manifest fields according to the tables below. You must update all relevant subproperties to the new addOns property.

Be sure to also update your manifest's oauthScopes field as needed to reflect the permissions your updated add-on requires.

To learn more about G Suite Add-on manifests, see Manifests.

Gmail add-ons

Original manifest field Action required
gmail.composeTrigger Move to addOns.gmail.composeTrigger.
gmail.contextualTriggers[] Move the list to addOns.gmail.contextualTriggers[].
gmail.logoUrl Move to addOns.common.logoUrl.
gmail.name Move to addOns.common.name.
gmail.openLinkUrlPrefixes[] Move the list to addOns.common.openLinkUrlPrefixes[].
gmail.primaryColor Move to addOns.common.layoutProperties.primaryColor.
gmail.secondaryColor Move to addOns.common.layoutProperties.secondaryColor.
gmail.universalActions[] Move the list to addOns.common.universalActions[].
gmail.universalActions[].text Move each gmail.universalActions[].text field to a corresponding addOns.common.universalActions[].label field.
gmail.useLocalFromApp Move to addOns.common.useLocaleFromApp.

Calendar conferencing add-ons

Original manifest field Action required
calendar.name Move to addOns.common.name.
calendar.logoUrl Move to addOns.common.logoUrl.
calendar.conferenceSolution[] Move to addOns.calendar.conferenceSolution[].

Step 4: Test your upgraded add-on

To test your upgraded add-on before publishing, see Testing G Suite add-ons.

Step 5: Request reviews of your upgraded add-on

All G Suite add-ons, whether an upgraded add-on or one built from scratch, must be approved before they can be listed in the G Suite Marketplace.

Follow these steps to submit your add-on for review:

  1. Make sure your add-on fulfills all of the add-on publishing requirements, with special attention to the user data protection requirements.

  2. Create a versioned deployment of your G Suite add-on (in the new Apps Script project) using the version of the code you want to publish. Don't attempt to publish using a head deployment.

  3. If you added new scopes while upgrading your add-on, you must request OAuth verification. For example, if your Gmail add-on uses new Drive or Calendar scopes in the G Suite add-on version, you must submit those new scopes for verification. Verification often takes a few days to complete, so start the process as early as possible. Make sure your add-on is verified before proceeding to Step 6.

Step 6: Make your upgraded add-on available

  1. Open the G Suite Marketplace SDK control panel.

  2. On the left, click Configuration. This panel contains a form where you provide information about your add-on.

  3. Update the short description, detailed description, and screenshots of your listing to reflect the new functionality of the G Suite add-on. If you have another app listed in G Suite Marketplace, we recommend you add the "for G Suite" suffix to your G Suite add-on to distinguish it from other listings in the G Suite Marketplace.

  4. Under Extensions, click the Upgrade to G Suite Add-on button. In the textbox that appears, enter the new deployment ID you created for your G Suite add-on in the previous step. If your deployment ID is valid, a list of supported hosts appears.

  5. If you added new scopes to your G Suite add-on, make sure you add them to the OAuth 2.0 scopes section in the Configuration page. The scopes listed in that section should exactly match the scopes listed in your add-on's manifest.

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

  7. If you added support for additional hosts to your add-on, re-approval of the add-on is required. Until your add-on is re-approved, the G Suite Marketplace won't display your add-on's listing and no new installs are allowed. Existing installed users can continue to use the add-on while the approval process moves forward. Your add-on's status is listed as Under review in the Publish panel while the approval process is underway. The Add-ons review team aims to review and approve the listing within 3 business days.

If you have questions or encounter an issue during this G Suite add-on upgrade process, contact us.

FAQ

The following are frequently-asked questions regarding add-on upgrades:

Can I upgrade my editor add-on?

Not at this time. The G Suite add-on experience isn't available for the editors, like Docs, Sheets, and Slides, but existing editor add-ons continue to function normally.

Can I build a separate G Suite add-on and keep my existing add-ons?

You're welcome to build additional G Suite add-ons under different brand names, but we don't permit separate Gmail or Calendar conferencing add-ons under the same brand name as your G Suite add-on. If you have questions or want to request an exception, contact us.

Will my users need to re-authorize the add-on after it's upgraded?

As long as your G Suite add-on uses the same underlying Cloud Platform (GCP) project, with an associated OAuth client ID, your users won't need to reauthorize permissions they've previously authorized for your original add-on. However, if you add new scopes during the upgrade process, your users must authorize those new scopes the first time they use the G Suite version of your add-on.

Can I upgrade my Chrome extension to a G Suite add-on and transfer users?

No. You can't transfer a Chrome extension's users, installs, and listing reviews. You must create a new G Suite add-on and direct users of your Chrome extension to the G Suite Marketplace.

Can I bundle multiple add-ons with my G Suite add-on?

No. Collecting multiple applications or add-ons together using a single Google Cloud Platform project and a single store listing isn't supported. The G Suite Marketplace doesn't support multi-install or bundling for any type of add-on.