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 de complementos
Existen dos formas 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 de la bandeja de entrada de Gmail). La segunda forma es iniciar el complemento mientras ves un mensaje.
En ambos casos, el complemento ejecuta la función de activación contextual correspondiente, definida en el manifiesto del complemento. El activador también se ejecuta si el usuario cambia a otro mensaje mientras el complemento sigue abierto. La función de activación contextual crea la IU del mensaje, que Gmail luego muestra al usuario.
Cómo crear un complemento de mensajes
Para agregar la funcionalidad de mensajes a un complemento, sigue estos pasos generales:
- Agrega los campos correspondientes al manifiesto del proyecto de secuencia de comandos del complemento, incluidos los alcances necesarios para la funcionalidad de mensajes. Asegúrate de agregar un campo de activación condicional al manifiesto, con un valor de
unconditionalde{}. - Implementa una función de activación contextual que compile una IU de mensajes cuando el usuario seleccione el complemento en un mensaje.
- Implementa las funciones asociadas necesarias para responder a las interacciones del usuario con la IU.
Activadores contextuales
Para brindar 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 que se dispara ejecuta una función de activación contextual que construye la interfaz de usuario del complemento y la devuelve 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 del complemento.
La definición del activador le indica a Gmail qué función de activación debe ejecutarse y en qué condiciones. Por ejemplo, este fragmento del manifiesto establece un activador incondicional que llama a la función de activación 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 cree 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 de Gmail determinado, se llama a esta función y se le pasa un objeto de evento de acción. A menudo, las funciones activadas 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 activación 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 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 los datos de ventas del cuerpo del mensaje y organizarlos para mostrarlos en una tarjeta.
La función de activación debe compilar y devolver un array de objetos Card compilados. Por ejemplo, el siguiente código 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];
}