Como estender a IU da mensagem

Os complementos do Google Workspace que ampliam o Gmail podem oferecer uma interface do usuário quando o usuário está lendo mensagens. Isso permite que os complementos do Google Workspace automatizem tarefas que respondem ao conteúdo da mensagem, como exibir, recuperar ou enviar outras informações relacionadas a ela.

Acessar a IU da mensagem do complemento

Há duas maneiras de ver a IU de mensagens de um complemento. A primeira maneira é abrir uma mensagem enquanto o complemento já está aberto (por exemplo, ao visualizar a página inicial do complemento na janela da caixa de entrada do Gmail). A segunda maneira é iniciar o complemento enquanto visualiza uma mensagem.

Ambos os casos fazem com que o complemento execute a função de gatilho contextual correspondente, definida no manifesto do complemento. O acionador também é executado se o usuário alternar para uma mensagem diferente enquanto o complemento ainda está aberto. A função de gatilho contextual cria a IU da 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:

1. Adicione os campos apropriados ao manifesto do projeto de script de complemento, incluindo os escopos necessários para a funcionalidade da mensagem. Adicione um campo de gatilho condicional ao manifesto com o valor unconditional de {}.
2. Implemente uma função de gatilho contextual que crie uma IU de mensagem quando o usuário seleciona o complemento em uma mensagem.
3. Implemente funções associadas necessárias para responder às interações de IU do usuário.

Gatilhos contextuais

Para oferecer assistência aos usuários ao 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 atende aos critérios do acionador,* o acionador é disparado. Um acionador disparado executa uma função de acionador contextual que constrói a interface do usuário do complemento e a retorna para o Gmail exibir. Nesse ponto, o usuário pode começar a interagir com ele.

Os acionadores contextuais são definidos no manifesto do projeto do complemento. A definição do acionador informa ao Gmail qual função de acionador disparar em quais 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 crie a interface do usuário do seu complemento. Você especifica essa função no campo onTriggerFunction do manifesto. Implemente essa função para aceitar um argumento de objeto de evento de ação e retornar um único objeto Card ou uma matriz de objetos Card.

Quando um acionador contextual é disparado para uma determinada mensagem do Gmail, ele chama essa função e transmite um 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 o serviço do Gmail do Apps Script. Por exemplo, a função de 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 nesses dados, extraindo as informações necessárias para a interface. Por exemplo, um complemento que resume os números de vendas pode coletar valores de vendas no corpo da mensagem e organizá-los para exibição em um card.

A função de gatilho precisa criar e retornar uma matriz de objetos Card criados. Por exemplo, o código a seguir cria um complemento com um único card 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];
  }