Extiende la IU de mensajes

Los complementos de Google Workspace que extienden Gmail pueden proporcionar una interfaz de usuario cuando el usuario lee mensajes. Esto permite que los complementos automaticen tareas que responden al contenido del mensaje, como mostrar, recuperar o enviar información adicional relacionada con el mensaje.

Accede a la IU de mensajes del complemento de Google Workspace

Existen dos maneras de ver la IU de mensajes de un complemento. La primera es abrir un mensaje mientras el complemento ya está abierto (por ejemplo, cuando se ve la página principal del complemento en la ventana de la carpeta Recibidos de Gmail). La segunda es iniciar el complemento mientras ves un mensaje.

En cualquier caso, el complemento ejecuta la función de activador contextual correspondiente, definida en el manifiesto del complemento. El activador también se ejecuta si el usuario cambia a un mensaje diferente mientras el complemento aún está abierto. La función de activador contextual compila la IU de mensajes para ese mensaje, que luego Gmail muestra al usuario.

Crea un complemento de mensajes

Para agregar funcionalidad de mensajes a un complemento, sigue estos pasos generales:

1. Agrega los campos adecuados al manifiesto del proyecto de secuencia de comandos del complemento , incluidos los permisos necesarios para la funcionalidad de mensajes. Asegúrate de agregar un campo de activador condicional al manifiesto, con un unconditional valor de {}.
2. Implementa una función de activador contextual que compile una IU de mensajes cuando el usuario seleccione el complemento en un mensaje.
3. Implementa las funciones asociadas necesarias para responder a las interacciones de la IU del usuario.

Activadores contextuales

Para brindar asistencia a los usuarios cuando leen mensajes, los complementos pueden definir un activador contextual en sus manifiestos. Cuando el usuario abre un mensaje de Gmail (con el complemento abierto) que cumple con los criterios del activador* se activa el activador. Un activador activado ejecuta una función de activador contextual que construye la interfaz de usuario del complemento y la muestra para que Gmail la muestre. En ese momento, el usuario puede comenzar a interactuar con ella.

Los activadores contextuales se definen en el manifiesto del proyecto de tu complemento. La definición del activador le indica a Gmail qué función de activador activar en qué condiciones. Por ejemplo, este fragmento de manifiesto establece un activador incondicional que llama a la función de activador onGmailMessageOpen() cuando se abre un mensaje:

{
  ...
  "addOns": {

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

Función de activador contextual

Cada activador contextual debe tener una función de activador correspondiente que construya la interfaz de usuario de tu complemento. Especifica esta función en el campo onTriggerFunction de tu manifiesto. Implementa esta función para aceptar un argumento de objeto de evento de acción y mostrar un solo objeto Cardo un array de objetos Card.

Cuando se activa un activador contextual para un mensaje de Gmail determinado, llama a esta función y le pasa un objeto de evento de acción. A menudo, las funciones de activador usan el ID de mensaje que proporciona este objeto de evento para obtener el texto del mensaje y otros detalles con el servicio de Gmail de Apps Script's . En la mayoría de los casos, debes activar los permisos de Gmail con el token de acceso que proporciona el objeto de evento y la GmailApp.setCurrentMessageAccessToken(accessToken) función antes de usar otras funciones del servicio de Gmail. Por ejemplo, la función de activador podría extraer el contenido del mensaje con estas funciones:

// 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();

Luego, la función de activador puede actuar sobre estos datos y extraer la información que necesita para la interfaz. Por ejemplo, un complemento que resume los números de ventas puede recopilar cifras de ventas del cuerpo del mensaje y organizarlas para mostrarlas en una tarjeta.

La función de activador debe compilar y mostrar un array de objetos Card compilados. Por ejemplo, el siguiente código compila un complemento con una sola tarjeta que solo muestra el asunto y el remitente del mensaje:

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.newDecoratedText()
              .setTopLabel('Subject')
              .setText(subject))
          .addWidget(CardService.newDecoratedText()
              .setTopLabel('From')
              .setText(sender)))
      .build();   // Don't forget to build the Card!
  return [exampleCard];
}