Manifestos para complementos do Google Workspace

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

Esta documentação aborda 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 de manifesto.

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

O exemplo de manifesto a seguir mostra a seção de um arquivo de manifesto que define 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 para o complemento.
• O manifesto define uma página inicial comum, mas também define páginas iniciais específicas do Google Agenda, Drive, Documentos, Planilhas e Apresentações. O Gmail usa a página inicial padrão.
• O exemplo de configurações do manifesto permite o seguinte:
  • Gatilhos eventOpen e eventUpdated do Agenda e duas soluções de conferência do Agenda.
  • Duas ações universais.
  • Uma onItemsSelectedTrigger de carro.
  • Uma ação "Escrever" do Gmail e um acionador contextual.
  • linkPreviewTrigger do Documentos. Para saber mais sobre esse acionador, consulte Visualizar links com ícones inteligentes.
  • Interfaces específicas de arquivos para Documentos, Planilhas e Apresentações.
• O campo oauthScopes define escopos de autorização para o projeto (normalmente necessários para complementos).
• O campo urlFetchWhitelist é um campo que garante que 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 ver 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 (link em inglês).

Observação: os manifestos incluem outros componentes relacionados às propriedades do Apps Script. Os campos abaixo do campo addOns estão relacionados diretamente aos complementos do Google Workspace. Esse exemplo é apenas uma parte de um arquivo de manifesto completo e não é um manifesto totalmente 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"
      },
      "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/"
  ],
}

Adicionar URLs à lista de permissões

Use listas de permissões para designar URLs específicos que são pré-aprovados para acesso pelo seu script ou complemento. As listas de permissões ajudam a proteger os dados do usuário. Quando você a define, 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 o 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 colocar URLs de busca na lista de permissões, inclua o campo urlFetchWhitelist no 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 colocar os URLs que vão ser abertos na lista de permissões, inclua o campo addOns.common.openLinkUrlPrefixes no arquivo de manifesto.

Observação: Lista de permissões, conforme usado em urlFetchWhitelist, é um termo descontinuado que é sinônimo de lista de permissões. Para mais informações, consulte Como escrever uma documentação inclusiva.

Adicionar prefixos à lista de permissões

Ao especificar listas de permissões no arquivo de manifesto (incluindo o campo addOns.common.openLinkUrlPrefixes ou urlFetchWhitelist), você precisa incluir 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 a prefixos de subdomínio de URL.
• É possível usar um único caractere curinga * 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 riscos e prolongar o processo de revisão de complementos. Use um caractere curinga apenas se a funcionalidade do 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, é uma correspondência.
• Se o URL for o mesmo ou um filho 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 corresponder um subdomínio aos 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 inicial 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 sufixo)
• https://example.com/foo (pelo menos um subdomínio precisa estar presente)

Algumas das regras de prefixo são aplicadas quando você tenta salvar seu manifesto. Por exemplo, os prefixos abaixo causam um erro se estiverem presentes no manifesto quando você tenta 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 inicial)