Page Summary

outlined_flag

• Google Workspace add-ons provide custom interfaces within Google Docs, Sheets, and Slides, enabling you to display relevant information, automate tasks, and connect to external systems.

• Add-ons offer various interface types including homepages (common or editor-specific), REST API interfaces (requiring file access), and link previews for third-party services.

• You can build add-on interfaces by configuring the manifest, implementing trigger functions (like homepageTrigger or onFileScopeGrantedTrigger), and handling user interactions through callback functions.

• Editor-specific homepages and REST API interfaces can be tailored to the context of the open document using event objects containing information about the client and file access permissions.

• Link preview interfaces require configuration in the manifest and a function to generate preview cards, potentially including an authorization flow for third-party services.

With Google Workspace add-ons, you can provide customized interfaces within the Editors,including Google Docs, Sheets, and Slides. This lets you provide the user withrelevant information, automate tasks, and connect third-party systems to theEditors.

Accessing the add-on UI

You can open a Google Workspace add-on in the Editorsif its icon appears in the Google Workspace quickaccess side panel on the right side of the Docs, Sheets, and Slides userinterfaces.

A Google Workspace add-on can present the following interfaces:

• Homepage interfaces: If the add-on’s manifestincludes the triggerEDITOR_NAME.homepageTrigger for the Editor the user opens the add-on in,the add-on builds and returns ahomepage card specifically forthat Editor. If the add-on’s manifest doesn't include theEDITOR_NAME.homepageTrigger for the Editor the user opensit in, a generic homepage card is displayed instead.

• REST API interfaces: If the add-on uses RESTAPIs, you can include triggers that request per-file access to a documentusing thedrive.file scope. Once granted, another trigger calledEDITOR_NAME.onFileScopeGrantedTrigger executes anddisplays an interface specific to the file.

• Link preview interfaces: If your add-onintegrates with a third-party service, you can build cards that previewcontent from your service's URLs.

Building interfaces for Editor add-ons

Build Editor add-on interfaces for the Editors by following these steps:

1. Add the appropriateaddOns.common,addOns.docs,addOns.sheets,andaddOns.slides fields to the add-on script projectmanifest.
2. Add any requiredEditor scopes toyour script project manifest.
3. If you're providing anEditor-specific homepage,implement theEDITOR_NAME.homepageTrigger function to build the interface. If not, use thecommon.homepageTrigger interface to build a common homepage for your host apps.
4. If you use REST APIs, implement thedrive.file scope authorization flowandEDITOR_NAME.onFileScopeGrantedTrigger trigger function to display an interface specific to the open file. For moreinformation, seeREST API interfaces.
5. If you’re configuring link previews from a third-party service, implementthehttps://www.googleapis.com/auth/workspace.linkpreview scope authorization flow andlinkPreviewTriggers function. For more information, seeLink preview interfaces.
6. Implement the associated callback functions needed to respond to the user'sUI interactions, such as button clicks.

Editor homepages

You must provide a homepage trigger function in your add-on's script projectthat builds and returns a singleCard or an array ofCard objects that make up the add-on’s homepage.

The homepage trigger function is passed anevent objectas a parameter that contains information such as the client's platform. You canuse the event object data to tailor the construction of the homepage.

You can present a common homepage or a homepage that is specific to the Editorthe user opens your add-on in.

Display the common homepage

To show your add-on's common homepage in the Editors, include the appropriateEditor fields, such asaddOns.docs,addOns.sheets,oraddOns.slides,in the add-on's manifest.

The following example shows theaddons portion of a Google Workspace add-onmanifest. The add-on extends Docs, Sheets, and Slides, and shows the commonhomepage in each host app.

 "addOns": {    "common": {      "name": "Translate",      "logoUrl": "https://www.gstatic.com/images/branding/product/1x/translate_24dp.png",      "layoutProperties": {        "primaryColor": "#2772ed"      },      "homepageTrigger": {        "runFunction": "onHomepage"      }    },    "docs": {},    "sheets": {},    "slides": {}  }}

Display an Editor-specific homepage

To present a homepage specific to an Editor, add theEDITOR_NAME.homepageTrigger to the add-onmanifest.

The following example shows theaddons portion of a Google Workspace add-on manifest.The add-on is enabled for Docs, Sheets, and Slides. It displays the commonhomepage in Docs and Slides, and a unique homepage in Sheets. The callbackfunctiononSheetsHomepage builds the Sheets-specific homepage card.

 "addOns": {    "common": {      "name": "Translate",      "logoUrl": "https://www.gstatic.com/images/branding/product/1x/translate_24dp.png",      "layoutProperties": {        "primaryColor": "#2772ed"      },      "homepageTrigger": {        "runFunction": "onHomepage"      }    },    "docs": {},    "slides": {},    "sheets": {     "homepageTrigger": {       "runFunction": "onSheetsHomepage"     },  }}

REST API interfaces

If your add-on uses REST APIs, such as theGoogle Sheets API,you can use theonFileScopeGrantedTrigger function to display a new interfacespecific to the file that's open in the Editor host app.

You must include thedrive.file scope authorization flow to use theonFileScopeGrantedTrigger function. To learn how to request thedrive.filescope, seeRequest file access for current document.

When a user grants thedrive.file scope, theEDITOR_NAME.onFileScopeGrantedTrigger.runFunction fires. When the trigger fires, it executes the contextual trigger functionspecified by theEDITOR_NAME.onFileScopeGrantedTrigger.runFunction field in theadd-on manifest.

To create a REST API interface for one of the Editors, follow the steps below.ReplaceEDITOR_NAME with the Editor host app you choose touse, for example,sheets.onFileScopeGrantedTrigger.

1. Include theEDITOR_NAME.onFileScopeGrantedTrigger in the appropriate Editor's section of your manifest. For example, if youwant to create this interface in Google Sheets, add the trigger tothe"sheets" section.
2. Implement the function named in theEDITOR_NAME.onFileScopeGrantedTriggersection. This function accepts anevent object as an argument and must return either a singleCard object or an array ofCard objects.
3. As with any card, you must implement the callback functions used to providewidget interactivity for the interface. For example, if you include a buttonin the interface, it should have an attachedAction and an implemented callback function that runs when the buttonis clicked.

The following example shows theaddons portion of a Google Workspace add-on manifest.The add-on uses REST APIs, so theonFileScopeGrantedTrigger is included forGoogle Sheets. When a user grants thedrive.file scope, the callback functiononFileScopeGrantedSheets builds a file-specific interface.

"addOns": {   "common": {     "name": "Productivity add-on",     "logoUrl": "https://www.gstatic.com/images/icons/material/system_gm/1x/work_outline_black_18dp.png",     "layoutProperties": {       "primaryColor": "#669df6",       "secondaryColor": "#ee675c"     }   },   "sheets": {     "homepageTrigger": {       "runFunction": "onEditorsHomepage"     },     "onFileScopeGrantedTrigger": {       "runFunction": "onFileScopeGrantedSheets"     }   }

Link preview interfaces for third-party services

To turn on link previews for a third-party service, you must configure linkpreviews in your add-on’s manifest and create a function that returns a previewcard. For services that require user authorization, your function must also invokethe authorization flow.

For steps to turn on link previews, seePreview links with smart chips.

Event objects

An event object is created and passed to trigger functions, such asEDITOR_NAME.homepageTrigger orEDITOR_NAME.onFileScopeGrantedTrigger. The trigger function uses the information in theevent object to determine how to construct add-on cards or otherwise control theadd-on behavior.

The full structure of event objects is described inEvent objects.

When an Editor is the acting host app of the add-on, the event objects includeDocs,Sheets, orSlidesevent object fields that carry client information.

If the add-on doesn’t havedrive.file scope authorization for the current useror document, the event object only contains thedocs.addonHasFileScopePermission,sheets.addonHasFileScopePermission, orslides.addonHasFileScopePermission field. If the add-on does haveauthorization, the event object contains all Editor event object fields.

The following example shows an Editor event object that is passed to asheets.onFileScopeGrantedTrigger function. Here, the add-on has thedrive.file scope authorization for the current document:

`        {          "commonEventObject": { ... },          "sheets": {            "addonHasFileScopePermission": true,            "id":"A_24Q3CDA23112312ED52",            "title":"How to get started with Sheets"          },          ...        }