Un proyecto de Apps Script usa un archivo de manifiesto para configurar ciertos detalles sobre la secuencia de comandos y su funcionamiento. Para obtener información sobre cómo ver y editar un manifiesto, consulta Manifiestos.
En esta documentación, se incluyen detalles sobre la configuración de un manifiesto para un complemento de Google Workspace.
Estructura de manifiesto para complementos de Google Workspace
Los complementos de Google Workspace usan el archivo de manifiesto del proyecto de Apps Script para definir varios aspectos de la apariencia y el comportamiento del complemento. Las propiedades del manifiesto para los complementos de Google Workspace se
organizan en la
sección addOns
de la estructura del objeto del manifiesto.
Ejemplo de la configuración del manifiesto del complemento de Google Workspace
En el siguiente ejemplo de manifiesto, se muestra la sección de un archivo de manifiesto en el que se definen complementos de Google Workspace, incluidos los siguientes aspectos:
- En la sección
addOns.common
del manifiesto, se definen el nombre, la URL del logotipo, los colores y otros parámetros de configuración generales independientes del host para el complemento. - El manifiesto define una página principal común, pero también define las páginas principales específicas de Calendario, Drive, Documentos, Hojas de cálculo y Presentaciones. Gmail usa la página principal predeterminada.
- La configuración del manifiesto de muestra habilita lo siguiente:
- Activadores de Calendario
eventOpen
yeventUpdated
, y dos soluciones de conferencia del Calendario. - Dos acciones universales.
- Una unidad de
onItemsSelectedTrigger
- Una acción de redacción de Gmail y un activador contextual
- Un
linkPreviewTrigger
de Documentos. Para obtener más información sobre este activador, consulta Cómo obtener una vista previa de los vínculos con chips inteligentes. - Interfaces específicas de archivos para Documentos, Hojas de cálculo y Presentaciones
- Activadores de Calendario
- El campo
oauthScopes
establece permisos de autorización para el proyecto (por lo general, es obligatorio para los complementos). - El campo
urlFetchWhitelist
es un campo que garantiza que cualquier extremo recuperado coincida con una lista especificada de prefijos de URL HTTPS. Este campo es opcional para las implementaciones de prueba, pero es obligatorio para las implementaciones. Para obtener más información, consulta URL de la lista de entidades permitidas.
Los vínculos de la muestra llevan a las descripciones de ese campo en la documentación de referencia del manifiesto.
// Sample configuration of the addOns section in a manifest file: { "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://en.wikipedia.org/wiki/", "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" } ] }, "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/" ], }
URL de la lista de entidades permitidas
Puedes usar listas de entidades permitidas para designar URL específicas que ya recibieron la aprobación previa de tu secuencia de comandos o complemento. Las listas de entidades permitidas ayudan a proteger los datos del usuario. Cuando defines una lista de entidades permitidas, los proyectos de secuencias de comandos no pueden acceder a las URLs que no se incluyeron en la lista de entidades permitidas.
Usarás listas de entidades permitidas cuando tu secuencia de comandos o complemento realice las siguientes acciones:
- Recupera o recupera información de una ubicación externa (como extremos HTTPS) mediante el servicio
UrlFetch
de Apps Script. Si quieres incluir las URLs en la lista de entidades permitidas para recuperarlas, incluye el campourlFetchWhitelist
en tu archivo de manifiesto. - Abre o muestra una URL en respuesta a una acción del usuario (obligatoria para los complementos de Google Workspace que abren o muestran URLs externas a Google). Si quieres incluir las URLs en la lista de entidades permitidas para que se abran, incluye el campo
addOns.common.openLinkUrlPrefixes
en tu archivo de manifiesto.
Agrega prefijos a tu lista de entidades permitidas
Cuando especificas listas de entidades permitidas en tu archivo de manifiesto (incluyendo el campo addOns.common.openLinkUrlPrefixes
o urlFetchWhitelist
), debes incluir una lista de prefijos de URL. Los prefijos que agregues al manifiesto deben cumplir con los siguientes requisitos:
- Cada prefijo debe ser una URL válida.
- Cada prefijo debe usar
https://
, nohttp://
. - Cada prefijo debe tener un dominio completo.
- Cada prefijo debe tener una ruta que no esté vacía. Por ejemplo,
https://www.google.com/
es válido, perohttps://www.google.com
no lo es. - Puedes usar comodines para hacer coincidir los prefijos de subdominios de URL.
- Se puede usar un solo comodín
*
en el campoaddOns.common.openLinkUrlPrefixes
para que coincida con todos los vínculos, pero no se recomienda, ya que puede exponer los datos de un usuario al riesgo y puede prolongar el proceso de revisión de complemento. Solo usa un comodín si tu funcionalidad de complemento lo requiere.
Cuando se determina si una URL coincide con un prefijo incluido en la lista de entidades permitidas, se aplican las siguientes reglas:
- La coincidencia de ruta de acceso distingue entre mayúsculas y minúsculas.
- Si el prefijo es idéntico a la URL, es una coincidencia.
- Si la URL es la misma o un elemento secundario del prefijo, es una coincidencia.
Por ejemplo, el prefijo https://example.com/foo
coincide con las siguientes URLs:
https://example.com/foo
https://example.com/foo/
https://example.com/foo/bar
https://example.com/foo?bar
https://example.com/foo#bar
Usa comodines
Puedes usar un solo carácter comodín (*
) a fin de hacer coincidir un subdominio para los campos urlFetchWhitelist
y addOns.common.openLinkUrlPrefixes
. No puedes usar más de un comodín para hacer coincidir varios subdominios, que deben representar el prefijo inicial de la URL.
Por ejemplo, el prefijo https://*.example.com/foo
coincide con las siguientes URLs:
https://subdomain.example.com/foo
https://any.number.of.subdomains.example.com/foo
El prefijo https://*.example.com/foo
no coincide con las siguientes URL:
https://subdomain.example.com/bar
(no coincide con el sufijo)https://example.com/foo
(debe estar presente, al menos, un subdominio)
Algunas de las reglas de prefijo se aplican cuando intentas guardar tu manifiesto. Por ejemplo, los siguientes prefijos generan un error si están presentes en tu manifiesto cuando intentas guardar:
https://*.*.example.com/foo
(se prohíben varios comodines)https://subdomain.*.example.com/foo
(se deben usar comodines como prefijo inicial)