This page describes the top-level of an Apps Script project's manifest file JSON data structure.
Each component sub-object of the JSON structure is described in a different section. For easier reference, some of the larger substructures of the manifest are defined in separate pages:
Manifest
The top-level of the manifest configuration.
JSON representation |
---|
{ "addOns": { object (AddOns) }, "dependencies": { object (Dependencies) }, "exceptionLogging": string, "executionApi": { object (ExecutionApi) }, "oauthScopes": [ string ], "runtimeVersion": string, "sheets": { object (Sheets) }, "timeZone": string, "urlFetchWhitelist": [ string ], "webapp": { object (Webapp) } } |
Fields | |
---|---|
addOns |
The resource configuration of the project if deployed as a Google Workspace add-on. |
dependencies |
The configuration of advanced services and libraries enabled for use by the script project. |
exceptionLogging |
The location where exceptions are logged. The valid settings are the following:
|
executionApi |
The script project's API executable configuration. This is only used if the project is deployed for API execution. |
oauthScopes[] |
The definition of authorization scopes used by the script project. |
runtimeVersion |
The runtime version the
script is using. If this field is not present in the manifest, the
script uses the default runtime (
|
sheets |
The resource configuration that defines Sheets macros. |
timeZone |
The script time zone in one of the available ZoneId values such as "America/Denver". |
urlFetchWhitelist[] |
A list of HTTPS URL prefixes. If present, any URL endpoint fetched must match one of the prefixes in this list. This can help to protect user data. See Whitelisting URLs for more details. |
webapp |
The script project's web app configuration, which is only used if the project is deployed as a web app. |
ExecutionApi
The script project's API executable configuration. This is only used if the project is deployed for API execution.
JSON representation |
---|
{ "access": string } |
Fields | |
---|---|
access |
Determines who has permission to run the script from the API. The valid settings are the following:
|
Webapp
The script project's web app configuration, which is only used if the project is deployed as a web app.
JSON representation |
---|
{ "access": string, "executeAs": string } |
Fields | |
---|---|
access |
The levels of permission for running the web app. The valid settings are the following:
|
executeAs |
The identity under which the web app executes. The valid settings are the following:
|
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://
, 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 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)