Build Google Workspace Add-ons

This page provides an overview for how to design, build, and publish Google Workspace Add-ons. This overview explains the following steps:

1. Determine the Google Workspace applications where you want your add-on to be available to users.
2. Set up your add-on's projects and choose an owner and collaborators.
3. Design your add-on's appearance and behavior.
4. Configure the add-on's project manifest or deployment resource.
5. Write code to define the add-on's appearance and behavior.
6. Verify your add-on's OAuth scopes.
7. Test the add-on within one or more Google Workspace applications.
8. Publish the add-on.

Choose Google Workspace host applications

You can configure Google Workspace Add-ons to appear in the following Google Workspace host applications:

• Gmail
• Google Calendar
• Google Docs
• Google Drive
• Google Sheets
• Google Slides

To learn about how to build for Google Workspace applications, see Extend the Google Workspace UI.

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.

Warning: If you don't add collaborators to your add-on projects, it's vital that you transfer ownership of them prior to the owner's account being shut down or removed. Otherwise you could lose access to the add-on code and settings entirely.

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.

Tip: Start with a simple homepage card, then add more widgets, cards, navigation, and other behavior. You can also consider contextual cards triggered by a user's action in the host application, like opening a Gmail message thread or Calendar event.

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.

Note: Failing to call build() after using builder classes in the Card service results in type errors. Trigger functions, for example, must return Card objects. Returning CardBuilder objects instead results in an error.

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

Warning: Only add a widget to a card or card section after you have finished building it. Only add a card section to a card after it has been fully populated with its widgets. Don't change widgets or sections after they are added. If you want to make a change to an added widget, you must recreate the section or card it was added to.

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 to function and nothing more.

In add-on projects, explicitly set the add-on scopes 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.