In most cases, you must authorize an add-on before you can use it. For many Apps Script projects such as web apps, authorization is straightforward—the script project asks for any missing permissions it needs when you attempt to use it. Once authorized, you can use the script project freely. Everyone using the script project authorizes it separately.
The authorization model for Editor Add-ons is more complex. Because these add-ons function on files residing in Google Drive—files that can be shared with others—you must build Editor Add-ons with the different authorization modes in mind. The Google Docs editors also provide an Add-ons menu in their UIs which is populated by the add-ons you've installed—even if you haven't authorized those add-ons yet. This adds some additional complexity to the authorization model.
Authorization model
Two properties of Editor Add-ons make them especially easy to share and use:
- Once you get an Editor Add-on from the store, you see it in the add-ons menu for every document, form, presentation, or spreadsheet that you open or create. Collaborators won't see the add-on except in documents, forms, presentations, or spreadsheets where you actually use it.
- Once you use an Editor Add-on in a document, form, presentation, or spreadsheet, your collaborators also see it in the add-ons menu, but just for that file (unless they have also installed that add-on).
This sharing model feels natural for most users. However, because an
Editor Add-on automatically runs its onOpen(e)
function to
add menu items when a Google Docs editor opens, the behavior above adds
some complexity to Apps Script's
authorization rules. After all, users wouldn't be comfortable with an
add-on accessing personal data every time they open a
document, form, presentation, or spreadsheet. This guide
should help you understand what your code can do and when.
Installed versus enabled
If you see an Editor Add-on in the menu, it's in one (or both) of two states: installed and enabled. An Editor Add-on is installed for a particular user after they choose the add-on in the store and authorize it to access their Google data. By contrast, an add-on is enabled in a given document, form, presentation, or spreadsheet when anyone uses it there. If two people collaborate and one of them uses an add-on, it's installed for the one user and enabled for the file.
The table below summarizes the two states. Note that when testing a script as an add-on you can choose to run the test in either or both of these states.
Installed | Enabled | |
---|---|---|
Applies to | User | Document, form, presentation, or spreadsheet |
Caused by | Getting an add-on from the store | Getting an add-on from the store while using
that document, form, presentation, or spreadsheet, or Using a previously installed add-on in that document, form, presentation, or spreadsheet |
Menu visible to | Only that user, in all documents, forms, presentations, or spreadsheets they open or create | All collaborators on that document, form, presentation, or spreadsheet |
onOpen(e) runs in |
AuthMode.NONE (unless also enabled, in which case
AuthMode.LIMITED) |
AuthMode.LIMITED |
Authorization modes
An Editor Add-on automatically runs its onOpen(e)
function to add menu items when a document, form, presentation, or spreadsheet
opens—but to protect users' data, Apps Script restricts
what the onOpen(e)
function can do. If the add-on
hasn't been used in the current document, form, presentation, or spreadsheet, these
restrictions become more severe.
Specifically, the installed and enabled states determine which authorization
mode the onOpen(e)
function runs in. Apps Script passes the authorization mode
as the authMode
property of the Apps Script
event parameter, e
; the value of
e.authMode
corresponds to a constant in the Apps Script
ScriptApp.AuthMode
enum.
If an Editor Add-on is enabled in the current document,
form, presentation, or spreadsheet, onOpen(e)
runs in
AuthMode.LIMITED
. If the add-on isn't enabled and is
only installed, onOpen(e)
runs in AuthMode.NONE
.
The concept of authorization modes applies to all Apps Script executions—such
as running from the script editor, from a menu item, or from an Apps Script
google.script.run
call—although
the e.authMode
property can only be inspected if the script runs as the result
of a trigger like onOpen(e)
, onEdit(e)
or onInstall(e)
. Custom functions
in Google Sheets use their own authorization mode, AuthMode.CUSTOM_FUNCTION
,
which is similar to LIMITED
but has slightly different restrictions. The
rest of the time, scripts run in AuthMode.FULL
, as detailed in the table
below.
NONE |
LIMITED |
CUSTOM_FUNCTION |
FULL |
|
---|---|---|---|---|
Occurs for | onOpen(e) (if the user has installed an
add-on but not enabled it in the document, form,
presentation, or spreadsheet) |
onOpen(e) (all other times)onEdit(e) (only in Sheets) |
Custom functions | All other times, including: installable triggers onInstall(e) google.script.run |
Access to user data | Locale only | Locale only | Locale only | Yes |
Access to document, form, presentation, or spreadsheet | No | Yes | Yes — read-only | Yes |
Access to user interface | Add menu items | Add menu items | No | Yes |
Access to Properties |
No | Yes | Yes | Yes |
Access to Jdbc , UrlFetch |
No | No | Yes | Yes |
Other services | Logger Utilities |
Any services that don’t access user data | Any services that don’t access user data | All services |
The complete lifecycle
If an add-on is either installed for the current user
or enabled in the current file, the
add-on is loaded in the document, form, presentation,
or spreadsheet, which causes it to appear in
the add-ons menu and start listening for the
simple triggers onInstall(e)
,
onOpen(e)
, and onEdit(e)
. If a user clicks one of the
add-on’s menu items, it runs.
Installing
When an Editor Add-on is installed from the store, its
onInstall(e)
function runs in AuthMode.FULL
. This allows the
add-on to run a complex setup routine, but it’s
important to also use onInstall(e)
to create menu items, since the
document, form, presentation, or spreadsheet is already open and thus your onOpen(e)
function hasn’t run. For convenience, you can just call onOpen(e)
from
onInstall(e)
, as shown in
this sample:
function onInstall(e) {
onOpen(e);
// Perform additional setup as needed.
}
Opening
When a document, form, presentation, or spreadsheet opens, it loads every
Editor Add-on that the current user has installed or
that any collaborator has enabled in the file, and calls
each of their onOpen(e)
functions. The authorization mode that onOpen(e)
runs in depends on whether an add-on is
installed or enabled.
If an add-on only creates a basic menu, the mode doesn’t matter. This sample
shows what a simple onOpen(e)
might look like:
function onOpen(e) {
SpreadsheetApp.getUi().createAddonMenu() // Or DocumentApp.
.addItem('Insert chart', 'insertChart')
.addItem('Update charts', 'updateCharts')
.addToUi();
}
However, if you want to add dynamic menu items based on stored Apps Script
properties, read the contents of the current
document, form, presentation, or spreadsheet, or perform other advanced tasks, you
need to detect the authorization
mode and handle it appropriately. This sample shows what an advanced onOpen(e)
function might look like, changing its behavior based on the authorization mode:
function onOpen(e) {
var menu = SpreadsheetApp.getUi().createAddonMenu(); // Or DocumentApp.
if (e && e.authMode == ScriptApp.AuthMode.NONE) {
// Add a normal menu item (works in all authorization modes).
menu.addItem('Start workflow', 'startWorkflow');
} else {
// Add a menu item based on properties (doesn't work in AuthMode.NONE).
var properties = PropertiesService.getDocumentProperties();
var workflowStarted = properties.getProperty('workflowStarted');
if (workflowStarted) {
menu.addItem('Check workflow status', 'checkWorkflow');
} else {
menu.addItem('Start workflow', 'startWorkflow');
}
}
menu.addToUi();
}
Running
When someone clicks one of an add-on's menu items,
Apps Script first checks to
see whether the user has installed the add-on, and
prompts them to do so if not. If the user has authorized the
add-on, the script runs the function that
corresponds to the menu item in AuthMode.FULL
. The
add-on also becomes enabled in the document, form,
presentation, or spreadsheet if it wasn’t already.