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 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.
Para informações sobre arquivos de manifesto do Apps Script, consulte Estrutura do manifesto.
Para informações sobre arquivos de manifesto de complementos criados com endpoints HTTP, consulte o recurso
projects.deployments.
Manifestos para o Google Chat
Se o complemento do Google Workspace estender o Google Chat, configure um app do Google Chat ativando e configurando a API Google Chat no console do Google Cloud.
As configurações comuns de configuração do manifesto (incluindo addons.common) são ignoradas no Chat. Em vez de usar o manifesto
do complemento, use a API Chat para configurar as seguintes
configurações do Chat:
- O nome, o logotipo e a descrição do app Chat, que aparecem apenas na interface do Chat.
- Gatilhos do app de chat.
Se você criou o complemento no Apps Script, também é necessário adicionar ou atualizar os seguintes objetos no manifesto:
addons.chat(obrigatório)oauthScopes(obrigatório se o app do Google Chat usar escopos do OAuth)
Para saber como configurar as opções do Chat para um complemento, consulte Configurar um app do Google Chat.
Exemplo de configuração de manifesto de complemento do Google Workspace
Os exemplos de manifesto a seguir mostram a seção de um arquivo de manifesto que define um complemento do Google Workspace, incluindo os seguintes aspectos:
A seção
addOns.commondo manifesto define o nome, o URL do logotipo, as cores e outras configurações gerais e independentes do host para o complemento.O manifesto define uma página inicial comum, mas também define páginas iniciais específicas para Agenda, Drive, Documentos, Planilhas e Apresentações. O Gmail usa a página inicial padrão.
As configurações de manifesto de exemplo permitem o seguinte:
Acionadores da Agenda
eventOpeneeventUpdated.(Somente Apps Script) Duas soluções de conferência do Google Agenda.
Duas ações universais.
Um Drive
onItemsSelectedTrigger.Uma ação de redação do Gmail e um gatilho contextual.
Um objeto
linkPreviewTriggersdo Google Docs. Para saber mais sobre esse gatilho, consulte Visualizar links com ícones inteligentes.Um objeto
createActionTriggersdo Google Docs. Para saber mais sobre esse gatilho, consulte Criar recursos de terceiros com o menu @.Interfaces específicas para arquivos dos apps Documentos, Planilhas e Apresentações.
(Somente HTTP) Dois
HttpOptionspara enviar um cabeçalho de autorização e oferecer suporte ao consentimento granular.
O campo
oauthScopesdefine os escopos de autorização do projeto (normalmente necessários para complementos).(Somente Apps Script) O campo
urlFetchWhitelistgarante que todos os endpoints buscados correspondam a uma lista especificada de prefixos de URL HTTPS. Para mais informações, consulte Lista de permissões de URLs.
Os links nos exemplos de manifesto redirecionam para as descrições desse campo na documentação de referência do manifesto correspondente para complementos do Apps Script e HTTP do Google Workspace.
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" } } "httpOptions": { "authorizationHeader": "SYSTEM_ID_TOKEN", "granularOauthPermissionSupport": "OPT_IN" } }, "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" ] }
Adicionar URLs à lista de permissões
Você usa 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 dos usuários. Quando você define uma lista de permissões, os projetos de script não podem acessar URLs que não foram adicionados a ela.
Esse campo é opcional ao instalar uma implantação de teste, mas é obrigatório ao criar uma implantação com controle de versões.
Você usa listas de permissão quando seu script ou complemento realiza as seguintes ações:
- Recupera ou busca informações de um local externo (como endpoints HTTPS) usando o serviço
UrlFetchdo Apps Script. Para permitir URLs para busca, inclua o campourlFetchWhitelistno arquivo de manifesto. - Abre ou mostra um URL em resposta a uma ação do usuário. Obrigatório para
complementos do Google Workspace que abrem ou mostram URLs externos ao
Google. Para permitir URLs na lista de permissões para abertura, inclua o campo
addOns.common.openLinkUrlPrefixesno arquivo de manifesto.
Adicionar prefixos à lista de permissões
Ao especificar listas de permissões no arquivo de manifesto (incluindo o campo addOns.common.openLinkUrlPrefixes ou urlFetchWhitelist), é necessário 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ãohttp://. - 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, mashttps://www.google.comnão é. - Você pode usar curingas para corresponder a prefixos de subdomínio de URL.
- Um único caractere curinga
*pode ser usado no campoaddOns.common.openLinkUrlPrefixespara 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 análise de complementos. Use um caractere curinga apenas se a funcionalidade do complemento exigir.
Ao determinar se um URL corresponde a um prefixo na lista de permissões, as seguintes regras são aplicadas:
- A correspondência de caminhos diferencia maiúsculas de minúsculas.
- Se o prefixo for idêntico ao URL, será uma correspondência.
- Se o URL for igual ou um filho do prefixo, será uma correspondência.
Por exemplo, o prefixo https://example.com/foo corresponde aos seguintes URLs:
https://example.com/foohttps://example.com/foo/https://example.com/foo/barhttps://example.com/foo?barhttps://example.com/foo#bar
Como usar caracteres curinga
Você pode usar um único caractere curinga (*) para corresponder a um subdomínio nos 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/foohttps://any.number.of.subdomains.example.com/foo
O prefixo https://*.example.com/foo não corresponde aos seguintes URLs:
https://subdomain.example.com/bar(sufixos diferentes)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 seguintes prefixos causam um erro se estiverem presentes no manifesto quando você tenta salvar:
https://*.*.example.com/foo(não é permitido usar vários caracteres curinga)https://subdomain.*.example.com/foo(os caracteres curinga precisam ser usados como um prefixo inicial)