Manifestos para complementos do Google Workspace

Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

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

Esta documentação aborda os detalhes de 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 dos complementos. 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 do manifesto de complementos do Google Workspace

O exemplo de manifesto abaixo mostra a seção de um arquivo de manifesto que define um complemento 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 e independentes de hosts para o complemento.
  • O manifesto define uma página inicial comum, mas também define páginas iniciais específicas do Google Agenda, Google Drive, Documentos, Planilhas e Apresentações. O Gmail usa a página inicial padrão.
  • As configurações do manifesto de exemplo permitem o seguinte:
    • Acionadores do Agenda eventOpen e eventUpdated e duas soluções de videoconferência do Agenda.
    • Duas ações universais.
    • Um Drive onItemsSelectedTrigger.
    • Um acionador de ação e de contexto contextual do Gmail.
    • 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ário para complementos).
  • O campo urlFetchWhitelist define um prefixo de URL HTTPS, o que garante que todos os endpoints buscados correspondam ao prefixo (normalmente necessário para complementos). 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 de 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"
      }
    },

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

Autorizar URLs

Às vezes, você pode querer que seu script ou complemento abra um URL em resposta a uma ação do usuário. Talvez você queira que o script ou complemento recupere informações de um local externo usando o serviço UrlFetch do Apps Script. Em ambos os casos, é necessário colocar na lista de permissões os URLs que você abre ou busca no manifesto do projeto.

Na lista de permissões, você atribui URLs específicos pré-aprovados para acesso pelo seu script ou complemento. Esse requisito ajuda a proteger os dados do usuário. Se você definir uma lista de permissões, os projetos de script não poderão acessar URLs que não estejam na lista de permissões. Google Workspace Os complementos exigem que os URLs estejam na lista de permissões antes de serem buscados ou abertos.

Você pode colocar um URL na lista de permissões para inclusão adicionando-o ou um prefixo correspondente ao campo de manifesto urlFetchWhitelist. Para Google Workspace projetos complementares, é possível incluir um URL para abertura adicionando-o ou um prefixo correspondente ao campo de manifesto addOns.common.openLinkUrlPrefixes.

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.
  • Você pode usar caracteres curinga para corresponder a 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, já que pode expor os dados de um usuário a riscos e pode prolongar o processo de avaliação complementar. Use um caractere curinga apenas se a funcionalidade dos complementos exigir isso.

Para determinar se um URL corresponde a um prefixo da lista de permissões, estas regras são aplicadas:

  • 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 filho do prefixo, ele 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 curingas

É possível usar um único caractere curinga (*) para corresponder a um subdomínio para os campos urlFetchWhitelist e addOns.common.openLinkUrlPrefixes. Não é possível usar mais de um caractere curinga para vários subdomínios, e esse caractere 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't 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 o manifesto. Por exemplo, os prefixos a seguir causarão um erro se estiverem presentes no manifesto quando você tentar salvar:

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