This page provides an overview for how to design, build, and publish Google Workspace Add-ons. This overview explains the following steps:
- Determine the Google Workspace applications where you want your add-on to be available to users.
- Set up your add-on's projects and choose an owner and collaborators.
- Design your add-on's appearance and behavior.
- Configure the add-on's project manifest or deployment resource.
- Write code to define the add-on's appearance and behavior.
- Verify your add-on's OAuth scopes.
- Test the add-on within one or more Google Workspace applications.
- 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.
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 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:
- Build the widget.
- Add the widget to card section.
- Repeat until the card section has all of its widgets.
- 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 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.