Manifiestos para los complementos de Google Workspace

Organiza tus páginas con colecciones Guarda y categoriza el contenido según tus preferencias.

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

En esta documentación, se incluyen los detalles sobre cómo configurar un manifiesto para un complemento de Google Workspace.

Estructura del manifiesto para los 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 el siguiente ejemplo de manifiesto, se muestra la sección de un archivo de manifiesto que define un complemento de Google Workspace, incluidos los siguientes aspectos:

  • La sección addOns.common del manifiesto define el nombre, la URL del logotipo, los colores y otros ajustes generales independientes del host para el complemento.
  • El manifiesto define una página principal común, pero también define 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:
    • Los activadores eventOpen y eventUpdated del Calendario, 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
    • Interfaces específicas de archivos para Documentos, Hojas de cálculo y Presentaciones
  • El campo oauthScopes establece permisos de autorización para el proyecto (por lo general, es obligatorio para los complementos).
  • El campo urlFetchWhitelist establece un prefijo de URL HTTPS, lo que garantiza que cualquier extremo recuperado coincida con el prefijo (por lo general, es obligatorio para los complementos). Para obtener más información, consulta URL incluidas en la lista de entidades permitidas.

Los vínculos de la muestra dirigen 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"
      }
    },

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

URL incluidas en la lista de entidades permitidas

A veces, es posible que desees que tu secuencia de comandos o complemento abra una URL en respuesta a una acción del usuario. En otras ocasiones, es posible que desees que la secuencia de comandos o el complemento recupere información de una ubicación externa con el servicio UrlFetch de Apps Script. En ambos casos, debes incluir en la lista de entidades permitidas las URL que abras o recuperes en el manifiesto del proyecto.

La lista de entidades permitidas es el proceso mediante el cual se designan URL específicas aprobadas previamente para que tu secuencia de comandos o complemento acceda a ellas. Este requisito ayuda a proteger los datos del usuario. Si defines una lista de entidades permitidas, los proyectos de secuencias de comandos no pueden acceder a las URL que no se incluyeron en la lista de elementos permitidos. Google Workspace Los complementos requieren que las URL se incluyan en la lista de entidades permitidas antes de que se puedan recuperar o abrir.

Puedes incluir una URL en la lista de entidades permitidas para recuperarla si la agregas o si agregas un prefijo que coincida con el campo del manifiesto urlFetchWhitelist. En el caso de los proyectos complementarios Google Workspace, puedes agregar una URL a la lista de entidades permitidas para abrirla si la agregas o un prefijo coincidente al campo addOns.common.openLinkUrlPrefixes del manifiesto.

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 que no esté 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 subdominio de URL.
  • Se puede usar un solo comodín * en el campo addOns.common.openLinkUrlPrefixes para hacer coincidir todos los vínculos, pero no se recomienda, ya que puede exponer los datos de un usuario en riesgo y puede prolongar el proceso de revisión de complementos. Usa un comodín solo si tu funcionalidad de complemento lo requiere.

Cuando determinas si una URL coincide con un prefijo incluido en la lista de entidades permitidas, se aplican las siguientes reglas:

  • La coincidencia de ruta 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 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, y el comodín debe 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 estar presente al menos un subdominio)

Algunas de las reglas de prefijos se aplican de forma forzosa 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 (varios comodines están prohibidos)
  • https://subdomain.*.example.com/foo (se deben usar comodines como prefijo inicial)