Manifestos para complementos do Google Workspace

Um complemento usa um arquivo de manifesto para configurar determinados detalhes sobre o app e a operação dele.

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 para definir vários aspectos do complementos aparência e comportamento.

As propriedades do manifesto para os complementos do Google Workspace são: organizados na seção addOns da estrutura do objeto do manifesto.

• Para informações sobre os arquivos de manifesto do Apps Script, consulte Estrutura do manifesto.
• Para informações sobre arquivos de manifesto para complementos criados com o Endpoints HTTP, consulte Recurso REST: projects.deployments

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 Complementos do Google Workspace, incluindo os seguintes aspectos:

• O addOns.common do manifesto define o nome, o URL do logotipo, as cores e outros elementos configurações gerais independentes do host para o complemento.
• O manifesto define uma página inicial comum, mas também define Agenda, Drive, Documentos, páginas iniciais específicas do Planilhas e do Apresentações. O Gmail usa a página inicial padrão.
• As configurações do exemplo de manifesto permitem o seguinte:
  • Acionadores eventOpen e eventUpdated da agenda.
  • (somente Apps Script) Duas agendas soluções de conferência.
  • Duas ações universais.
  • Uma onItemsSelectedTrigger de carro.
  • Uma ação de texto e um acionador contextual do Gmail.
  • Um objeto linkPreviewTriggersdo Docs. Para saber mais sobre esse gatilho, consulte Visualizar links com ícones inteligentes.
  • Um objeto createActionTriggers dos Documentos. Para saber mais sobre esse gatilho, consulte Criar recursos de terceiros no menu @.
  • Interfaces específicas para arquivos nos apps Documentos, Planilhas e Apresentações.
• O campo oauthScopes define escopos de autorização para o projeto (normalmente necessário para ou complementos).
• (Somente Apps Script) O urlFetchWhitelist é um campo que garante que os pontos de extremidade buscados correspondam a um lista de prefixos de URL HTTPS. Para mais informações, consulte Adicionar URLs à lista de permissões.

Os links no exemplo direcionam para as descrições desse campo na linha documentação de referência do manifesto para Apps Script e HTTP Complementos do Google Workspace.

Observação: os manifestos incluem outros componentes. Os campos na addOns está relacionado diretamente aos complementos do Google Workspace. Isso é apenas uma parte de um arquivo de manifesto completo e não é um arquivo manifesto funcional.

Apps Script

{
  "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://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"
        }
      ],
      "createActionTriggers": [
        {
          "id": "exampleId",
          "labelText": "Example label text",
          "localizedLabelText": {
            "es": "Label text localized in Spanish"
          },
          "runFunction": "exampleFunction",
          "logoUrl": "https://www.example.com/images/case.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/"
  ]
}

HTTP

{
  "addOns": {
    "calendar": {
      "currentEventAccess": "READ_WRITE",
      "eventOpenTrigger": {
        "runFunction": "https://myownpersonaldomain.com/mypage?trigger=onCalendarEventOpen"
      },
      "eventUpdateTrigger": {
        "runFunction": "https://myownpersonaldomain.com/mypage?trigger=onCalendarEventUpdate"
      },
      "eventAttachmentTrigger": {
        "label": "My Event Attachment",
        "runFunction": "https://myownpersonaldomain.com/mypage?trigger=onCalendarEventAddAttachment"
      },
      "homepageTrigger": {
        "runFunction": "https://myownpersonaldomain.com/mypage?trigger=onCalendarHomePageOpen",
        "enabled": true
      }
    },
    "common": {
      "homepageTrigger": {
        "runFunction": "https://myownpersonaldomain.com/mypage?trigger=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://www.example.com/"
      ],
      "universalActions": [{
        "label": "Open settings",
        "runFunction": "https://myownpersonaldomain.com/mypage?trigger=getSettingsCard"
      }, {
        "label": "Open Help URL",
        "openLink": "https://www.example.com/help"
      }],
      "useLocaleFromApp": true
    },
    "drive": {
      "homepageTrigger": {
        "runFunction": "https://myownpersonaldomain.com/mypage?trigger=onDriveHomePageOpen",
        "enabled": true
      },
      "onItemsSelectedTrigger": {
        "runFunction": "https://myownpersonaldomain.com/mypage?trigger=onDriveItemsSelected"
      }
    },
    "gmail": {
      "composeTrigger": {
        "actions": [
          {
            "label": "Add images to email",
            "runFunction": "https://myownpersonaldomain.com/mypage?trigger=getInsertImageComposeCards"
          }
        ],
        "draftAccess": "METADATA"
      },
      "contextualTriggers": [
        {
          "unconditional": {},
          "onTriggerFunction": "https://myownpersonaldomain.com/mypage?trigger=onGmailMessageOpen"
        }
      ]
    },
    "docs": {
      "homepageTrigger": {
        "runFunction": "https://myownpersonaldomain.com/mypage?trigger=onEditorsHomepage"
      },
      "onFileScopeGrantedTrigger": {
        "runFunction": "https://myownpersonaldomain.com/mypage?trigger=onFileScopeGrantedEditors"
      },
      "linkPreviewTriggers": [
        {
          "runFunction": "https://myownpersonaldomain.com/mypage?trigger=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"
        }
      ],
      "createActionTriggers": [
        {
          "id": "exampleId",
          "labelText": "Example label text",
          "localizedLabelText": {
            "es": "Label text localized in Spanish"
          },
          "runFunction": "https://myownpersonaldomain.com/mypage?trigger=onCreateAction",
          "logoUrl": "https://www.example.com/images/case.png"
        }
      ]
    },
    "sheets": {
      "homepageTrigger": {
        "runFunction": "https://myownpersonaldomain.com/mypage?trigger=onEditorsHomepage"
      },
      "onFileScopeGrantedTrigger": {
        "runFunction": "https://myownpersonaldomain.com/mypage?trigger=onFileScopeGrantedEditors"
      }
    },
    "slides": {
      "homepageTrigger": {
        "runFunction": "https://myownpersonaldomain.com/mypage?trigger=onEditorsHomepage"
      },
      "onFileScopeGrantedTrigger": {
        "runFunction": "https://myownpersonaldomain.com/mypage?trigger=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"
  ]
}

Colocar URLs na lista de permissões

As listas de permissões são usadas para designar URLs específicos pré-aprovados para acesso. pelo seu script ou complemento. As listas de permissões ajudam a proteger o usuário data; quando você define uma lista de permissões, os projetos de script não podem acessar URLs que tenham não está na lista de permissões.

Este campo é opcional quando você instala uma implantação de teste, mas é obrigatório quando crie uma implantação com controle de versão.

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

• Recupera ou busca informações de um local externo (como HTTPS endpoints) usando o UrlFetch do Apps Script serviço. Para autorizar URLs para busca, 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 a Google). Para permitir URLs que podem ser abertos, inclua o campo addOns.common.openLinkUrlPrefixes no seu arquivo de manifesto do app.

.

Observação: lista de permissões, como usado em urlFetchWhitelist, é um termo descontinuado que é sinônimo e foi substituído por lista de permissões. Para mais informações, consulte Como escrever documentação inclusiva.

Como adicionar prefixos à sua lista de permissões

Quando você especifica listas de permissões no seu arquivo de manifesto (incluindo os addOns.common.openLinkUrlPrefixes ou urlFetchWhitelist), será preciso incluir uma lista de prefixos de URL. Os prefixos adicionados ao manifesto precisam atendam aos seguintes requisitos:

• Cada prefixo precisa ser um URL válido.
• Cada prefixo precisa usar https://, e 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 na addOns.common.openLinkUrlPrefixes para corresponder a todos os links, mas isso não é recomendado, pois pode expor uma dos dados do usuário a riscos e pode prolongar a processo de revisão de complementos. Somente use um caractere curinga se a funcionalidade do complemento exigir.

Para determinar se um URL corresponde a um prefixo da lista de permissões, siga estas regras: aplicar:

• A correspondência de caminho diferencia maiúsculas de minúsculas.
• Se o prefixo for idêntico ao URL, isso indica uma correspondência.
• Se o URL for o mesmo ou um filho do prefixo, é 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

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

Por exemplo, o prefixo https://*.example.com/foo corresponde ao seguinte: URLs:

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

O prefixo https://*.example.com/foo não corresponde ao seguinte: 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. Para exemplo, os prefixos a seguir causarão um erro se estiverem presentes no quando você tenta salvar:

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