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 las tareas que responden al contenido del mensaje, 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 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 visualizas un mensaje.
En ambos casos, el complemento ejecuta la función de activador contextual correspondiente, que se define en el manifiesto del complemento. El activador también se ejecuta si el usuario cambia a un mensaje diferente mientras el complemento está abierto. La función de activador contextual compila la IU del mensaje para ese mensaje, que luego Gmail le muestra al usuario.
Cómo compilar un complemento de Message
Puede agregar la función de mensajes a un complemento siguiendo 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 mensaje. Asegúrate de agregar un campo de activador condicional al manifiesto con un valor
unconditionalde{}. - 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 brindar asistencia a los usuarios durante la lectura de los 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 Gmail la muestre. En ese momento, el usuario puede comenzar a interactuar con él.
Los activadores contextuales se definen en el manifiesto del proyecto del complemento.
La definición del activador le indica a Gmail qué función del activador se debe activar en qué condiciones. Por ejemplo, en este fragmento de manifiesto se establece un activador incondicional que llama a la función activadora onGmailMessageOpen() cuando se abre un mensaje:
{
...
"addOns": {
"common": {
...
},
"gmail": {
"contextualTriggers": [
{
"unconditional": {},
"onTriggerFunction": "onGmailMessageOpen"
}
],
...
},
...
}
...
}
Función de activación contextual
Cada activador contextual debe tener una función de activación correspondiente que construya la interfaz de usuario del 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 arreglo 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 de activación 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, tu función activadora podría extraer el contenido de los mensajes mediante 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 activación puede actuar sobre estos datos y extraer la información que necesita para la interfaz. Por ejemplo, un complemento que resume las cifras 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 arreglo de objetos Card compilados. Por ejemplo, a continuación, se 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];
}