Configuración del complemento de Outlook para la activación basada en eventos

  • Artículo

La característica de activación basada en eventos permite a un usuario usar el complemento para completar sus tareas sin iniciar explícitamente el complemento. El complemento ejecutará tareas cuando se produzcan determinados eventos, como actualizar automáticamente los datos adjuntos de un elemento de correo cuando los destinatarios cambien o comprueben un dato adjunto determinado antes de que se envíe un elemento de correo. También puede integrar la activación basada en eventos con el panel de tareas y los comandos de función.

Nota:

La compatibilidad con esta característica se introdujo en el conjunto de requisitos 1.10, con eventos adicionales ahora disponibles en conjuntos de requisitos posteriores. Para obtener más información sobre el conjunto de requisitos mínimos de un evento y los clientes y plataformas que lo admiten, consulte Eventos y conjuntos de requisitos admitidos por los servidores exchange y los clientes de Outlook.

Para obtener información sobre cómo implementar un complemento basado en eventos que se ejecuta en Outlook en dispositivos móviles, consulte Implementación de la activación basada en eventos en complementos móviles de Outlook.

Eventos compatibles

En la tabla siguiente se enumeran los eventos que están disponibles actualmente y los clientes admitidos para cada evento. Cuando se genera un evento, el controlador recibe un event objeto que puede incluir detalles específicos del tipo de evento. La columna Descripción incluye un vínculo al objeto relacionado cuando corresponda.

Nombre canónico del evento
y nombre del manifiesto XML		 Manifiesto unificado para el nombre de Microsoft 365 Descripción Conjunto de requisitos mínimos y clientes admitidos
OnNewMessageCompose newMessageComposeCreated Al redactar un mensaje nuevo (incluye respuesta, responder todo y reenviar), pero no al editar, por ejemplo, un borrador. 1.10

- Windows (clásico1 y nuevo (versión preliminar))
- Explorador web
- Nueva interfaz de usuario de Mac
- Android2
- iOS2
OnNewAppointmentOrganizer newAppointmentOrganizerCreated Al crear una nueva cita, pero no al editar una existente. 1.10

- Windows (clásico1 y nuevo (versión preliminar))
- Explorador web
- Nueva interfaz de usuario de Mac
OnMessageAttachmentsChanged messageAttachmentsChanged Al agregar o quitar datos adjuntos al redactar un mensaje.

Objeto de datos específico del evento: AttachmentsChangedEventArgs		 1.11

- Windows (clásico1 y nuevo (versión preliminar))
- Explorador web
- Nueva interfaz de usuario de Mac
OnAppointmentAttachmentsChanged appointmentAttachmentsChanged Al agregar o quitar datos adjuntos al redactar una cita.

Objeto de datos específico del evento: AttachmentsChangedEventArgs		 1.11

- Windows (clásico1 y nuevo (versión preliminar))
- Explorador web
- Nueva interfaz de usuario de Mac
OnMessageRecipientsChanged messageRecipientsChanged Al agregar o quitar destinatarios mientras se redacta un mensaje.

Objeto de datos específico del evento: RecipientsChangedEventArgs		 1.11

- Windows (clásico1 y nuevo (versión preliminar))
- Explorador web
- Nueva interfaz de usuario de Mac
OnAppointmentAttendeesChanged appointmentAttendeesChanged Al agregar o quitar asistentes mientras se redacta una cita.

Objeto de datos específico del evento: RecipientsChangedEventArgs		 1.11

- Windows (clásico1 y nuevo (versión preliminar))
- Explorador web
- Nueva interfaz de usuario de Mac
OnAppointmentTimeChanged appointmentTimeChanged Al cambiar la fecha y hora al redactar una cita.

Objeto de datos específico del evento: AppointmentTimeChangedEventArgs

Importante: Si arrastra y coloca una cita en una ranura de fecha y hora diferente en el calendario, el OnAppointmentTimeChanged evento no se produce. Solo se produce cuando la fecha y hora se cambia directamente de una cita.		 1.11

- Windows (clásico1 y nuevo (versión preliminar))
- Explorador web
- Nueva interfaz de usuario de Mac
OnAppointmentRecurrenceChanged appointmentRecurrenceChanged Al agregar, cambiar o quitar los detalles de periodicidad al redactar una cita. Si se cambia la fecha y hora, también se produce el OnAppointmentTimeChanged evento.

Objeto de datos específico del evento: RecurrenceChangedEventArgs		 1.11

- Windows (clásico1 y nuevo (versión preliminar))
- Explorador web
- Nueva interfaz de usuario de Mac
OnInfoBarDismissClicked infoBarDismissClicked Al descartar una notificación mientras se redacta un mensaje o elemento de cita. Solo se notificará al complemento que agregó la notificación.

Objeto de datos específico del evento: InfobarClickedEventArgs		 1.11

- Windows (clásico1 y nuevo (versión preliminar))
- Explorador web
- Nueva interfaz de usuario de Mac
OnMessageSend messageSending Al enviar un elemento de mensaje. Para más información, pruebe el tutorial Alertas inteligentes. 1.12

- Windows (clásico1 y nuevo (versión preliminar))
- Explorador web
- Nueva interfaz de usuario de Mac
OnAppointmentSend appointmentSending Al enviar un elemento de cita. Para obtener más información, vea Controlar eventos OnMessageSend y OnAppointmentSend en el complemento de Outlook con alertas inteligentes. 1.12

- Windows (clásico1 y nuevo (versión preliminar))
- Explorador web
- Nueva interfaz de usuario de Mac
OnMessageCompose messageComposeOpened Al redactar un nuevo mensaje (incluye respuesta, responder todo y reenviar) o editar un borrador. 1.12

- Windows (clásico1 y nuevo (versión preliminar))
- Explorador web
- Nueva interfaz de usuario de Mac
OnAppointmentOrganizer appointmentOrganizerOpened Al crear una nueva cita o editar una existente. 1.12

- Windows (clásico1 y nuevo (versión preliminar))
- Explorador web
- Nueva interfaz de usuario de Mac
OnMessageFromChanged messageFromChanged Al cambiar la cuenta de correo en el campo Desde de un mensaje que se va a componer. Para más información, consulte Actualización automática de la firma al cambiar entre cuentas de Exchange. 1.13

- Windows (clásico1 y nuevo (versión preliminar))
- Explorador web
- Nueva interfaz de usuario de Mac
OnAppointmentFromChanged appointmentFromChanged Al cambiar la cuenta de correo en el campo organizador de una cita que se va a componer. Para más información, consulte Actualización automática de la firma al cambiar entre cuentas de Exchange. 1.13

- nuevo Outlook en Windows (versión preliminar)
- Explorador web
- Nueva interfaz de usuario de Mac
OnSensitivityLabelChanged sensitivityLabelChanged Al cambiar la etiqueta de confidencialidad al redactar un mensaje o una cita. Para obtener información sobre cómo administrar la etiqueta de confidencialidad de un elemento de correo, consulte Administrar la etiqueta de confidencialidad del mensaje o la cita en modo de redacción.

Objeto de datos específico del evento: SensitivityLabelChangedEventArgs		 1.13

- Windows (clásico1 y nuevo (versión preliminar))
- Explorador web
- Nueva interfaz de usuario de Mac
OnMessageReadWithCustomAttachment No disponible Al abrir un mensaje que contiene un tipo de datos adjuntos específico en modo de lectura. Versión preliminar3

- Windows1
OnMessageReadWithCustomHeader No disponible Al abrir un mensaje que contiene un nombre de encabezado de Internet específico en modo de lectura. Versión preliminar3

- Windows1

Nota:

1 Los complementos basados en eventos en Outlook en Windows requieren un mínimo de Windows 10 versión 1903 (compilación 18362) o Windows Server 2019 versión 1903 para ejecutarse.

2 Outlook en dispositivos móviles admite API hasta el conjunto de requisitos de buzón 1.5. Sin embargo, la compatibilidad ahora está habilitada para las API y características adicionales introducidas en conjuntos de requisitos posteriores, como el OnNewMessageCompose evento . Para obtener más información, vea Implementar la activación basada en eventos en complementos móviles de Outlook.

3 Para obtener una vista previa de los OnMessageReadWithCustomAttachment eventos y OnMessageReadWithCustomHeader , debe instalar Outlook en Windows Versión 2312 (compilación 17110.10000) o posterior. A continuación, únase al programa Microsoft 365 Insider y seleccione la opción Canal beta para acceder a las compilaciones beta de Office.

Solución de problemas del complemento

A medida que desarrolle el complemento basado en eventos, es posible que tenga que solucionar problemas, como que el complemento no se cargue o que el evento no se produzca. Para obtener instrucciones sobre cómo solucionar problemas de un complemento basado en eventos, consulte Solución de problemas de complementos de informes de correo no deseado y basados en eventos.

Implementación en usuarios

Los complementos basados en eventos solo están restringidos a las implementaciones administradas por el administrador, incluso si se adquieren de AppSource. Si los usuarios adquieren el complemento desde AppSource o la Tienda Office desde la aplicación, no podrán activar la función basada en eventos del complemento. Para obtener más información sobre cómo enumerar el complemento basado en eventos en AppSource, consulte Opciones de lista de AppSource para el complemento de Outlook basado en eventos.

Administración implementaciones se realizan cargando el manifiesto en el Centro de administración de Microsoft 365. En el portal de administración, expanda la sección Configuración en el panel de navegación y, a continuación, seleccione Aplicaciones integradas. En la página Aplicaciones integradas , elija la acción Cargar aplicaciones personalizadas .

La página Aplicaciones integradas del Centro de administración de Microsoft 365 con la acción Cargar aplicaciones personalizadas resaltada.

Importante

Los complementos que usan la característica Alertas inteligentes solo se pueden publicar en AppSource si la propiedad de modo de envío del manifiesto está establecida en la opción de usuario de aviso o bloque temporal . Si la propiedad de modo de envío de un complemento está establecida en bloquear, solo la puede implementar el administrador de una organización, ya que no se realizará la validación de AppSource.

Implementación de actualizaciones de manifiestos

Dado que los administradores implementan complementos basados en eventos, cualquier cambio que realice en el manifiesto requiere el consentimiento del administrador a través de la Centro de administración de Microsoft 365. Hasta que el administrador acepte los cambios, los usuarios de su organización no podrán usar el complemento. Para más información sobre el proceso de consentimiento del administrador, consulte Administración consentimiento para instalar complementos basados en eventos.

Comportamiento y limitaciones de la activación basada en eventos

Se espera que los controladores de eventos de inicio de complementos sean de ejecución corta, ligeros y no invasivos como sea posible. Después de la activación, el complemento agotará el tiempo de espera en aproximadamente 300 segundos, la duración máxima permitida para ejecutar complementos basados en eventos. Para indicar que el complemento ha completado el procesamiento de un evento de inicio, el controlador de eventos asociado debe llamar al método event.completed . (Tenga en cuenta que el código incluido después de la event.completed instrucción no se garantiza que se ejecute). Cada vez que se desencadena un evento que controla el complemento, el complemento se reactiva y ejecuta el controlador de eventos asociado y se restablece la ventana de tiempo de espera. El complemento finaliza después de agotar el tiempo de espera o el usuario cierra la ventana de redacción o envía el elemento.

Si el usuario tiene varios complementos que se suscriben al mismo evento, la plataforma Outlook inicia los complementos sin ningún orden determinado. Actualmente, solo se pueden ejecutar activamente cinco complementos basados en eventos.

En todos los clientes de Outlook compatibles, el usuario debe permanecer en el elemento de correo actual donde se activó el complemento para que se complete la ejecución. Al desplazarse fuera del elemento actual (por ejemplo, cambiar a otra ventana o pestaña de redacción) finaliza la operación del complemento. Sin embargo, un complemento que se activa en el evento controla el OnMessageSend cambio de elemento de forma diferente en función del cliente de Outlook en el que se ejecute. Para obtener más información, vea la sección "El usuario navega lejos del mensaje actual" de Control de eventos OnMessageSend y OnAppointmentSend en el complemento de Outlook con alertas inteligentes.

Además del cambio de elementos, un complemento basado en eventos también deja de funcionar cuando el usuario envía el mensaje o la cita que está redactando.

Al desarrollar un complemento basado en eventos para ejecutarlo en el cliente de Outlook en Windows, tenga en cuenta lo siguiente:

  • Las importaciones no se admiten en el archivo JavaScript donde se implementa el control para la activación basada en eventos.

  • Los complementos no ejecutan código incluido en Office.onReady() y Office.initialize. Se recomienda agregar cualquier lógica de inicio, como comprobar la versión de Outlook del usuario, a los controladores de eventos en su lugar.

  • Solo se admite el archivo JavaScript al que se hace referencia en el manifiesto para la activación basada en eventos. Debe agrupar el código JavaScript de control de eventos en este único archivo. La ubicación del archivo JavaScript al que se hace referencia en el manifiesto varía en función del tipo de manifiesto que use el complemento.

    • Manifiesto XML: <invalidación> del elemento secundario del <nodo Runtime>
    • Manifiesto unificado para Microsoft 365 (versión preliminar): propiedad "script" del objeto "code"

    Tenga en cuenta que una agrupación de JavaScript grande puede causar problemas con el rendimiento del complemento. Se recomienda preprocesar operaciones pesadas para que no se incluyan en el código de control de eventos.

Algunas API de Office.js que cambian o modifican la interfaz de usuario no se permiten en los complementos basados en eventos. A continuación se muestran las API bloqueadas.

Características de vista previa en controladores de eventos (Outlook en Windows)

Outlook en Windows incluye una copia local de las versiones de producción y beta de Office.js en lugar de cargar desde la red de entrega de contenido (CDN). De forma predeterminada, se hace referencia a la copia de producción local de la API. Para hacer referencia a la copia beta local de la API, debe configurar el registro del equipo. Esto le permitirá probar las características de vista previa en los controladores de eventos en Outlook en Windows.

  1. En el Registro, vaya a HKEY_CURRENT_USER\SOFTWARE\Microsoft\Office\16.0\Outlook\Options\WebExt\Developer. Si la clave no existe, créela.

  2. Cree una entrada denominada EnableBetaAPIsInJavaScript y establezca su valor en 1.

    El valor del Registro EnableBetaAPIsInJavaScript se establece en 1.

Habilitación del inicio de sesión único (SSO)

Para habilitar el inicio de sesión único en el complemento basado en eventos, debe agregar su archivo JavaScript a un URI conocido. Para obtener instrucciones sobre cómo configurar este recurso, consulte Uso del inicio de sesión único (SSO) o el uso compartido de recursos entre orígenes (CORS) en el complemento de Outlook de informes de correo no deseado o basado en eventos.

Solicitud de datos externos

Puede solicitar datos externos mediante una API como Fetch o mediante XMLHttpRequest (XHR), una API web estándar que emite solicitudes HTTP para interactuar con los servidores.

Tenga en cuenta que debe usar medidas de seguridad adicionales al usar objetos XMLHttpRequest, que requieren la misma directiva de origen y CORS (uso compartido de recursos entre orígenes).

Nota:

La compatibilidad completa con CORS está disponible en Outlook en la Web, Mac y Windows (a partir de la versión 2201, compilación 16.0.14813.10000).

Para realizar solicitudes CORS desde el complemento basado en eventos, debe agregar el complemento y su archivo JavaScript a un URI conocido. Para obtener instrucciones sobre cómo configurar este recurso, consulte Uso del inicio de sesión único (SSO) o el uso compartido de recursos entre orígenes (CORS) en el complemento de Outlook de informes de correo no deseado o basado en eventos.

Vea también