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 mensagens. Isso permite que osGoogle Workspace complementos automatizem tarefas que respondam ao conteúdo da mensagem, como exibir, recuperar ou enviar outras informações relacionadas à mensagem.

Como acessar a IU da mensagem de complemento

Há duas maneiras de visualizar 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 ao visualizar uma mensagem.

Os dois casos fazem com que o complemento execute a função de gatilho contextual correspondente, definida no manifesto do complemento. O gatilho também é 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, 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 de 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 oferecer assistência aos usuários ao ler mensagens, os complementosGoogle Workspace podem definir um acionador de contexto nos próprios manifestos. Quando o usuário abre uma mensagem do Gmail (com o complemento aberto) que atende aos critérios de acionamento*, o acionador é disparado. Um acionador acionado executa uma função de acionador contextual que constrói a interface do usuário complementar e a retorna para o Gmail exibir. Nesse momento, o usuário pode começar a interagir com ele.

Os acionadores contextuais são definidos no manifesto do projeto dos seus complementos. Ela define o Gmail qual função de acionamento deve ser disparada em quais condições. Por exemplo, o 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 acionador contextual

Cada gatilho contextual precisa ter uma função de gatilho correspondente que construa 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 a ela um objeto de evento de ação. Muitas vezes, 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 gatilho pode extrair 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();

Em seguida, 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 os números de vendas pode coletar números de vendas do 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. O exemplo 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];
  }