Os complementos do Google Workspace que ampliam os recursos do Gmail uma interface do usuário quando o usuário está lendo mensagens. Isso permite Complementos do Google Workspace para automatizar tarefas que respondem às ao conteúdo da mensagem, como exibição, recuperação ou envio informações adicionais relacionadas à mensagem.
Como acessar a interface da mensagem de complementos
Há duas maneiras de ver a interface da mensagem de um complemento. A primeira é abrir uma mensagem enquanto o complemento já estiver aberto (por exemplo, ao visualizar na página inicial do complemento na janela da caixa de entrada do Gmail). A segunda maneira é iniciar o complemento enquanto visualiza uma mensagem.
Os dois casos fazem com que o complemento execute a função de gatilho contextual, definida na manifesto do complemento. O gatilho também é executado se o usuário mudar para uma mensagem diferente enquanto o ainda está aberto. A função de gatilho contextual cria a interface de mensagem para essa mensagem, que o Gmail exibe ao usuário.
Como criar um complemento de mensagem
Para adicionar a funcionalidade de mensagem a um complemento, siga estas etapas gerais:
- Adicione os campos apropriados ao projeto de script do complemento
manifesto,
incluindo os
escopos necessários para
a funcionalidade de mensagens. Certifique-se de adicionar um
campo "Gatilho condicional"
ao manifesto, com um
unconditional
de{}
. - Implementar uma função de gatilho contextual que crie uma interface de mensagem quando o usuário seleciona o complemento em uma mensagem.
- Implementar funções associadas necessárias para responder à interface do usuário e interações.
Gatilhos contextuais
Para ajudar os usuários a ler mensagens, Os complementos do Google Workspace podem definir um acionador contextual nos manifestos. Quando o usuário abre uma mensagem do Gmail (com o complemento aberto) que corresponde ao acionador * o acionador é disparado. Um acionador disparado executa uma função de gatilho contextual que cria a da interface do usuário do complemento e a retorna para exibição no Gmail. Nesse ponto, usuário possa começar a interagir com ele.
Os gatilhos contextuais são definidos no projeto do complemento
manifesto.
A definição do gatilho informa ao Gmail qual função de gatilho será disparada e em qual delas
pelas condições Por exemplo, este snippet de manifesto define um gatilho incondicional
que chama a função de gatilho onGmailMessageOpen()
quando uma mensagem é aberta:
{ ... "addOns": { "common": { ... }, "gmail": { "contextualTriggers": [ { "unconditional": {}, "onTriggerFunction": "onGmailMessageOpen" } ], ... }, ... } ... }
Função de gatilho contextual
Cada acionador contextual precisa ter uma função de acionador correspondente
que cria a interface de usuário do seu complemento. Você especifica essa função no
onTriggerFunction
do manifesto
. Implemente essa função para aceitar uma
objeto de evento de ação
e retornam um único
objeto Card
ou uma matriz de
Objetos Card
.
Quando um acionador contextual é disparado para uma determinada mensagem do Gmail, ele chama este e a passa uma objeto de evento de ação. Muitas vezes, as funções de acionamento usam o ID da mensagem fornecido por esse objeto de evento para receber o texto da mensagem e outros detalhes usando a serviço do Gmail. Por exemplo, seu gatilho pode extrair o conteúdo da mensagem usando estas funções:
// Activate temporary Gmail scopes, in this case to allow
// the add-on to read message metadata and content.
var accessToken = e.gmail.accessToken;
GmailApp.setCurrentMessageAccessToken(accessToken);
// Read message metadata and content. This requires the Gmail scope
// https://www.googleapis.com/auth/gmail.addons.current.message.readonly.
var messageId = e.gmail.messageId;
var message = GmailApp.getMessageById(messageId);
var subject = message.getSubject();
var sender = message.getFrom();
var body = message.getPlainBody();
var messageDate = message.getDate();
// Setting the access token with a gmail.addons.current.message.readonly
// scope also allows read access to the other messages in the thread.
var thread = message.getThread();
var threadMessages = thread.getMessages();
// Using this link can avoid the need to copy message or thread content
var threadLink = thread.getPermalink();
A função de gatilho pode agir com base nesses dados, extraindo as informações necessárias para a interface. Por exemplo, um complemento que resume as vendas Os números podem coletar dados de vendas no corpo da mensagem e organizá-los exibir em um card.
A função de gatilho deve criar e retornar uma matriz de objetos
Card
objetos. Por exemplo, o código abaixo cria um complemento com um único cartão que
apenas lista o assunto e o remetente da mensagem:
function onGmailMessageOpen(e) {
// Activate temporary Gmail scopes, in this case to allow
// message metadata to be read.
var accessToken = e.gmail.accessToken;
GmailApp.setCurrentMessageAccessToken(accessToken);
var messageId = e.gmail.messageId;
var message = GmailApp.getMessageById(messageId);
var subject = message.getSubject();
var sender = message.getFrom();
// Create a card with a single card section and two widgets.
// Be sure to execute build() to finalize the card construction.
var exampleCard = CardService.newCardBuilder()
.setHeader(CardService.newCardHeader()
.setTitle('Example card'))
.addSection(CardService.newCardSection()
.addWidget(CardService.newKeyValue()
.setTopLabel('Subject')
.setContent(subject))
.addWidget(CardService.newKeyValue()
.setTopLabel('From')
.setContent(sender)))
.build(); // Don't forget to build the Card!
return [exampleCard];
}