Build Google Workspace Add-ons

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

  1. Set up your add-on's projects and choose an owner and collaborators.
  2. Design your add-on's appearance and behavior.
  3. Configure the add-on's project manifest or deployment resource.
  4. Write code to define the add-on's appearance and behavior.
  5. Verify your add-on's OAuth scopes.
  6. Test the add-on within the host applications it extends.
  7. Publish the add-on.

Set up your add-on's projects and choose an owner and collaborators

If you build your add-on in Apps Script, you create both an Apps Script project and a Google Cloud project. If you build your add-on in a language other than Apps Script, you only need to create a Google Cloud project.

Before starting add-on development, choose a single user account to own the projects and decide which other accounts are collaborators. The owner of the projects creates and manages the project files and associated settings, while collaborators can help with coding and testing.

Apps Script projects

You can build your add-on's Apps Script project files in a shared drive so that no single account has sole ownership. Placing your add-on script file in a shared drive ensures that multiple collaborators have access to the script project.

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

To create an Apps Script project, see Script projects.

Google Cloud projects

We recommend that you add collaborators to the add-on's Cloud project. This helps ensure someone on your team can always access the add-on's Cloud settings.

To create a Google Cloud project, see Create a Google Cloud project.

Design your add-on appearance and behavior

Decide what you want your add-on to look like and how it should behave before you start building it. 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.

Refer to the Google Workspace Add-on style guide for guidelines on how to design your add-on user experience.

Configure the add-on project manifest

In Apps Script projects, the project manifest is a special JSON file. 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.

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

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

Code the add-on

You must implement a card-based interface for the add-on. Use Apps Script's Card service or if you're writing in another code language, return properly formatted JSON for the interface to render as cards.

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.

Construct 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.

In Apps Script, 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 CardBuilder.build() 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-ons 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 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, explicitly set the add-on scopes in order to ensure the add-on uses the least-permissive set of scopes possible. You 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 appearance 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 preparation and time to complete.

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

See Publishing Google Workspace Add-on for more details.