Como estender a interface de escrita com ações de escrita

Além de fornecer uma interface baseada em cards quando um usuário está lendo uma mensagem do Gmail, os complementos do Google Workspace que estendem o Gmail podem fornecer outra interface quando o usuário está escrevendo novas mensagens ou respondendo às existentes. Isso permite que os complementos do Google Workspace automatizem a tarefa de escrever e-mails para o usuário.

Acessar a interface do complemento

Há duas maneiras de ver a interface do usuário do complemento no Compose. A primeira maneira é começar a escrever um novo rascunho ou resposta enquanto o complemento já está aberto. A segunda maneira é iniciar o complemento ao escrever um rascunho.

Em ambos os casos, o complemento executa a função de acionamento de composição correspondente, definida no manifesto do complemento. A função de acionamento do Compose cria a interface do Compose para essa ação do Compose, que o Gmail mostra ao usuário.

Criar um complemento do Compose

Para adicionar a funcionalidade de composição a um complemento, siga estas etapas gerais:

1. Adicione o campo gmail.composeTrigger ao projeto de script do complemento manifesto e atualize os escopos do manifesto para incluir os necessários para ações de composição.
2. Implemente uma função de gatilho do Compose que crie uma interface do Compose quando o gatilho for disparado. As funções de acionamento do Compose retornam um único objeto Card ou uma matriz de objetos Card que compreendem a interface do Compose para a ação de composição.
3. Implemente as funções de callback associadas necessárias para reagir às interações do usuário com a interface do Compose. Essas funções não são a ação de composição em si (que apenas faz com que a interface do Compose apareça). Em vez disso, são as funções individuais que regem o que acontece quando diferentes elementos da interface do Compose são selecionados. Por exemplo, um card da interface que contém um botão geralmente tem uma função de callback associada que é executada quando um usuário clica nesse botão. A função de callback para widgets que atualizam o conteúdo da mensagem em rascunho precisa retornar um objeto UpdateDraftActionResponse.

Função de acionamento do Compose

A interface do usuário de composição de um complemento é criada da mesma forma que a interface do usuário de mensagens do complemento: usando o serviço de card do Apps Script para construir cards e preenchê-los com widgets.

Você precisa implementar o gmail.composeTrigger.selectActions[].runFunction que você define no manifesto. A função de gatilho de composição precisa retornar um único objeto Card ou uma matriz de objetos Card que compreendem a interface do Compose para essa ação. Essas funções são muito semelhantes às funções de acionamento contextual e devem criar cards da mesma forma.

Aviso: por motivos de segurança, os complementos não podem mudar silenciosamente as permissões de acesso a arquivos do Google Workspace ou de terceiros. Por exemplo, um complemento não pode adicionar destinatários de e-mail ao conjunto de contas que podem acessar um arquivo do Dropbox sem avisar. Em vez disso, o complemento precisa informar aos usuários que a mudança de permissão está ocorrendo. Os complementos que não informam os usuários sobre essas mudanças não podem passar pela análise de complementos.

Compor objetos de eventos de acionamento

Quando uma ação de composição é selecionada, ela executa a função de acionamento de composição correspondente e transmite à função um objeto de evento como um parâmetro. O objeto de evento pode conter informações sobre o contexto do complemento e o rascunho que está sendo composto para a função de acionamento.

Consulte Estrutura do objeto de evento para detalhes sobre como as informações são organizadas no objeto de evento. As informações contidas no objeto de evento são parcialmente controladas pelo valor do campo de manifesto gmail.composeTrigger.draftAccess:

• Se o campo gmail.composeTrigger.draftAccess do manifesto for NONE ou não estiver incluído, o objeto de evento terá apenas informações mínimas.

• Se gmail.composeTrigger.draftAccess estiver definido como METADATA, o objeto de evento transmitido para a função de gatilho de composição será preenchido com listas de destinatários do e-mail que está sendo composto.

Observação: para usar o acesso a rascunhos do METADATA, o manifesto do complemento precisa incluir o https://www.googleapis.com/auth/gmail.addons.current.message.metadata escopo do Gmail.

Inserir conteúdo em rascunhos ativos

Normalmente, uma interface do usuário de composição de complemento do Google Workspace oferece as opções e o controle do usuário que ajudam a compor uma mensagem. Para esses casos de uso, depois que o usuário faz seleções na interface, o complemento interpreta as seleções e atualiza o rascunho de e-mail em que está trabalhando.

Para facilitar a atualização do rascunho de e-mail atual, o serviço de card foi estendido com as seguintes classes:

• ContentType: um enum que define se é necessário adicionar HTML mutável, HTML imutável (que os usuários do Gmail não podem editar) ou conteúdo de texto simples.
• UpdateDraftActionResponse: representa uma resposta a uma ação que atualiza o rascunho de e-mail atual.
• UpdateDraftActionResponseBuilder: um builder para objetos UpdateDraftActionResponse.
• UpdateDraftBodyAction: representa uma ação que atualiza o corpo do e-mail em rascunho atual.
• UpdateDraftBodyType: uma enumeração que define como o corpo é alterado.
• UpdateDraftSubjectAction: representa uma ação que atualiza o campo de assunto do rascunho de e-mail atual.
• UpdateDraftToRecipientsAction: representa uma ação que atualiza os destinatários "Para" do e-mail em rascunho atual.
• UpdateDraftCcRecipientsAction: representa uma ação que atualiza os destinatários em cópia do e-mail em rascunho atual.
• UpdateDraftBccRecipientsAction: representa uma ação que atualiza os destinatários em cópia oculta do e-mail em rascunho atual.

Normalmente, uma interface do usuário de composição de complemento inclui um widget "Salvar" ou "Inserir" em que um usuário pode clicar para indicar que terminou de fazer seleções na interface e quer que as escolhas sejam adicionadas ao e-mail que está sendo escrito. Para adicionar essa interatividade, o widget precisa ter um objeto Action associado que instrua o complemento a executar uma função de callback específica quando o widget for clicado. Você precisa implementar essas funções de callback. Cada função de callback precisa retornar um objeto UpdateDraftActionResponse criado que detalha as mudanças a serem feitas no rascunho de e-mail atual.

Exemplo 1

O snippet de código a seguir mostra como criar uma interface do Compose que atualiza o assunto e os destinatários Para, Cc e Cco do rascunho de e-mail atual.

    /**
     * Compose trigger function that fires when the compose UI is
     * requested. Builds and returns a compose UI for inserting images.
     *
     * @param {event} e The compose trigger event object. Not used in
     *         this example.
     * @return {Card[]}
     */
    function getComposeUI(e) {
      return [buildComposeCard()];
    }

    /**
     * Build a card to display interactive buttons to allow the user to
     * update the subject, and To, Cc, Bcc recipients.
     *
     * @return {Card}
     */
    function buildComposeCard() {

      var card = CardService.newCardBuilder();
      var cardSection = CardService.newCardSection().setHeader('Update email');
      cardSection.addWidget(
          CardService.newTextButton()
              .setText('Update subject')
              .setOnClickAction(CardService.newAction()
                  .setFunctionName('applyUpdateSubjectAction')));
      cardSection.addWidget(
          CardService.newTextButton()
              .setText('Update To recipients')
              .setOnClickAction(CardService.newAction()
                  .setFunctionName('updateToRecipients')));
      cardSection.addWidget(
          CardService.newTextButton()
              .setText('Update Cc recipients')
              .setOnClickAction(CardService.newAction()
                  .setFunctionName('updateCcRecipients')));
      cardSection.addWidget(
          CardService.newTextButton()
              .setText('Update Bcc recipients')
              .setOnClickAction(CardService.newAction()
                  .setFunctionName('updateBccRecipients')));
      return card.addSection(cardSection).build();
    }

    /**
     * Updates the subject field of the current email when the user clicks
     * on "Update subject" in the compose UI.
     *
     * Note: This is not the compose action that builds a compose UI, but
     * rather an action taken when the user interacts with the compose UI.
     *
     * @return {UpdateDraftActionResponse}
     */
    function applyUpdateSubjectAction() {
      // Get the new subject field of the email.
      // This function is not shown in this example.
      var subject = getSubject();
      var response = CardService.newUpdateDraftActionResponseBuilder()
          .setUpdateDraftSubjectAction(CardService.newUpdateDraftSubjectAction()
              .addUpdateSubject(subject))
          .build();
      return response;
    }

    /**
     * Updates the To recipients of the current email when the user clicks
     * on "Update To recipients" in the compose UI.
     *
     * Note: This is not the compose action that builds a compose UI, but
     * rather an action taken when the user interacts with the compose UI.
     *
     * @return {UpdateDraftActionResponse}
     */
    function applyUpdateToRecipientsAction() {
      // Get the new To recipients of the email.
      // This function is not shown in this example.
      var toRecipients = getToRecipients();
      var response = CardService.newUpdateDraftActionResponseBuilder()
          .setUpdateDraftToRecipientsAction(CardService.newUpdateDraftToRecipientsAction()
              .addUpdateToRecipients(toRecipients))
          .build();
      return response;
    }

    /**
     * Updates the Cc recipients  of the current email when the user clicks
     * on "Update Cc recipients" in the compose UI.
     *
     * Note: This is not the compose action that builds a compose UI, but
     * rather an action taken when the user interacts with the compose UI.
     *
     * @return {UpdateDraftActionResponse}
     */
    function applyUpdateCcRecipientsAction() {
      // Get the new Cc recipients of the email.
      // This function is not shown in this example.
      var ccRecipients = getCcRecipients();
      var response = CardService.newUpdateDraftActionResponseBuilder()
          .setUpdateDraftCcRecipientsAction(CardService.newUpdateDraftCcRecipientsAction()
              .addUpdateToRecipients(ccRecipients))
          .build();
      return response;
    }

    /**
     * Updates the Bcc recipients  of the current email when the user clicks
     * on "Update Bcc recipients" in the compose UI.
     *
     * Note: This is not the compose action that builds a compose UI, but
     * rather an action taken when the user interacts with the compose UI.
     *
     * @return {UpdateDraftActionResponse}
     */
    function applyUpdateBccRecipientsAction() {
      // Get the new Bcc recipients of the email.
      // This function is not shown in this example.
      var bccRecipients = getBccRecipients();
      var response = CardService.newUpdateDraftActionResponseBuilder()
          .setUpdateDraftBccRecipientsAction(CardService.newUpdateDraftBccRecipientsAction()
              .addUpdateToRecipients(bccRecipients))
          .build();
      return response;
    }

Exemplo 2

O snippet de código a seguir mostra como criar uma interface do Compose que insere imagens no rascunho de e-mail atual.

    /**
     * Compose trigger function that fires when the compose UI is
     * requested. Builds and returns a compose UI for inserting images.
     *
     * @param {event} e The compose trigger event object. Not used in
     *         this example.
     * @return {Card[]}
     */
    function getInsertImageComposeUI(e) {
      return [buildImageComposeCard()];
    }

    /**
     * Build a card to display images from a third-party source.
     *
     * @return {Card}
     */
    function buildImageComposeCard() {
      // Get a short list of image URLs to display in the UI.
      // This function is not shown in this example.
      var imageUrls = getImageUrls();

      var card = CardService.newCardBuilder();
      var cardSection = CardService.newCardSection().setHeader('My Images');
      for (var i = 0; i < imageUrls.length; i++) {
        var imageUrl = imageUrls[i];
        cardSection.addWidget(
            CardService.newImage()
                .setImageUrl(imageUrl)
                .setOnClickAction(CardService.newAction()
                      .setFunctionName('applyInsertImageAction')
                      .setParameters({'url' : imageUrl})));
      }
      return card.addSection(cardSection).build();
    }

    /**
     * Adds an image to the current draft email when the image is clicked
     * in the compose UI. The image is inserted at the current cursor
     * location. If any content of the email draft is currently selected,
     * it is deleted and replaced with the image.
     *
     * Note: This is not the compose action that builds a compose UI, but
     * rather an action taken when the user interacts with the compose UI.
     *
     * @param {event} e The incoming event object.
     * @return {UpdateDraftActionResponse}
     */
    function applyInsertImageAction(e) {
      var imageUrl = e.parameters.url;
      var imageHtmlContent = '<img style=\"display: block\" src=\"'
           + imageUrl + '\"/>';
      var response = CardService.newUpdateDraftActionResponseBuilder()
          .setUpdateDraftBodyAction(CardService.newUpdateDraftBodyAction()
              .addUpdateContent(
                  imageHtmlContent,
                  CardService.ContentType.MUTABLE_HTML)
              .setUpdateType(
                  CardService.UpdateDraftBodyType.IN_PLACE_INSERT))
          .build();
      return response;
    }