When you want to build a new Google Workspace Add-on, follow this general procedure:
- 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 the host applications it extends.
- 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'll 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'll 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 allows you to easily ensure that multiple collaborators always 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.
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.
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.
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
class. Each card requires a
and one or more
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
You can use other built-in Apps Script services
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.
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.
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, 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 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 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.
Google Workspace Add-on example
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.