Users must install and authorize an add-on before they can open and use it. Since these steps are the first part of the add-on user experience, you should understand them before you start creating your own add-ons.
This documentation section describes how users can install, authorize, and start using add-ons.
Install add-ons
Before you can use an add-on, you must install it. Once installed, the add-on becomes available in the Google Workspace host application it extends.
You can install published add-ons from the Google Workspace host application or from the Google Workspace Marketplace. Domain administrators can also install add-ons on behalf of their users from the Google Workspace Marketplace. You can also install unpublished add-ons you're developing so that you can test them. Before you can use an installed add-on for first time, you must authorize it.
For more details, see Publish add-ons.
Authorize add-ons
After installing an add-on, it becomes available in the Google Workspace host application it extends. The first time a user attempts to use the add-on the host application presents them with an authorization card or dialog. This card explains what the add-on needs permission to do for the user, such as accessing the content of the current Google Sheet. The user can then grant those permissions and allow the add-on to proceed. If the user denies the add-on authorization, they can't use the add-on.
Editor add-ons use an authorization model that differs from Google Workspace add-ons. Because Editor add-ons operate on Google Drive files, the editor authorization model defines various authorization modes that result when add-ons are used with individual files. When developing Editor add-ons, it's important to understand the different modes and how an add-on moves between them.
Authorize published add-ons
After you install a published add-on, the authorization flow begins immediately:
- You are prompted to Choose an account to install the add-on to.
- You are then presented with the list of authorizations the add-on requires to operate, so that you know what it attempts to do. Review this list carefully, and if you still want to grant authorization, click Allow. This enables the add-on for use.
- You can now run it from the host application it extends. If the application was already open in a browser tab, you may need to refresh the tab before the add-on becomes available.
If the add-on you've installed is later updated and requires additional authorizations you have not yet granted, you are prompted to provide those permissions the next time you use the add-on.
Authorize unpublished Google Workspace add-ons
Unpublished add-ons don't have the same authorization flow as published add-ons because they aren't listed in the Google Workspace Marketplace yet. After installing an unpublished add-on, you aren't immediately asked to authorize. Instead, the authorization flow starts when you first attempt to use the add-on.
When an add-on is run, it determines if any user authorization is needed. If authorization is necessary, the add-on presents an authorization card. Authorization is always required the first time an add-on executes, and may also be required if a new version of the add-on uses a service not previously authorized. The Authorize Access button provides a dialog window for the user to Allow or Deny authorization for the add-on.
Authorize non-Google services for a Google Workspace add-on
It's possible for a Google Workspace add-on to connect to a third-party service that itself requires authorization. Google Workspace add-ons that connect to such services require two separate actions from the user:
- Authorization of the add-on itself when the add-on is installed or first started.
- Authorization of the non-Google service when it is first accessed.
If a Google Workspace add-on you are developing needs to access a non-Google service using OAuth, you must configure the connection for that service when building the add-on.
For more information, refer to Connect your Google Workspace add-on to a third-party service.
Third-party conferencing systems
Google Workspace add-ons that extend Google Calendar can also add additional conferencing solutions that let users select a third-party conferencing system when editing Google Calendar events. If your add-on provides conferencing options that require the user to log into them, your add-on must give the user the ability to do so.
If a user attempts to create a conference with your add-on without a necessary
sign in, the conference solutions's onCreateFunction method
should return a
ConferenceData
object containing an
ConferenceError
with an
authentication URL.
Upon receiving this object, Google Calendar creates a LOG IN button in the event edit UI that links to the authentication URL the add-on provides. Users can then use this button to log into the third-party system prior to using the add-on further.
See Creating third-party conferences
for more details on handling authorization using ConferenceError.
Authorize unpublished Editor add-ons
It's a best practice to test Editor add-ons as you develop them. The authorization flow is identical to that for published Editor add-ons, except that the flow starts when you first attempt to test the add-on. If you later retest the same add-on, you aren't prompted for authorization again.
Unauthorize add-ons
When developing add-ons, it can be useful to unauthorize them so you can retest the authorization flow.
You can unauthorize an add-on by doing the following:
- Open your account security console.
- Locate and click the add-on you wish to unauthorize.
- Click Remove Access.
When you run the add-on again after unauthorizing it, the authorization flow is presented again.
Uninstall add-ons
To uninstall an add-on that you installed from the Google Workspace Marketplace, refer to Uninstall a Marketplace app or add-on.
To uninstall an unpublished add-on built in Apps Script, refer to Uninstall an unpublished add-on.