Objetos de eventos

En esta página, se describe la estructura de los objetos de eventos de complementos de Google Workspace.

Los objetos de evento son estructuras JSON que se construyen automáticamente y se pasan como parámetros para activar funciones o devolver llamadas cuando un usuario interactúa con un complemento. Los objetos de evento llevan información del cliente sobre la app host y el contexto actual a la función de devolución de llamada del servidor del complemento.

Los complementos de Google Workspace usan objetos de evento en los siguientes lugares:

• Activadores de la página principal: A cada función homepageTrigger que definas se le pasa automáticamente un objeto de evento cuando se activa la función del activador de la página principal. Puedes usar este objeto en tu función de activación de la página principal para identificar la app de host activa, la plataforma del cliente, la configuración regional del usuario y otra información.

  Los objetos de evento creados cuando se activa la página principal no contienen todos los campos incluidos en los otros dos casos; se omiten los campos relacionados con los widgets y la información contextual.

• Activadores contextuales: Cada aplicación host proporciona un conjunto diferente de activadores contextuales que se activan cuando el usuario ingresa a un contexto específico. Por ejemplo:

  • Gmail proporciona un activador contextual para cuando un usuario abre un mensaje y otro cuando un usuario compone un mensaje.
  • El Calendario de Google proporciona un activador contextual para cuando un usuario abre un evento.
  • Google Drive proporciona un activador contextual para cuando un usuario selecciona archivos de Drive.

  Cuando se activa un activador contextual, la aplicación host llama al runFunction correspondiente que se indica en el manifiesto del complemento y le pasa un objeto de evento como parámetro. Los objetos de evento que se crean cuando se activan los activadores contextuales contienen todos los campos incluidos en los objetos de eventos de activación de la página principal, además de los campos que contienen información contextual.

• Acciones del widget. Los objetos de evento también se usan para proporcionar interactividad con el widget con el mismo modelo de acción que usan los complementos de Gmail. Los complementos de Google Workspace usan las mismas funciones de controlador de widgets, objetos Action y respuestas de acciones. Sin embargo, en los complementos de Google Workspace, los objetos de eventos de acción incluyen aún más información en la que puede actuar una función de devolución de llamada.

  Los objetos de evento creados como resultado de las acciones de widgets contienen todos los campos incluidos en los objetos de eventos de activadores contextuales, además de los campos que contienen información del widget.

• Obtén una vista previa de los activadores de vínculos. En Documentos, Hojas de cálculo y Presentaciones de Google, puedes configurar vistas previas de vínculos para servicios de terceros en función de patrones de URL específicos. Cuando los usuarios interactúan con un vínculo que cumple con el patrón, se activa linkPreviewTriggers y se pasa un objeto de evento que contiene el vínculo a la función de devolución de llamada del activador. Tu complemento puede usar este objeto de evento para crear un chip y una tarjeta inteligentes que muestren información sobre el vínculo dentro de la aplicación anfitrión. También puedes compilar acciones de widgets para permitir que los usuarios interactúen con la tarjeta de vista previa y su contenido.

• Activadores de la app de Google Chat (versión preliminar para desarrolladores). En Google Chat, el complemento se muestra a los usuarios como una app de Chat, y estos pueden interactuar con él agregándolo a espacios, enviando mensajes, usando comandos de barra y mucho más. Para compilar funciones interactivas, configuras y usas varios activadores de la app de Chat. Cada activador envía una carga útil de objeto de evento diferente que te ayuda a procesar o responder a cada tipo de interacción.

Estructura del objeto de evento

En la siguiente tabla, se describe la estructura de nivel superior de los objetos de eventos de complementos de Google Workspace. La estructura del objeto del evento incluye un campo de nivel superior commonEventObject para la información independiente del host. Cada objeto de evento también puede tener uno de los siguientes campos de nivel superior específicos del host, que determina la app de host activa: gmailEventObject, calendarEventObject o driveEventObject.

Para garantizar la retrocompatibilidad, los objetos de eventos de complementos de Google Workspace también incluyen todos los campos originales que se usan en los objetos de eventos de acción de complementos de Gmail. Estos campos se enumeran en la siguiente tabla, en “Campos de complementos originales de Gmail”. La información de estos campos se reproduce en la nueva estructura de objetos.

Objeto de evento común

El objeto de evento común es la parte del objeto de evento general que lleva información general independiente del host al complemento desde el cliente del usuario. Esta información incluye detalles como la configuración regional, la app host y la plataforma del usuario.

Además de los activadores contextuales y de la página principal, los complementos construyen y pasan objetos de eventos a las funciones de devolución de llamada de acción cuando el usuario interactúa con los widgets. La función de devolución de llamada de tu complemento puede consultar el objeto de evento común para determinar el contenido de los widgets abiertos en el cliente del usuario. Por ejemplo, tu complemento puede ubicar el texto que un usuario ingresó en un widget TextInput en el objeto eventObject.commentEventObject.formInputs.

Entradas del formulario del selector de fecha y hora

Las funciones de devolución de llamada de acción pueden recibir los valores actuales del widget en el campo commonEventObject.formInputs. Esto incluye los valores de fecha o hora seleccionados por el usuario en los widgets de selector de fecha o hora. Sin embargo, la estructura de la información difiere según si el widget se configuró como un selector de fecha y hora, un selector de solo fecha o un selector de solo hora. Las diferencias estructurales se describen en la siguiente tabla:

Objeto de evento de calendario

El objeto de evento de calendario es la parte del objeto de evento general que contiene información sobre el calendario y los eventos de calendario de un usuario. Solo está presente en un objeto de evento si la aplicación host es el Calendario de Google.

En la siguiente tabla, se muestran los campos presentes en el campo calendarEventObject de un objeto de evento. Los campos marcados como Datos generados por el usuario están presentes en el objeto del evento solo si los datos están presentes en el evento del Calendario y el complemento establece su campo addOns.calendar.currentEventAccess manifest en READ o READ_WRITE.

Asistente

Los objetos de asistentes contienen información sobre asistentes individuales a eventos del Calendario de Google. Esta información está presente en el objeto del evento solo si los datos están presentes en el evento del Calendario y el complemento establece su campo addOns.calendar.currentEventAccess manifest en READ o READ_WRITE.

Datos de la conferencia

Los objetos de datos de conferencias contienen información sobre las conferencias que se adjuntan a los eventos del Calendario de Google. Pueden ser soluciones de conferencias de Google, como Google Meet, o conferencias de terceros. Esta información está presente en el objeto del evento solo si los datos están presentes en el evento del Calendario y el complemento establece su campo manifest addOns.calendar.currentEventAccess en READ o READ_WRITE.

Punto de entrada

Los objetos de punto de entrada contienen información sobre los medios establecidos para acceder a una conferencia determinada, como por teléfono o video. Esta información está presente en el objeto del evento solo si los datos están presentes en el evento del Calendario y el complemento establece su campo addOns.calendar.currentEventAccess manifest en READ o READ_WRITE.

Objeto de evento de Drive

El objeto del evento de Drive es la parte del objeto del evento general que contiene información sobre Google Drive de un usuario y su contenido. Solo está presente en un objeto de evento si la aplicación host es Google Drive.

Elemento de Drive

Los objetos de elementos de Drive contienen información sobre elementos específicos de Drive, como archivos o carpetas.

Objeto de evento de Gmail

El objeto del evento de Gmail es la parte del objeto del evento general que contiene información sobre los mensajes de Gmail de un usuario. Solo está presente en un objeto de evento si la aplicación host es Gmail.

Objeto de evento de Documentos

El objeto del evento de Documentos es la parte del objeto del evento general que contiene información sobre el documento de un usuario y su contenido. Solo está presente en un objeto de evento si la aplicación host es Documentos de Google.

"docs" : {
  "matchedUrl" : {
      "url" : "https://www.example.com/12345"
  }
}
        

Objeto de evento de Hojas de cálculo

El objeto del evento de Hojas de cálculo es la parte del objeto del evento general que contiene información sobre el documento de un usuario y su contenido. Solo está presente en un objeto de evento si la aplicación host es Hojas de cálculo de Google.

"sheets" : {
  "matchedUrl" : {
      "url" : "https://www.example.com/12345"
  }
}
        

Objeto de evento de diapositivas

El objeto del evento de diapositivas es la parte del objeto del evento general que contiene información sobre el documento de un usuario y su contenido. Solo está presente en un objeto de evento si la aplicación host es Presentaciones de Google.

"slides" : {
  "matchedUrl" : {
      "url" : "https://www.example.com/12345"
  }
}