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 no
drive.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
and
addOns.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 the
common.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
scope
Ensure 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 single
Card
object or an array of
Card
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"
},
...
]
},
...
}