Alternate Runtimes for Google Workspace Add-ons is coming soon. Learn more.

Building Google Workspace add-ons

When you want to build a new Google Workspace add-on, follow this general procedure:

  1. Choose an add-on project owner and collaborators.
  2. Create an Apps Script project.
  3. Design your add-on appearance and behavior.
  4. Configure the add-on project manifest.
  5. Write code to define the add-on's appearance and behavior, using the built-in Apps Script Card service.
  6. Verify your add-on's OAuth scopes.
  7. Test the add-on within the host applications it extends.
  8. Publish the add-on.

Choose a project owner and collaborators

Before starting add-on development, choose a single user account to own the project, and decide which other accounts are collaborators. The owner of the project creates and manages the Apps Script project file and associated settings, while collaborators can help with coding and testing. Alternatively, you can decide to build the add-on project files in a shared drive so that no single account has sole ownership.

When you publish an add-on, a single user account acts as the publisher (even if the project is in a shared drive). The publishing account must have edit access to the add-on script project, but it doesn't need to be project owner.

It's very important to avoid situations where you lose access to an add-on's code or settings because the owner of the project left your organization.

To prevent losing access to add-on code, we encourage you to use shared drives when you collaborate on an add-on. Placing your add-on script file in a shared drive allows you to easily ensure that multiple collaborators always have access to the add-on project.

It is also recommended that you add collaborators to the script project's Cloud Platform (GCP) project. This helps ensure someone on your team always can access the add-on's Cloud settings.

Create a script project

A Google Workspace add-on is a standalone Apps Script project. The standalone script guide provides instructions to create new projects. You can also just open a new script. If you do this, the project file (initially named Untitled project) is placed in your root Drive folder.

If you've decided to use a shared drive for collaboration, make sure the shared drive is created and your collaborators are given access. Then create or move the script project into the shared drive.

Design your add-on appearance and behavior

Spend some time deciding what you want your add-on to look like, and how it should behave. Consider what use cases the add-on should attempt to provide solutions for. Start with a simple design to get working first, then add more refinements.

Configure the add-on project manifest

The add-on project manifest is a special JSON file used in Apps Script projects. It specifies a variety of details about the project, such as its library dependencies. For Google Workspace add-ons, the manifest also provides the basic information the host application needs to display the add-on correctly.

As you add code and features to your add-on script project, edit the manifest as needed to produce the required add-on appearance and behavior.

See Manifests for details on how to configure your add-on's manifest.

Code the add-on

Once you have created a script project, you can begin writing code to define the add-on appearance and behavior. You must implement a card-based interface for the add-on, using Apps Script's Card service. You must also implement any trigger functions specified in the add-on manifest. If your add-on connects to a third-party, non-Google service using OAuth, you must configure the OAuth for that service as well.

As you code, refer to the Google Workspace add-on style guide for guidelines on how to design your add-on user experience.

Constructing cards

You define an add-on user interface by creating Card objects and filling them with widgets. Trigger functions specified in your manifest must return either a single Card object or an array of Card objects that represent different 'pages' of the add-on interface. Your add-on can also create and display new cards in response to user actions.

You create cards using the CardBuilder class. Each card requires a CardHeader and one or more CardSections. You should populate each card section with the individual widgets that make up the add-on interface. Interaction widgets, are usually linked to actions to define their interaction behavior.

After you have added all the sections and widgets to your card via its CardBuilder, you must call to create the corresponding Card object.

You can use other built-in Apps Script services such as CalendarApp to retrieve information to display in the add-on cards you build. You can use data fetched from non-Google services.

If your Google Workspace add-on needs access to non-Google APIs that require OAuth, you must configure and connect to that service—see the Connecting to Non-Google Services guide for more details.

Construction order

When building a card, you must build from the top up. That is, you must use this construction order:

  1. Build the widget.
  2. Add the widget to card section.
  3. Repeat until the card section has all of its widgets.
  4. Add the card section to the card.

This is required because when you add a widget to a card or card section, you are actually adding a copy of that widget. Any changes you make to the widget object after adding it are not reflected in the final card.

Universal actions

You can use universal actions to provide context-independent functionality. Universal actions are menu items available in the add-on UI regardless of what card is currently displayed. All defined universal actions always appear in the add-on's card menu.

See Universal actions for more details.

Verify the add-on OAuth scopes

Scopes define what actions the add-on is allowed to take on a user's behalf. It's a best practice for add-ons to only have scopes for actions they must have in order function and nothing more.

In add-on projects you should explicitly set the add-on scopes in order to ensure the add-on uses the least-permissive set of scopes possible. You can define what scopes your add-on uses in the add-on manifest.

See Scopes for more details.

Test the add-on

You can test unpublished add-ons by first installing the unpublished add-on. Once installed and authorized, you can use the add-on in your account and test its appearence and behavior in the host applications it extends. You should verify that the add-on behaves as expected for contexts and user actions.

See Testing Google Workspace add-ons for more details.

Publish the add-on

Publishing your add-on makes it available to others, either publicly or just users in your domain. Before you start the publishing process, be sure to review the publication overview. Publication is a complex process that requires prepration and time to complete.

Google Workspace add-ons are published to the Google Workspace Marketplace. Publicly available add-ons must complete add-on review before they are published.

See Publishing Google Workspace add-on for more details.

Google Workspace add-on example

Google Workspace add-on sidebar

To help you understand how Google Workspace add-ons are constructed, the Google Workspace "Cats" add-on quickstart demonstrates how to build a simple Google Workspace add-on, including homepages, card navigation, and connections to a third-party service. Once you've completed the quickstart, you can install the add-on and experiment with the code.