Manifestos para complementos do Google Workspace

Um projeto do Apps Script usa um arquivo de manifesto para configurar determinados detalhes sobre o script e sua operação. Para saber como ver e editar um manifesto, consulte Manifestos.

Esta documentação abrange os detalhes da configuração de um manifesto para um complemento do Google Workspace.

Estrutura do manifesto para complementos do Google Workspace

Os complementos do Google Workspace usam o arquivo de manifesto do projeto do Apps Script para definir vários aspectos da aparência e do comportamento do complemento. As propriedades do manifesto para complementos do Google Workspace são organizadas na seção addOns da estrutura do objeto do manifesto.

Exemplo de configuração de manifesto de complemento do Google Workspace

O exemplo de manifesto a seguir mostra a seção de um arquivo de manifesto que define os complementos do Google Workspace, incluindo os seguintes aspectos:

  • A seção addOns.common do manifesto define o nome, o URL do logotipo, as cores e outras configurações gerais independentes do host do complemento.
  • O manifesto define uma página inicial comum, mas também define páginas específicas do Agenda, do Drive, do Documentos, do Planilhas e do Apresentações. O Gmail usa a página inicial padrão.
  • As configurações de manifesto de amostra permitem o seguinte:
    • Acionadores eventOpen e eventUpdated do Agenda e duas soluções de videoconferência do Agenda.
    • Duas ações universais.
    • Um Drive onItemsSelectedTrigger.
    • Uma ação de escrita e um acionador contextual do Gmail.
    • Um documento linkPreviewTrigger. Para saber mais sobre esse gatilho, consulte Visualizar links com ícones inteligentes.
    • Interfaces específicas de arquivos para o Documentos, Planilhas e Apresentações.
  • O campo oauthScopes define escopos de autorização para o projeto (normalmente necessários para complementos).
  • O campo urlFetchWhitelist garante que todos os endpoints buscados correspondam a uma lista especificada de prefixos de URL HTTPS. Esse campo é opcional para implantações de teste, mas é obrigatório para implantações. Para mais informações, consulte URLs da lista de permissões.

Os links no exemplo direcionam para as descrições desse campo na documentação de referência do manifesto.

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

Autorizar URLs

Use listas de permissões para designar URLs específicos pré-aprovados para acesso pelo seu script ou complemento. As listas de permissões ajudam a proteger os dados do usuário. Quando você define uma lista de permissões, os projetos de script não podem acessar URLs que não estejam na lista de permissões.

Você usa listas de permissões quando seu script ou complemento executa as seguintes ações:

  • Recupera ou busca informações de um local externo (como endpoints HTTPS) usando o serviço UrlFetch do Apps Script. Para autorizar os URLs a serem buscados, inclua o campo urlFetchWhitelist no seu arquivo de manifesto.
  • Abre ou exibe um URL em resposta a uma ação do usuário (obrigatório para complementos do Google Workspace que abrem ou exibem URLs externos ao Google). Para autorizar os URLs a serem abertos, inclua o campo addOns.common.openLinkUrlPrefixes no arquivo de manifesto.

Como adicionar prefixos à lista de permissões

Ao especificar listas de permissões no arquivo de manifesto, incluindo o campo addOns.common.openLinkUrlPrefixes ou urlFetchWhitelist, inclua uma lista de prefixos de URL. Os prefixos adicionados ao manifesto precisam atender aos seguintes requisitos:

  • Cada prefixo precisa ser um URL válido.
  • Cada prefixo precisa usar https://, não http://.
  • Cada prefixo precisa ter um domínio completo.
  • Cada prefixo precisa ter um caminho não vazio. Por exemplo, https://www.google.com/ é válido, mas https://www.google.com não é.
  • É possível usar caracteres curinga para corresponder aos prefixos de subdomínio do URL.
  • Um único caractere curinga * pode ser usado no campo addOns.common.openLinkUrlPrefixes para corresponder a todos os links, mas isso não é recomendado porque pode expor os dados de um usuário a risco e pode prolongar o processo de revisão de complementos. Use um caractere curinga apenas se a funcionalidade de complemento exigir.

Ao determinar se um URL corresponde a um prefixo da lista de permissões, as seguintes regras se aplicam:

  • A correspondência de caminho diferencia maiúsculas de minúsculas.
  • Se o prefixo for idêntico ao URL, será uma correspondência.
  • Se o URL for o mesmo ou um derivado do prefixo, será uma correspondência.

Por exemplo, o prefixo https://example.com/foo corresponde aos seguintes URLs:

  • https://example.com/foo
  • https://example.com/foo/
  • https://example.com/foo/bar
  • https://example.com/foo?bar
  • https://example.com/foo#bar

Como usar caracteres curinga

É possível usar um único caractere curinga (*) para fazer a correspondência de um subdomínio para os campos urlFetchWhitelist e addOns.common.openLinkUrlPrefixes. Não é possível usar mais de um caractere curinga para corresponder a vários subdomínios, e o caractere curinga precisa representar o prefixo principal do URL.

Por exemplo, o prefixo https://*.example.com/foo corresponde aos seguintes URLs:

  • https://subdomain.example.com/foo
  • https://any.number.of.subdomains.example.com/foo

O prefixo https://*.example.com/foo não corresponde aos seguintes URLs:

  • https://subdomain.example.com/bar (incompatibilidade de sufixos)
  • https://example.com/foo (pelo menos um subdomínio precisa estar presente)

Algumas das regras de prefixo são aplicadas quando você tenta salvar o manifesto. Por exemplo, os prefixos a seguir causam um erro se estiverem presentes no manifesto quando você tentar salvar:

  • https://*.*.example.com/foo (vários caracteres curingas são proibidos)
  • https://subdomain.*.example.com/foo Os caracteres curinga precisam ser usados como prefixo.