An add-on uses a manifest file to configure certain details about the app and its operation.
This documentation covers the details of configuring a manifest for a Google Workspace Add-on.
Manifest structure for Google Workspace Add-ons
Google Workspace Add-ons use the manifest file to define several aspects of the add-on's appearance and behavior.
The manifest properties for Google Workspace Add-ons are
organized under the addOns
section of the manifest object structure.
- For information about Apps Script manifest files, refer to Manifest structure.
- For information about manifest files for add-ons built with
HTTP endpoints, refer to REST Resource:
projects.deployments
Sample Google Workspace Add-on manifest configuration
The following manifest sample shows the section of a manifest file that defines a Google Workspace Add-ons, including the following aspects:
- The
addOns.common
section of the manifest defines the name, logo URL, colors, and other general, host-independent settings for the add-on. - The manifest defines a common homepage, but also defines Calendar, Drive, Docs, Sheets, and Slides-specific homepages. Gmail uses the default homepage.
- The sample manifest settings enable the following:
- Calendar
eventOpen
andeventUpdated
triggers. - (Apps Script only) Two Calendar conference solutions.
- Two universal actions.
- A Drive
onItemsSelectedTrigger
. - A Gmail compose action and contextual trigger.
- A Docs
linkPreviewTriggers
object. To learn about this trigger, see Preview links with smart chips. - A Docs
createActionTriggers
object. To learn about this trigger, see Create third-party resources from the @ menu. - File-specific interfaces for Docs, Sheets, and Slides.
- Calendar
- The
oauthScopes
field sets authorization scopes for the project (Typically required for add-ons). - (Apps Script only) The
urlFetchWhitelist
field is a field that ensures that any fetched endpoints match a specified list of HTTPS URL prefixes. For more information, see Allowlist URLs.
The links in the sample direct to the descriptions of that field in the corresponding manifest reference documentation for Apps Script and HTTP Google Workspace Add-ons.
Apps Script
{ "addOns": { "calendar": { "createSettingsUrlFunction": "getConferenceSettingsPageUrl", "conferenceSolution": [{ "id": "my-video-conf", "logoUrl": "https://lh3.googleusercontent.com/...", "name": "My Video Conference", "onCreateFunction": "onCreateMyVideoConference" }, { "id": "my-streamed-conf", "logoUrl": "https://lh3.googleusercontent.com/...", "name": "My Streamed Conference", "onCreateFunction": "onCreateMyStreamedConference" }], "currentEventAccess": "READ_WRITE", "eventOpenTrigger": { "runFunction": "onCalendarEventOpen" }, "eventUpdateTrigger": { "runFunction": "onCalendarEventUpdate" }, "eventAttachmentTrigger": { "label": "My Event Attachment", "runFunction": "onCalendarEventAddAttachment" }, "homepageTrigger": { "runFunction": "onCalendarHomePageOpen", "enabled": true } }, "common": { "homepageTrigger": { "runFunction": "onDefaultHomePageOpen", "enabled": true }, "layoutProperties": { "primaryColor": "#ff392b", "secondaryColor": "#d68617" }, "logoUrl": "https://ssl.gstatic.com/docs/script/images/logo/script-64.png", "name": "Demo Google Workspace Add-on", "openLinkUrlPrefixes": [ "https://mail.google.com/", "https://script.google.com/a/google.com/d/", "https://drive.google.com/a/google.com/file/d/", "https://www.example.com/" ], "universalActions": [{ "label": "Open settings", "runFunction": "getSettingsCard" }, { "label": "Open Help URL", "openLink": "https://www.example.com/help" }], "useLocaleFromApp": true }, "drive": { "homepageTrigger": { "runFunction": "onDriveHomePageOpen", "enabled": true }, "onItemsSelectedTrigger": { "runFunction": "onDriveItemsSelected" } }, "gmail": { "composeTrigger": { "selectActions": [ { "text": "Add images to email", "runFunction": "getInsertImageComposeCards" } ], "draftAccess": "METADATA" }, "contextualTriggers": [ { "unconditional": {}, "onTriggerFunction": "onGmailMessageOpen" } ] }, "docs": { "homepageTrigger": { "runFunction": "onEditorsHomepage" }, "onFileScopeGrantedTrigger": { "runFunction": "onFileScopeGrantedEditors" }, "linkPreviewTriggers": [ { "runFunction": "onLinkPreview", "patterns": [ { "hostPattern": "example.com", "pathPrefix": "example-path" } ], "labelText": "Link preview", "localizedLabelText": { "es": "Link preview localized in Spanish" }, "logoUrl": "https://www.example.com/images/smart-chip-icon.png" } ], "createActionTriggers": [ { "id": "exampleId", "labelText": "Example label text", "localizedLabelText": { "es": "Label text localized in Spanish" }, "runFunction": "exampleFunction", "logoUrl": "https://www.example.com/images/case.png" } ] }, "sheets": { "homepageTrigger": { "runFunction": "onEditorsHomepage" }, "onFileScopeGrantedTrigger": { "runFunction": "onFileScopeGrantedEditors" } }, "slides": { "homepageTrigger": { "runFunction": "onEditorsHomepage" }, "onFileScopeGrantedTrigger": { "runFunction": "onFileScopeGrantedEditors" } } }, "oauthScopes": [ "https://www.googleapis.com/auth/calendar.addons.execute", "https://www.googleapis.com/auth/calendar.addons.current.event.read", "https://www.googleapis.com/auth/calendar.addons.current.event.write", "https://www.googleapis.com/auth/drive.addons.metadata.readonly", "https://www.googleapis.com/auth/gmail.addons.current.action.compose", "https://www.googleapis.com/auth/gmail.addons.current.message.metadata", "https://www.googleapis.com/auth/userinfo.email", "https://www.googleapis.com/auth/script.external_request", "https://www.googleapis.com/auth/script.locale", "https://www.googleapis.com/auth/script.scriptapp", "https://www.googleapis.com/auth/drive.file", "https://www.googleapis.com/auth/documents.currentonly", "https://www.googleapis.com/auth/spreadsheets.currentonly", "https://www.googleapis.com/auth/presentations.currentonly", "https://www.googleapis.com/auth/workspace.linkpreview" ], "urlFetchWhitelist": [ "https://www.example.com/myendpoint/" ] }
HTTP
{ "addOns": { "calendar": { "currentEventAccess": "READ_WRITE", "eventOpenTrigger": { "runFunction": "https://myownpersonaldomain.com/mypage?trigger=onCalendarEventOpen" }, "eventUpdateTrigger": { "runFunction": "https://myownpersonaldomain.com/mypage?trigger=onCalendarEventUpdate" }, "eventAttachmentTrigger": { "label": "My Event Attachment", "runFunction": "https://myownpersonaldomain.com/mypage?trigger=onCalendarEventAddAttachment" }, "homepageTrigger": { "runFunction": "https://myownpersonaldomain.com/mypage?trigger=onCalendarHomePageOpen", "enabled": true } }, "common": { "homepageTrigger": { "runFunction": "https://myownpersonaldomain.com/mypage?trigger=onDefaultHomePageOpen", "enabled": true }, "layoutProperties": { "primaryColor": "#ff392b", "secondaryColor": "#d68617" }, "logoUrl": "https://ssl.gstatic.com/docs/script/images/logo/script-64.png", "name": "Demo Google Workspace Add-on", "openLinkUrlPrefixes": [ "https://mail.google.com/", "https://script.google.com/a/google.com/d/", "https://drive.google.com/a/google.com/file/d/", "https://www.example.com/" ], "universalActions": [{ "label": "Open settings", "runFunction": "https://myownpersonaldomain.com/mypage?trigger=getSettingsCard" }, { "label": "Open Help URL", "openLink": "https://www.example.com/help" }], "useLocaleFromApp": true }, "drive": { "homepageTrigger": { "runFunction": "https://myownpersonaldomain.com/mypage?trigger=onDriveHomePageOpen", "enabled": true }, "onItemsSelectedTrigger": { "runFunction": "https://myownpersonaldomain.com/mypage?trigger=onDriveItemsSelected" } }, "gmail": { "composeTrigger": { "actions": [ { "label": "Add images to email", "runFunction": "https://myownpersonaldomain.com/mypage?trigger=getInsertImageComposeCards" } ], "draftAccess": "METADATA" }, "contextualTriggers": [ { "unconditional": {}, "onTriggerFunction": "https://myownpersonaldomain.com/mypage?trigger=onGmailMessageOpen" } ] }, "docs": { "homepageTrigger": { "runFunction": "https://myownpersonaldomain.com/mypage?trigger=onEditorsHomepage" }, "onFileScopeGrantedTrigger": { "runFunction": "https://myownpersonaldomain.com/mypage?trigger=onFileScopeGrantedEditors" }, "linkPreviewTriggers": [ { "runFunction": "https://myownpersonaldomain.com/mypage?trigger=onLinkPreview", "patterns": [ { "hostPattern": "example.com", "pathPrefix": "example-path" } ], "labelText": "Link preview", "localizedLabelText": { "es": "Link preview localized in Spanish" }, "logoUrl": "https://www.example.com/images/smart-chip-icon.png" } ], "createActionTriggers": [ { "id": "exampleId", "labelText": "Example label text", "localizedLabelText": { "es": "Label text localized in Spanish" }, "runFunction": "https://myownpersonaldomain.com/mypage?trigger=onCreateAction", "logoUrl": "https://www.example.com/images/case.png" } ] }, "sheets": { "homepageTrigger": { "runFunction": "https://myownpersonaldomain.com/mypage?trigger=onEditorsHomepage" }, "onFileScopeGrantedTrigger": { "runFunction": "https://myownpersonaldomain.com/mypage?trigger=onFileScopeGrantedEditors" } }, "slides": { "homepageTrigger": { "runFunction": "https://myownpersonaldomain.com/mypage?trigger=onEditorsHomepage" }, "onFileScopeGrantedTrigger": { "runFunction": "https://myownpersonaldomain.com/mypage?trigger=onFileScopeGrantedEditors" } } }, "oauthScopes": [ "https://www.googleapis.com/auth/calendar.addons.execute", "https://www.googleapis.com/auth/calendar.addons.current.event.read", "https://www.googleapis.com/auth/calendar.addons.current.event.write", "https://www.googleapis.com/auth/drive.addons.metadata.readonly", "https://www.googleapis.com/auth/gmail.addons.current.action.compose", "https://www.googleapis.com/auth/gmail.addons.current.message.metadata", "https://www.googleapis.com/auth/userinfo.email", "https://www.googleapis.com/auth/script.external_request", "https://www.googleapis.com/auth/script.locale", "https://www.googleapis.com/auth/script.scriptapp", "https://www.googleapis.com/auth/drive.file", "https://www.googleapis.com/auth/documents.currentonly", "https://www.googleapis.com/auth/spreadsheets.currentonly", "https://www.googleapis.com/auth/presentations.currentonly", "https://www.googleapis.com/auth/workspace.linkpreview" ] }
Allowlist URLs
You use allowlists to designate specific URLs that are pre-approved for access by your script or add-on. Allowlists help protect user data; when you define an allowlist, script projects can't access URLs that have not been allowlisted.
This field is optional when you install a test deployment, but is required when you create a versioned deployment.
You use allowlists when your script or add-on performs the following actions:
- Retrieves or fetches information from an external location (such as HTTPS
endpoints) using the Apps Script
UrlFetch
service. To allowlist URLs for fetching, include theurlFetchWhitelist
field in your manifest file. - Opens or displays a URL in response to a user action (Required for
Google Workspace Add-ons that open or display URLs that are external to
Google). To allowlist URLs for opening, include the
addOns.common.openLinkUrlPrefixes
field in your manifest file.
Adding prefixes to your allowlist
When you specify allowlists in your manifest file (by including either the
addOns.common.openLinkUrlPrefixes
or urlFetchWhitelist
field), you must
include a list of URL prefixes. The prefixes you add to the manifest must
satisfy the following requirements:
- Each prefix must be a valid URL.
- Each prefix must use
https://
, nothttp://
. - Each prefix must have a full domain.
- Each prefix must have a non-empty path. For example,
https://www.google.com/
is valid buthttps://www.google.com
is not. - You can use wildcards to match URL subdomain prefixes.
- A single
*
wildcard can be used in theaddOns.common.openLinkUrlPrefixes
field to match all links, but this is not recommended as it can expose a user's data to risk and can prolong the add-on review process. Only use a wildcard if your add-on functionality requires it.
When determining if a URL matches a allowlisted prefix, the following rules apply:
- Path matching is case-sensitive.
- If the prefix is identical to the URL, it is a match.
- If the URL is the same or a child of the prefix, it is a match.
For example, the prefix https://example.com/foo
matches the following URLs:
https://example.com/foo
https://example.com/foo/
https://example.com/foo/bar
https://example.com/foo?bar
https://example.com/foo#bar
Using wildcards
You can use a single wildcard character (*
) to match a subdomain for both the
urlFetchWhitelist
and addOns.common.openLinkUrlPrefixes
fields. You can't use more than one wildcard to match multiple subdomains, and
the wildcard must represent the leading prefix of the URL.
For example, the prefix https://*.example.com/foo
matches the following
URLs:
https://subdomain.example.com/foo
https://any.number.of.subdomains.example.com/foo
The prefix https://*.example.com/foo
doesn't match the following
URLs:
https://subdomain.example.com/bar
(suffix mismatch)https://example.com/foo
(at least one subdomain must be present)
Some of the prefix rules are enforced when you try to save your manifest. For example, the following prefixes cause an error if they are present in your manifest when you attempt to save:
https://*.*.example.com/foo
(multiple wildcards are forbidden)https://subdomain.*.example.com/foo
(wildcards must be used as a leading prefix)