Cómo extender la IU de Compose con acciones de Compose

Además de proporcionar una interfaz basada en tarjetas cuando un usuario lee un mensaje de Gmail, los complementos de Google Workspace que extienden Gmail pueden proporcionar otra interfaz cuando el usuario redacta mensajes nuevos o responde mensajes existentes. Esto permite que los complementos de Google Workspace automaticen la tarea de redactar correos electrónicos para el usuario.

Cómo acceder a la IU de Compose del complemento

Hay dos maneras de ver la IU de redacción de un complemento. La primera es comenzar a redactar un nuevo borrador o responder mientras el complemento ya está abierto. La segunda forma es iniciar el complemento mientras redactas un borrador.

En ambos casos, el complemento ejecuta la función activadora de composición correspondiente, que se define en el manifiesto del complemento. La función de activador de redacción compila la IU de composición para esa acción de redacción, que Gmail muestra al usuario.

Cómo compilar un complemento de Compose

Puedes agregar la función de redacción a un complemento siguiendo estos pasos generales:

1. Agrega el campo gmail.composeTrigger al manifiesto del proyecto de secuencia de comandos del complemento y actualiza los alcances del manifiesto a fin de incluir aquellos necesarios para las acciones de redacción.
2. Implementa una función de activador de composición que compile una IU de composición cuando el activador se active. Las funciones del activador de Compose muestran un solo objeto Card o un array de objetos Card que componen la IU de composición para la acción de composición.
3. Implementa las funciones de devolución de llamada asociadas que se necesitan para reaccionar a las interacciones de IU de redacción del usuario. Estas funciones no son la acción de redacción en sí (que solo hace que aparezca la IU de redacción). En su lugar, son las funciones individuales que rigen lo que sucede cuando se seleccionan diferentes elementos de la IU de composición. Por ejemplo, una tarjeta de IU que contiene un botón suele tener una función de devolución de llamada asociada que se ejecuta cuando un usuario hace clic en ese botón. La función de devolución de llamada para widgets que actualizan el contenido del mensaje en borrador debe mostrar un objeto UpdateDraftActionResponse.

Función de activación de Compose

La IU de redacción de un complemento se compila de la misma manera que la IU de mensajes del complemento: se usa el servicio Card de Apps Script para crear tarjetas y llenarlas con widgets.

Debes implementar el gmail.composeTrigger.selectActions[].runFunction que definas en el manifiesto. La función de activador de composición debe mostrar un solo objeto Card o un arreglo de objetos Card que componen la IU de composición para esa acción. Estas funciones son muy similares a las funciones de activador contextuales y deben compilar tarjetas de la misma manera.

Advertencia: Por motivos de seguridad, los complementos no pueden cambiar de forma silenciosa los permisos de acceso a archivos de Google Workspace o de terceros. Por ejemplo, un complemento no puede agregar silenciosamente destinatarios de correo electrónico al conjunto de cuentas que pueden ver un archivo de Dropbox. En cambio, el complemento debe informar a los usuarios que se está realizando el cambio de permiso. Los complementos que no informan a los usuarios sobre tales cambios no pueden pasar la revisión del complemento.

Objetos de evento de activación de Compose

Cuando se selecciona una acción de redacción, ejecuta la función de activador de composición correspondiente y pasa la función a un objeto de evento como parámetro. El objeto de evento puede llevar información sobre el contexto del complemento y el borrador que se compone en la función de activación.

Consulta la Estructura del objeto de evento para obtener detalles sobre cómo se organiza la información en el objeto de evento. La información que se incluye en el objeto de evento está parcialmente controlada por el valor del campo de manifiesto gmail.composeTrigger.draftAccess:

• Si el campo de manifiesto gmail.composeTrigger.draftAccess es NONE o no se incluye, el objeto de evento solo tiene información mínima.

• Si gmail.composeTrigger.draftAccess se establece en METADATA, el objeto de evento pasado a la función de activador de redacción se propaga con listas de destinatarios del correo electrónico que se está redactando.

Nota: Para usar el acceso de borrador METADATA, el manifiesto del complemento debe incluir el https://www.googleapis.com/auth/gmail.addons.current.message.metadata permiso de Gmail.

Insertar contenido en borradores activos

Por lo general, la IU de redacción de un complemento de Google Workspace proporciona las opciones y el control del usuario que ayudan a redactar un mensaje. Para estos casos prácticos, una vez que el usuario realiza selecciones en la IU, el complemento interpreta las selecciones y actualiza el borrador del correo electrónico en funcionamiento actual según corresponda.

Para facilitar la actualización del borrador del correo electrónico actual, el servicio de Card se extendió con las siguientes clases:

• ContentType: Es una enumeración que define si se debe agregar HTML mutable, HTML inmutable (que los usuarios de Gmail no pueden editar) o contenido de texto sin formato.
• UpdateDraftActionResponse: Representa la respuesta a una acción que actualiza el borrador del correo electrónico actual.
• UpdateDraftActionResponseBuilder: Es un compilador para objetos UpdateDraftActionResponse.
• UpdateDraftBodyAction: Representa una acción que actualiza el cuerpo del borrador de correo electrónico actual.
• UpdateDraftBodyType: Una enumeración que define cómo se cambia el cuerpo.
• UpdateDraftSubjectAction: Representa una acción que actualiza el campo de asunto del borrador de correo electrónico actual.
• UpdateDraftToRecipientsAction: Representa una acción que actualiza los destinatarios de los correos electrónicos en borrador.
• UpdateDraftCcRecipientsAction: Representa una acción que actualiza los destinatarios en Cc del borrador del correo electrónico actual.
• UpdateDraftBccRecipientsAction: Representa una acción que actualiza los destinatarios del campo Cco del correo electrónico borrador actual.

Por lo general, la IU de un complemento de redacción incluye un widget de "Guardar" o "Insertar" en el que un usuario puede hacer clic para indicar que completó la selección en la IU y desea que sus opciones se agreguen al correo electrónico que está redactando. Para agregar esta interactividad, el widget debe tener un objeto Action asociado que le indique al complemento que ejecute una función de devolución de llamada específica cuando se haga clic en el widget. Debes implementar estas funciones de devolución de llamada. Cada función de devolución de llamada debe mostrar un objeto UpdateDraftActionResponse compilado que detalla los cambios que se realizarán en el borrador del correo electrónico actual.

Ejemplo 1

En el siguiente fragmento de código, se muestra cómo compilar una IU de redacción para actualizar el asunto, y los destinatarios a, Cc y Cco del borrador del correo electrónico actual.

    /**
     * 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;
    }

Ejemplo 2

En el siguiente fragmento de código, se muestra cómo compilar una IU de redacción que inserta imágenes en el borrador del correo electrónico actual.

    /**
     * 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;
    }