Manifiestos para los complementos de Google Workspace

Un proyecto de Apps Script usa un archivo de manifiesto para configurar ciertos detalles sobre la secuencia de comandos y su funcionamiento. Para obtener más información sobre cómo ver y editar un manifiesto, consulta Manifiestos.

En esta documentación, se abarcan los detalles de la configuración de un manifiesto para un complemento de Google Workspace.

Estructura del 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 configuración de manifiesto del complemento de Google Workspace

En la siguiente muestra del manifiesto, se muestra la sección de un archivo de manifiesto que define un complemento 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 y eventUpdated, y dos soluciones de conferencia para el Calendario.
  • Dos acciones universales.
  • Una unidad de onItemsSelectedTrigger
  • Una acción de redacción de Gmail y un activador contextual.
  • Interfaces específicas para archivos de Documentos, Hojas de cálculo y Presentaciones.
• El campo oauthScopes establece los permisos de autorización del proyecto (por lo general, es necesario para los complementos).
• El campo urlFetchWhitelist es un campo opcional que garantiza que los extremos recuperados coincidan con una lista especificada de prefijos de URL HTTPS. Para obtener más información, consulta Cómo incluir URL en la lista de anunciantes permitidos.

Los vínculos de la muestra dirigen a las descripciones de ese campo en la documentación de referencia del manifiesto.

Nota: Los manifiestos incluyen otros componentes relacionados con las propiedades de Apps Script. Los campos del campo addOns se relacionan directamente con los complementos de Google Workspace. Este ejemplo es solo una parte de un archivo de manifiesto completo y no es un manifiesto completamente funcional.

// 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"
      }
    },

    "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/"
  ],
}

Incluir URL en la lista de anunciantes permitidos

Puedes usar listas de entidades permitidas para designar URL específicas con aprobación previa a fin de acceder a ellas mediante la secuencia de comandos o el complemento. Las listas de entidades permitidas ayudan a proteger los datos del usuario: cuando defines una lista de entidades permitidas, los proyectos de secuencia de comandos no pueden acceder a las URL que no se incluyeron en la lista de anunciantes permitidos.

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. A fin de incluir URL en la lista de entidades permitidas para recuperarlas, incluye el campo urlFetchWhitelist en el archivo de manifiesto.
• Abre o muestra una URL en respuesta a una acción del usuario (obligatorio para los complementos de Google Workspace que abren o muestran URL que son externas a Google). Si quieres agregar URL a la lista de entidades permitidas para abrirlas, incluye el campo addOns.common.openLinkUrlPrefixes en tu archivo de manifiesto.

Nota: Lista blanca, tal como se usa en urlFetchWhitelist, es un término obsoleto que se usa en simultáneo y se reemplaza por allowlist. Para obtener más información, consulta Escribe documentación inclusiva.

Agrega prefijos a la 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://, no http://.
• Cada prefijo debe tener un dominio completo.
• Cada prefijo debe tener una ruta no vacía. Por ejemplo, https://www.google.com/ es válido, pero https://www.google.com no lo es.
• Puedes usar comodines para hacer coincidir los prefijos de los subdominios de URL.
• Se puede usar un solo comodín * en el campo addOns.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.

Para determinar 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 una secundaria del prefijo, es una coincidencia.

Por ejemplo, el prefijo https://example.com/foo coincide con las siguientes URL:

• 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 (*) para hacer coincidir un subdominio en 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 URL:

• 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 haber al menos un subdominio)

Algunas de las reglas de prefijos se aplican de manera forzosa cuando intentas guardar el manifiesto. Por ejemplo, los siguientes prefijos generan un error si están presentes en tu manifiesto cuando intentas guardar:

• https://*.*.example.com/foo (se prohibieron varios comodines)
• https://subdomain.*.example.com/foo (los comodines deben usarse como prefijo inicial)