Se usó la API de Cloud Translation para traducir esta página.

Extensión de 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 del mensaje del complemento

Existen dos maneras de ver la IU de mensajes de un complemento. La primera forma es abrir un mensaje mientras el complemento ya está abierto (por ejemplo, cuando se ve la página principal del complemento en la ventana Recibidos de Gmail). La segunda forma 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 sigue abierto. La función del activador contextual compila la IU del mensaje para ese mensaje, que Gmail le muestra al usuario.

Cómo compilar un complemento de mensajes

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

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

Activadores contextuales

Para brindarles asistencia a los usuarios cuando leen 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*, 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 la muestre Gmail. 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 debe activarse en qué condiciones. Por ejemplo, este fragmento de manifiesto establece un activador no condicional que llama a la función de activador onGmailMessageOpen() cuando se abre un mensaje:

{
  ...
  "addOns": {

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

Actualmente, el único tipo de activador contextual disponible es unconditional, que se activa para todos los correos electrónicos, independientemente del contenido.

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. Especificas esta función en el campo onTriggerFunction del 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 se activa un activador contextual para un mensaje determinado de Gmail, llama a esta función y le pasa un objeto de evento de acción. A menudo, las funciones de activación 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. Por ejemplo, tu función de activado podría extraer el contenido de los mensajes 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 del activador puede actuar en estos datos y extraer la información que necesita para la interfaz. Por ejemplo, un complemento que resuma los números de ventas puede recopilar las cifras de ventas del cuerpo del mensaje y organizarlas para mostrarlas en una tarjeta.

La función del activador debe compilar y mostrar un array de objetos Card compilados. Por ejemplo, el siguiente comando 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.newKeyValue()
                .setTopLabel('Subject')
                .setContent(subject))
            .addWidget(CardService.newKeyValue()
                .setTopLabel('From')
                .setContent(sender)))
        .build();   // Don't forget to build the Card!
    return [exampleCard];
  }