Activadores de los complementos de Google Workspace

Los activadores de Apps Script hacen que se ejecute una función de secuencia de comandos específica (la función de activación) cada vez que ocurre un evento específico. Solo ciertos eventos pueden hacer que se activen los activadores, y cada aplicación de Google Workspace admite un conjunto diferente de eventos.

Cuando se activa un activador, se crea un objeto de evento. Esta estructura JSON contiene detalles sobre el evento que ocurrió. La información en la estructura del objeto de evento se organiza de manera diferente según el tipo de activador.

Una vez que se crea el objeto del evento, Apps Script lo pasa como parámetro a la función del activador. La función activadora es una función de devolución de llamada que debes implementar por tu cuenta a fin de realizar las acciones apropiadas para responder al evento. Por ejemplo, en un complemento de Google Workspace que extiende Gmail, puedes definir un activador que cree una interfaz de tarjeta nueva cuando el usuario abra una conversación de mensaje. En este caso, implementas una función de devolución de llamada contextual para crear las tarjetas que conforman la IU nueva con los datos pasados en el objeto del evento.

En esta página, se proporcionan lineamientos sobre el uso de activadores en proyectos de complementos de Google Workspace.

Activadores del manifiesto

A diferencia de los complementos de Editores, por el momento, los complementos de Google Workspace no pueden usar activadores simples de Apps Script. En cambio, usan activadores diseñados específicamente para los complementos de Google Workspace: activadores de manifiesto.

Los activadores del manifiesto se definen por completo en el manifiesto del complemento de Google Workspace. Entre los ejemplos de activadores de manifiesto, se incluyen los siguientes:

  • Activadores de la página principal que compilan y muestran la página principal del complemento
  • Activadores de eventOpen de Calendario que muestran una tarjeta nueva o realizan otras acciones cuando se abre un evento de Calendario.
  • Activadores de eventUpdate de Calendario que muestran una tarjeta nueva o realizan otras acciones cuando un usuario edita y guarda un evento de Calendario.
  • Activadores de Drive onItemsSelected que muestran una tarjeta nueva o realizan otras acciones cuando un usuario selecciona uno o más archivos o carpetas en Drive
  • Activadores de redacción de Gmail que muestran una tarjeta del complemento cuando el usuario lo abre en la ventana de redacción de Gmail
  • Activadores contextuales de Gmail que muestran una tarjeta nueva o realizan otras acciones cuando el usuario abre un mensaje de Gmail
  • Activadores de Editor onFileScopeGranted que muestran una tarjeta nueva cuando los usuarios otorgan autorización para el permiso de OAuth drive.file en el documento actual de Editor.

En la lista anterior, solo los activadores de la página principal son no contextuales; el resto son activadores contextuales. Consulta Manifiesto para obtener más información sobre las definiciones de los activadores de manifiesto.

Además de los activadores de manifiesto, los complementos de Google Workspace también pueden usar activadores instalables de Apps Script.

Restricciones

Los activadores de manifiestos tienen ciertas restricciones de uso.

  • Estos activadores solo se usan en proyectos de complementos de Google Workspace; no tienen propósito en ninguna otra aplicación.
  • Dado que se definen en el manifiesto del complemento y no en su código, no puedes usar el servicio Script de Apps Script para crear o modificar estos activadores.
  • Por el momento, los activadores contextuales de Gmail solo pueden tener un criterio unconditional. Esto significa que los activadores contextuales se activan para cada mensaje de correo electrónico, sin importar el contenido.
  • Cada complemento solo puede tener un activador de cada tipo, por usuario y por documento.