Manifests for Google Workspace add-ons

An Apps Script project uses a manifest file to configure certain details about the script and its operation. A manifest is a special JSON-formatted file that is hidden in your script project by default; in most cases, Apps Script automatically adjusts the manifest in response to actions you take in the Apps Script editor. For example, if you add a library to a script project, the relevant details of that library are added to the manifest behind the scenes for you. See Manifest structure for a list of properties an Apps Script project can define in its manifest.

Sometimes it is helpful or necessary to edit a manifest directly. For example, if you intend to publish an add-on you must configure your add-on's manifest to always use the narrowest scopes possible. See Setting explicit scopes for more details.

This documentation covers the details of configuring a manifest for a Google Workspace add-on.

Editing a manifest

The Apps Script editor hides manifest files by default in order to protect your Apps Script project settings. Follow these steps to make a hidden project manifest visible in the Apps Script editor:

New editor

1. Open the script project in the Apps Script editor.
2. At the left, click Project Settings .
3. Select the Show "appsscript.json" manifest file in editor checkbox.

To hide the manifest file, clear the Show "appsscript.json" manifest file in editor checkbox.

Legacy editor

1. Open the script project in the Apps Script editor.
2. Select View > Show project manifest.

To hide the manifest file, select View > Show project manifest again.

The manifest file appears as a project file named appsscript.json. You can edit this file directly in the editor and save any changes you make.

Note: Hide the manifest when you are done editing. Your manifest may already contain a number of key:value pairs; these represent the current configuration of your Apps Script project. Exercise care when editing the manifest, as you may inadvertently alter how your script project operates.

Warning: Make sure you define your manifest file correctly. A poorly defined manifest can prevent you from saving a versioned deployment. A script project that you want to publish can't pass publication review if it lacks required fields or uses OAuth scopes that are too broad.

Manifest structure for Google Workspace Add-ons

Google Workspace Add-ons use the Apps Script project manifest file to define several aspects of the add-on's appearance and behavior. Google Workspace Add-on manifest properties are organized under the addOns section of manifest object structure.

Sample Google Workspace Add-on manifest configuration

The below manifest sample shows the section of a manifest file that defines a Google Workspace Add-on, 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 and eventUpdated triggers, and two Calendar conference solutions.
  • Two universal actions.
  • A Drive onItemsSelectedTrigger.
  • A Gmail compose action and contextual trigger.
  • File-specific interfaces for Docs, Sheets, and Slides.

The below sample manifest also gives examples of oauthScopes and urlFetchWhitelist fields, which most add-on manifests must set.

The links in the sample direct to the descriptions of that field in the Apps Script manifest reference documentation.

Note: Manifests include other components that relate to Apps Script properties. The fields under the addOns field relate directly to Google Workspace Add-ons. This example is just a portion of a full manifest file and is not a fully functional manifest.

{
  ...
  "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"
      },
      "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://en.wikipedia.org/wiki/",
        "https://www.example.com/"
      ],
      "universalActions": [{
        "label": "Open settings",
        "runFunction": "getSettingsCard"
        "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"
      }
    },

    "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"
    ...
  ],
  "urlFetchWhitelist": [
    "https://www.example.com/myendpoint/",
    ...
  ],
  ...
}

Whitelisting URLs

Sometimes you may want your script or add-on to open a URL in response to a user action. Other times you may want your script or add-on to retrieve information from an external location using the Apps Script UrlFetch service. In both cases you must whitelist the URLs you open or fetch from in the project manifest.

Whitelisting is the process where you designate specific URLs that are pre-approved for access by your script or add-on. This requirement helps protect user data; if you define a whitelist, script projects can't access URLs that have not been whitelisted. Google Workspace add-ons require URLs to be whitelisted before they can be fetched or opened.

You can whitelist a URL for fetching by adding it or a matching prefix to the urlFetchWhitelist manifest field. For Google Workspace add-on projects, you can whitelist a URL for opening by adding it or a matching prefix to the addOns.common.openLinkUrlPrefixes manifest field.

The prefixes you add to the manifest must satisfy the following requirements:

• Each prefix must be a valid URL.
• Each prefix must use https://, not http://.
• Each prefix must have a full domain.
• Each prefix must have a non-empty path. For example, https://www.google.com/ is valid but https://www.google.com is not.
• You can use wildcards to match URL subdomain prefixes.
• A single * wildcard can be used in the addOns.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 whitelisted 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)