Google Workspace Add-ons can provide customized interfaces when the user is using Google Drive. This lets you provide the user with additional relevant information, automate tasks, and connect third-party systems to Google Drive.
Accessing the add-on UI
You can open a Google Workspace Add-on in Google Drive if its icon appears in the icon column on the right side of the Drive user interface. A Google Workspace Add-on can define a homepage interface, an item select interface, or both:
- If a user clicks the add-on icon while in Google Drive,
the add-on executes
the corresponding
drive.homepageTrigger
function (if present). This function builds and returns a homepage card to Google Drive for display. If nodrive.homepageTrigger
function is defined, a generic homepage card is displayed instead. - If the user selects one or more items in Google Drive and then clicks the add-on
icon, or selects items while the add-on is open, the add-on executes the corresponding
drive.onItemsSelectedTrigger
contextual function (if present). This function builds the add-on's Google Drive contextual "items selected" interface and returns it to Google Drive for display.
Building the add-on Drive interface
You can build interfaces that extend Google Drive by following these general steps:
- Decide whether you want your add-on to have a Drive-specific homepage. Also decide if you want to provide a contextual interface for when the user selects Drive items.
- Add the appropriate
addOns.common
andaddOns.drive
fields to the add-on script project manifest, including any Drive scopes required. - If you are providing a Drive-specific homepage,
implement the
drive.homepageTrigger
function to build this interface. You can also choose to use thecommon.homepageTrigger
interface for multiple Google Workspace hosts. - If you are providing a Drive contextual item selection interface, you must
implement a
drive.onItemsSelectedTrigger
contextual trigger function to build this interface. See Drive contextual interface for items selected) for details. - Implement the associated callback functions needed to respond to the user's UI interactions, such as button clicks.
Drive homepages
Google Drive supports displaying Google Workspace Add-on
homepages.
To show your add-on's common homepage in Google Drive simply make sure there
is a addOns.drive
field
in the add-on's manifest.
Alternatively, add a
drive.homepageTrigger
to the add-on manifest to provide a Drive-specific homepage.
In either case, you must provide the name of a homepage trigger function in your
add-on's script project. This function is automatically called to build the
Drive homepage when it is needed. You must implement this function to build and
return a single
Card
or an array of
Card
objects that make up the homepage. The homepage trigger function is passed an
event object
as a parameter that contains some general information such as the client's
platform. You can use the event object data to tailor the construction of the
homepage.
Drive contextual interface for items selected
Google Drive relies on a contextual trigger to determine what interface
(if any) to display when the user selects one or more Google Drive items. When the
trigger fires, it executes the contextual trigger function specified by the
drive.onItemsSelectedTrigger.runFunction
field in the add-on manifest.
To create a contextual item selection interface for Drive, you must do the following:
Ensure the add-on's manifest includes the
https://www.googleapis.com/auth/drive.addons.metadata.readonly
scopeEnsure the manifest includes a
drive.onItemsSelectedTrigger
section.Implement the function named in the
drive.onItemsSelectedTrigger
field. This function accepts an event object as an argument and must return either a singleCard
object or an array ofCard
objects.As with any card, you must implement any callback functions used to provide widget interactivity for the interface. For example, if you include a button in the interface, it should have an attached Action and an implemented callback function that run when the button is clicked.
Event objects
An event object is created and passed
to the drive.homepageTrigger
or drive.onItemsSelectedTrigger
trigger function when those functions are called. The trigger function can use
the information in this event object to determine how to construct add-on cards
or otherwise control the add-on behavior.
The full structure of event objects is described in Event objects. When Drive is the acting host app of the add-on, contextual event objects include the Drive event object field that carries Drive-specific client information.
Contextual Drive event objects for item selection triggers include information about the items the user has selected when the trigger fires. When a user selects more than one item in Drive, one of the items is deemed to be one of primary interest; this item is referred to as the active cursor item.
The following example shows a
Drive event object
that is passed to a
drive.onItemsSelectedTrigger
function:
{
"commonEventObject": { ... },
"drive": {
"activeCursorItem":{
"addonHasFileScopePermission": true,
"id":"0B_sX1fXRRU6Ac3RhcnRlcl9maWxl",
"iconUrl": "https://drive-thirdparty.googleusercontent.com...",
"mimeType":"application/pdf",
"title":"How to get started with Drive"
},
"selectedItems": [
{
"addonHasFileScopePermission": true,
"id":"0B_sX1fXRRU6Ac3RhcnRlcl9maWxl",
"iconUrl":"https://drive-thirdparty.googleusercontent.com...",
"mimeType":"application/pdf",
"title":"How to get started with Drive"
},
...
]
},
...
}