Extiende la IU del mensaje

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

Cómo acceder a la IU de mensajes del complemento

Hay 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 ves la página principal del complemento en la ventana de Recibidos de Gmail). La segunda forma es iniciar el complemento mientras ves un mensaje.

Cualquiera de estas situaciones hace que el complemento ejecute 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 todavía está abierto. La función de activación contextual compila la IU para ese mensaje, que Gmail le muestra al usuario.

Cómo crear un complemento de mensaje

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

  1. Agrega los campos adecuados al manifiesto del proyecto de secuencia de comandos de complementos, incluidos los alcances necesarios para la funcionalidad del mensaje. Asegúrate de agregar un campo de activación condicional al manifiesto, con un valor unconditional de {}.
  2. Implementa una función de activador contextual que compile una IU para 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 lean mensajes, los complementos de Google Workspace 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*, el activador se activa. Un activador activado ejecuta una función de activador contextual que construye la interfaz de usuario del complemento y la muestra para que la muestre Gmail. En ese momento, el usuario puede comenzar a interactuar con él.

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 se debe activar y 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. Debes especificar esta función en el campo onTriggerFunction de tu manifiesto. Implementas esta función para aceptar un argumento de objeto de evento de acción y mostrar un solo objeto Card o un array de objetos Card.

Cuando un activador contextual se activa 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 del activador usan el ID de mensaje que proporciona este objeto de evento para obtener el texto del mensaje y otros detalles mediante el servicio de Gmail de Apps Script. Por ejemplo, la función activador podría extraer contenido del mensaje con las siguientes 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 del 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 que se muestren en una tarjeta.

La función del activador debe compilar y mostrar un arreglo de objetos Card compilados. Por ejemplo, a continuación, se compila un complemento con una sola tarjeta que solo enumera 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.newKeyValue()
                .setTopLabel('Subject')
                .setContent(subject))
            .addWidget(CardService.newKeyValue()
                .setTopLabel('From')
                .setContent(sender)))
        .build();   // Don't forget to build the Card!
    return [exampleCard];
  }