Implementación de un complemento integrado de informes de correo no deseado

Con el número de correos electrónicos no solicitados en aumento, la seguridad está a la vanguardia del uso de complementos. Actualmente, los complementos de informes de correo no deseado de asociados se agregan a la cinta de Outlook, pero suelen aparecer hacia el final de la cinta o en el menú de desbordamiento. Esto dificulta que los usuarios busquen el complemento para notificar correos electrónicos no solicitados. Además de configurar cómo se procesan los mensajes cuando se notifican, los desarrolladores también deben completar tareas adicionales para mostrar diálogos de procesamiento o información complementaria al usuario.

La característica integrada de informes de correo no deseado facilita la tarea de desarrollar componentes de complemento individuales desde cero. Lo que es más importante, muestra el complemento en un lugar destacado en la cinta de Opciones de Outlook, lo que facilita a los usuarios localizarlo y notificar mensajes de correo no deseado. Implemente esta característica en el complemento para:

• Mejore el seguimiento de los mensajes no solicitados.
• Proporcione una mejor guía a los usuarios sobre cómo notificar mensajes sospechosos.
• Permitir que el centro de operaciones de seguridad (SOC) o los administradores de TI de una organización realicen fácilmente simulaciones de spam y phishing con fines educativos.

Clientes compatibles

En la tabla siguiente se identifica qué clientes de Outlook admiten la característica integrada de informes de correo no deseado.

Vista previa de la característica integrada de informes de correo no deseado en Outlook en Mac

Para obtener una vista previa de la característica integrada de informes de correo no deseado en Outlook en Mac, debe instalar la versión 16.81.1217.0 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.

Configurar el entorno

Complete el inicio rápido de Outlook, que crea un proyecto de complemento con el generador de Yeoman para complementos de Office.

Configuración del manifiesto

Para implementar la característica integrada de informes de correo no deseado en el complemento, debe configurar lo siguiente en el manifiesto.

• Tiempo de ejecución usado por el complemento. En Outlook clásico en Windows, un complemento de informes de correo no deseado se ejecuta en un entorno de ejecución de solo JavaScript. En Outlook en la Web y en Mac y en el nuevo Outlook en Windows, un complemento de informes de correo no deseado se ejecuta en un entorno de ejecución del explorador. Para obtener más información, vea Runtimes in Office Add-ins.

• Botón del complemento de informes de correo no deseado que siempre aparece en un lugar destacado de la cinta de Opciones de Outlook. A continuación se muestra un ejemplo de cómo aparece el botón de un complemento de informes de correo no deseado en la cinta de opciones del cliente clásico de Outlook en Windows. La interfaz de usuario de la cinta de opciones puede variar en función de la plataforma en la que se ejecute el cliente de Outlook del usuario.

  

• Cuadro de diálogo de preprocesamiento. Este cuadro de diálogo se muestra al usuario cuando selecciona el botón del complemento. En este cuadro de diálogo, un usuario puede proporcionar información adicional sobre el mensaje que está notificando. Cuando un usuario selecciona Informe en el cuadro de diálogo, el evento SpamReporting se activa y, a continuación, lo controla el controlador de eventos de JavaScript. A continuación se muestra un ejemplo de un cuadro de diálogo de preprocesamiento en Outlook en Windows. Tenga en cuenta que la apariencia del cuadro de diálogo puede variar en función de la plataforma en la que se ejecute el cliente de Outlook del usuario.

  

Seleccione la pestaña del tipo de manifiesto que está usando.

Implementar el controlador de eventos

Cuando el complemento se usa para informar de un mensaje, genera un SpamReporting evento que, a continuación, el controlador de eventos procesa en el archivo JavaScript del complemento. Para asignar el nombre del controlador de eventos especificado en el manifiesto a su homólogo de JavaScript, debe llamar a Office.actions.associate en el código.

1. En el proyecto de complemento, vaya al directorio ./src . A continuación, cree una nueva carpeta denominada spamreporting.

2. En la carpeta ./src/spamreporting , cree un nuevo archivo denominado spamreporting.js.

3. Abra el archivo despamreporting.js recién creado y agregue el siguiente código JavaScript.

   // Handles the SpamReporting event to process a reported message.
   function onSpamReport(event) {
     // TODO - Send a copy of the reported message.
   
     // TODO - Get the user's responses.
   
     // TODO - Signal that the spam-reporting event has completed processing.
   }
   
   // IMPORTANT: To ensure your add-in is supported in Outlook, remember to map the event handler name specified in the manifest to its JavaScript counterpart.
   Office.actions.associate("onSpamReport", onSpamReport);
   

4. Guarde los cambios.

Reenviar una copia del mensaje y obtener las respuestas del cuadro de diálogo de preprocesamiento

El controlador de eventos es responsable de procesar el mensaje notificado. Puede configurarla para reenviar información, como una copia del mensaje o las opciones seleccionadas por el usuario en el cuadro de diálogo de preprocesamiento, a un sistema interno para su posterior investigación.

Para enviar de forma eficaz una copia del mensaje notificado, llama al método getAsFileAsync en el controlador de eventos. Esto obtiene el formato EML codificado en Base64 de un mensaje, que puede reenviar a su sistema interno.

Si necesita realizar un seguimiento de las respuestas del usuario a las opciones y al cuadro de texto del cuadro de diálogo de preprocesamiento, extraiga los options valores y freeText del objeto de SpamReporting evento. Para obtener más información sobre estas propiedades, vea Office.SpamReportingEventArgs.

A continuación se muestra un ejemplo de un controlador de eventos de informes de correo no deseado que llama al getAsFileAsync método y obtiene las respuestas del usuario del objeto de SpamReporting evento.

1. En el archivo spamreporting.js , reemplace su contenido por el código siguiente.

   // Handles the SpamReporting event to process a reported message.
   function onSpamReport(event) {
     // Get the Base64-encoded EML format of a reported message.
     Office.context.mailbox.item.getAsFileAsync({ asyncContext: event }, (asyncResult) => {
       if (asyncResult.status === Office.AsyncResultStatus.Failed) {
         console.log(`Error encountered during message processing: ${asyncResult.error.message}`);
         return;
       }
   
       // Get the user's responses to the options and text box in the preprocessing dialog.
       const spamReportingEvent = asyncResult.asyncContext;
       const reportedOptions = spamReportingEvent.options;
       const additionalInfo = spamReportingEvent.freeText;
   
       // Run additional processing operations here.
   
       // TODO - Signal that the spam-reporting event has completed processing.
     });
   }
   
   // IMPORTANT: To ensure your add-in is supported in Outlook, remember to map the event handler name specified in the manifest to its JavaScript counterpart.
   Office.actions.associate("onSpamReport", onSpamReport);
   

2. Guarde los cambios.

Señal cuando se ha procesado el evento

Una vez que el controlador de eventos ha completado el procesamiento del mensaje, debe llamar al método event.completed . Además de indicar al complemento que se ha procesado el evento de informes de correo no deseado, event.completed también se puede usar para personalizar un cuadro de diálogo posterior al procesamiento para mostrarlo al usuario o realizar operaciones adicionales en el mensaje, como eliminarlo de la bandeja de entrada. Para obtener una lista de las propiedades que puede incluir en un objeto JSON para pasar como parámetro al event.completed método, vea Office.SpamReportingEventCompletedOptions.

1. En el archivo spamreporting.js , reemplace su contenido por el código siguiente.

   // Handles the SpamReporting event to process a reported message.
   function onSpamReport(event) {
     // Get the Base64-encoded EML format of a reported message.
     Office.context.mailbox.item.getAsFileAsync({ asyncContext: event }, (asyncResult) => {
       if (asyncResult.status === Office.AsyncResultStatus.Failed) {
         console.log(`Error encountered during message processing: ${asyncResult.error.message}`);
         return;
       }
   
       // Get the user's responses to the options and text box in the preprocessing dialog.
       const spamReportingEvent = asyncResult.asyncContext;
       const reportedOptions = spamReportingEvent.options;
       const additionalInfo = spamReportingEvent.freeText;
   
       // Run additional processing operations here.
   
       /**
        * Signals that the spam-reporting event has completed processing.
        * It then moves the reported message to the Junk Email folder of the mailbox, then
        * shows a post-processing dialog to the user. If an error occurs while the message
        * is being processed, the `onErrorDeleteItem` property determines whether the message
        * will be deleted.
        */
       const event = asyncResult.asyncContext;
       event.completed({
         onErrorDeleteItem: true,
         moveItemTo: Office.MailboxEnums.MoveSpamItemTo.JunkFolder,
         showPostProcessingDialog: {
           title: "Contoso Spam Reporting",
           description: "Thank you for reporting this message.",
         },
       });
     });
   }
   
   // IMPORTANT: To ensure your add-in is supported in Outlook, remember to map the event handler name specified in the manifest to its JavaScript counterpart
   Office.actions.associate("onSpamReport", onSpamReport);
   

   Nota:

   Si está en la versión clásica de Outlook en Windows 2308 (compilación 16724.10000) o posterior, Outlook en Mac, Outlook en la Web o nueva Outlook en Windows, debe usar la moveItemTo propiedad en la event.completed llamada para especificar la carpeta a la que se mueve un mensaje notificado una vez que el complemento lo procesa. En versiones anteriores de Outlook se basa en Windows que admiten la característica integrada de informes de correo no deseado, debe usar la postProcessingAction propiedad .

2. Guarde los cambios.

A continuación se muestra un cuadro de diálogo de posprocesamiento de ejemplo que se muestra al usuario una vez que el complemento completa el procesamiento de un mensaje notificado en Outlook en Windows. Tenga en cuenta que la apariencia del cuadro de diálogo puede variar en función de la plataforma en la que se ejecute el cliente de Outlook del usuario.

Actualizar el archivo HTML de comandos

1. En la carpeta ./src/commands , abra commands.html.

2. Inmediatamente antes de la etiqueta principal de cierre (</head>), agregue la siguiente entrada de script .

   <script type="text/javascript" src="../spamreporting/spamreporting.js"></script>    
   

   Nota:

   La característica integrada de informes de correo no deseado está actualmente en versión preliminar en Outlook en Mac. Si va a probar la característica en este cliente, debe incluir una referencia a la versión preliminar de la API de JavaScript de Office en el archivo decommands.html .

   <script type="text/javascript" src="https://appsforoffice.microsoft.com/lib/beta/hosted/office.js"></script>
   <script type="text/javascript" src="../spamreporting/spamreporting.js"></script>
   

3. Guarde los cambios.

Actualización de la configuración de webpack

1. En el directorio raíz del proyecto del complemento, abra el archivo webpack.config.js .

2. Busque la plugins matriz dentro del config objeto y agregue este nuevo objeto al principio de la matriz.

   new CopyWebpackPlugin({
     patterns: [
       {
         from: "./src/spamreporting/spamreporting.js",
         to: "spamreporting.js",
       },
     ],
   }),
   

3. Guarde los cambios.

Prueba y validación del complemento

1. Transferir localmente el complemento en un cliente de Outlook compatible.
2. Elija un mensaje en la bandeja de entrada y, a continuación, seleccione el botón del complemento en la cinta de opciones.
3. En el cuadro de diálogo de preprocesamiento, elija un motivo para notificar el mensaje y agregue información sobre el mensaje, si está configurado. A continuación, seleccione Informe.
4. (Opcional) En el cuadro de diálogo posterior al procesamiento, seleccione Aceptar.

Revisión del comportamiento y las limitaciones de las características

A medida que desarrolle y pruebe la característica integrada de informes de correo no deseado en el complemento, tenga en cuenta sus características y limitaciones.

• En Outlook en la Web y en Windows (nuevo y clásico), un complemento integrado de informes de correo no deseado reemplaza el botón informe nativo de la cinta de opciones de Outlook. Si se instalan varios complementos de informes de correo no deseado, todos aparecerán en la sección Informe de la cinta de opciones.

  

• Un complemento de informes de correo no deseado puede ejecutarse durante un máximo de cinco minutos una vez activado. Cualquier procesamiento que se produzca más allá de cinco minutos hará que el complemento agote el tiempo de espera. Si el complemento agota el tiempo de espera, se mostrará un cuadro de diálogo al usuario para notificarle esto.

  

• En Outlook clásico en Windows, se puede usar un complemento de informes de correo no deseado para notificar un mensaje incluso si el panel de lectura del cliente de Outlook está desactivado. En Outlook en la Web, en Mac y en la nueva Outlook en Windows, el complemento de informes de correo no deseado se puede usar si el panel de lectura está activado o el mensaje que se va a notificar está abierto en otra ventana.

• Solo se puede notificar un mensaje a la vez. Si selecciona varios mensajes para informar, el botón del complemento de informes de correo no deseado deja de estar disponible.

• En Outlook clásico en Windows, solo se puede procesar un mensaje notificado a la vez. Si un usuario intenta notificar otro mensaje mientras se sigue procesando el anterior, se mostrará un cuadro de diálogo para notificarlo.

  

  Esto no se aplica a Outlook en la Web o en Mac, ni a la nueva Outlook en Windows. En estos clientes de Outlook, un usuario puede informar de un mensaje desde el panel de lectura y puede notificar simultáneamente cada mensaje que está abierto en una ventana independiente.

• El complemento todavía puede procesar el mensaje notificado incluso si el usuario se aleja del mensaje seleccionado. En Outlook en Mac, esto solo se admite si un usuario informa de un mensaje mientras está abierto en una ventana independiente. Si el usuario informa de un mensaje mientras lo ve desde el panel de lectura y, a continuación, se aleja de él, el proceso de generación de informes finaliza.

• Los botones que aparecen en los diálogos de preprocesamiento y posprocesamiento no son personalizables. Además, el texto y los botones del tiempo de espera y los diálogos de informes en curso no se pueden modificar.

• Las características integradas de generación de informes de correo no deseado y activación basada en eventos deben usar el mismo tiempo de ejecución. Actualmente no se admiten varios entornos de ejecución en Outlook. Para obtener más información sobre los tiempos de ejecución, consulte Runtimes in Office Add-ins( Tiempos de ejecución en complementos de Office).

• Un complemento de informes de correo no deseado solo implementa comandos de función. No se puede asignar un comando de panel de tareas al botón de informes de correo no deseado de la cinta de opciones. Si desea implementar un panel de tareas en el complemento, debe configurarlo en el manifiesto de la siguiente manera:

  • Manifiesto de solo complemento: incluya el elemento Action en el manifiesto y establezca su xsi:type atributo ShowTaskpaneen .
  • Manifiesto unificado para Microsoft 365: configure un objeto de panel de tareas en las matrices "extensions.runtimes" y "extensions.ribbons". Para obtener instrucciones, consulte la sección "Agregar un comando de panel de tareas" de Creación de comandos de complemento con el manifiesto unificado para Microsoft 365.

  Tenga en cuenta que se agregará un botón independiente para activar el panel de tareas a la cinta de opciones, pero no aparecerá en el área de informes de correo no deseado dedicado de la cinta de opciones.

Solución de problemas del complemento

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

Vea también

• Manifiesto de complementos de Office
• Tiempos de ejecución en complementos de Office
• Solución de problemas de complementos de informes de correo no deseado y basados en eventos
• Punto de extensión ReportPhishingCommandSurface
• Office.MessageRead.getAsFileAsync
• Office.MailboxEnums.MoveSpamItemTo
• Office.SpamReportingEventArgs
• Office.SpamReportingEventCompletedOptions