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

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 de manifiesto de solo complemento	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 Explorador web Windows (nuevo y clásico1) Nueva interfaz de usuario de Mac Android2 iOS2
OnNewAppointmentOrganizer	newAppointmentOrganizerCreated	Al crear una nueva cita, pero no al editar una existente.	1.10 Explorador web Windows (nuevo y clásico1) 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 Explorador web Windows (nuevo y clásico1) 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 Explorador web Windows (nuevo y clásico1) 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 Explorador web Windows (nuevo y clásico1) Nueva interfaz de usuario de Mac Android2 iOS2
OnAppointmentAttendeesChanged	appointmentAttendeesChanged	Al agregar o quitar asistentes mientras se redacta una cita. Objeto de datos específico del evento: RecipientsChangedEventArgs	1.11 Explorador web Windows (nuevo y clásico1) 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 Explorador web Windows (nuevo y clásico1) 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 Explorador web Windows (nuevo y clásico1) 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 Explorador web Windows (nuevo y clásico1) 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 Explorador web Windows (nuevo y clásico1) 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 Explorador web Windows (nuevo y clásico1) 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 Explorador web Windows (nuevo y clásico1) Nueva interfaz de usuario de Mac
OnAppointmentOrganizer	appointmentOrganizerOpened	Al crear una nueva cita o editar una existente.	1.12 Explorador web Windows (nuevo y clásico1) 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 Explorador web Windows (nuevo y clásico1) 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 Explorador web nuevo Outlook en Windows 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 Explorador web Windows (nuevo y clásico1) 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 Windows (clásico 1)
OnMessageReadWithCustomHeader	No disponible	Al abrir un mensaje que contiene un nombre de encabezado de Internet específico en modo de lectura.	Versión preliminar3 Windows (clásico 1)

Nota:

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

² 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.

³ Para obtener una vista previa de los OnMessageReadWithCustomAttachment eventos y OnMessageReadWithCustomHeader , debe instalar outlook clásico 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 .

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.

Complementos basados en eventos en Outlook clásico en Windows

Al desarrollar un complemento basado en eventos para que se ejecute en el cliente clásico 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 de solo complemento: <invalidación> del elemento secundario del<> nodo Runtime
  • Manifiesto unificado para Microsoft 365: 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.

API no compatibles

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.

API	Métodos
Office.devicePermission	requestPermissionsAsync
Office.context.auth*	getAccessToken getAccessTokenAsync
Office.context.mailbox	displayAppointmentForm displayMessageForm displayNewAppointmentForm displayNewMessageForm
Office.context.mailbox.item	close
Office.context.ui	displayDialogAsync messageParent

Nota:

* OfficeRuntime.auth se admite en todas las versiones de Outlook que admiten la activación basada en eventos y el inicio de sesión único (SSO), mientras que Office.auth solo se admite en determinadas compilaciones de Outlook. Para obtener más información, 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.

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

Outlook clásico 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 clásico 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.

   

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.

Nota:

Si el complemento funcionará en un entorno de ejecución solo de JavaScript, use direcciones URL absolutas en las llamadas a Fetch API. Las direcciones URL relativas de las llamadas API fetch no se admiten en un entorno de ejecución solo de JavaScript.

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 clientes de Outlook en la Web, Mac y Windows (nuevos y clásicos (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

• Solución de problemas de complementos de informes de correo no deseado y basados en eventos
• Depuración de complementos basados en eventos y de informes de correo no deseado
• Opciones de lista de AppSource para el complemento de Outlook basado en eventos
• Controlar eventos OnMessageSend y OnAppointmentSend en el complemento de Outlook con alertas inteligentes
• Establecer automáticamente el asunto de un nuevo mensaje o cita
• Comprobar automáticamente si hay datos adjuntos antes de enviar un mensaje
• Actualizar automáticamente la firma al cambiar entre cuentas de correo
• Ejemplos de código de complementos de Office:
  • Cifrar datos adjuntos, procesar asistentes a la convocatoria de reunión y reaccionar a los cambios de fecha y hora de la cita mediante la activación basada en eventos de Outlook
  • Establecimiento de la firma mediante la activación basada en eventos de Outlook
  • Identificar y etiquetar destinatarios externos mediante la activación basada en eventos de Outlook
  • Compruebe las categorías de color de un mensaje o cita antes de enviarlo mediante alertas inteligentes.
  • Comprobación de la etiqueta de confidencialidad de un mensaje