Como estender a IU da mensagem

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

Como acessar a IU da mensagem do complemento

Existem duas formas 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 durante a visualização de uma mensagem.

Em ambos os casos, o complemento executa a função de acionamento contextual correspondente, definida no manifesto do complemento. O acionador também será executado se o usuário mudar para uma mensagem diferente enquanto o complemento ainda estiver aberto. A função de gatilho contextual cria a IU da mensagem para essa mensagem, que o Gmail exibe ao usuário.

Criação de um complemento de mensagem

Para adicionar a funcionalidade de mensagens a um complemento, siga estas etapas gerais:

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

Gatilhos contextuais

Para ajudar os usuários a ler mensagens, os complementosGoogle 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 cria a interface do usuário complementar e a retorna para que o Gmail exiba. Nesse momento, o usuário pode começar a interagir com ele.

Os acionadores contextuais são definidos no manifesto do projeto de complemento. A definição do gatilho informa ao Gmail qual função é acionada em determinadas condições. Por exemplo, este snippet de manifesto define um acionador incondicional que chama a função onGmailMessageOpen() quando uma mensagem é aberta:

{
  ...
  "addOns": {

    "common": {
      ...
    },
    "gmail": {
      "contextualTriggers": [
        {
          "unconditional": {},
          "onTriggerFunction": "onGmailMessageOpen"
        }
      ],
      ...
    },
    ...
  }
  ...
}

Função de acionamento contextual

Cada acionador contextual precisa ter uma função de acionamento 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. Geralmente, as funções de gatilho 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 acionamento pode extrair conteúdo de mensagens 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 atuar nesses dados, extraindo as informações necessárias para a interface. Por exemplo, um complemento que resume os números de vendas pode coletar os valores no corpo da mensagem e organizá-los para que sejam exibidos em um card.

A função de gatilho precisa criar e retornar uma matriz de objetos Card. O exemplo a seguir cria um complemento com um único card que lista apenas 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];
  }