Implémenter un complément de création de rapports de courrier indésirable intégré

Avec le nombre d’e-mails non sollicités à la hausse, la sécurité est à la pointe de l’utilisation des compléments. Actuellement, les compléments de création de rapports de courrier indésirable partenaires sont ajoutés au ruban Outlook, mais ils apparaissent généralement vers la fin du ruban ou dans le menu de dépassement. Cela rend plus difficile pour les utilisateurs de localiser le complément pour signaler les e-mails non sollicités. En plus de configurer la façon dont les messages sont traités lorsqu’ils sont signalés, les développeurs doivent également effectuer des tâches supplémentaires pour afficher des dialogues de traitement ou des informations supplémentaires à l’utilisateur.

La fonctionnalité intégrée de création de rapports de courrier indésirable facilite le développement de composants de complément individuels à partir de zéro. Plus important encore, il affiche votre complément à un endroit bien visible sur le ruban Outlook, ce qui permet aux utilisateurs de le localiser plus facilement et de signaler les messages indésirables. Implémentez cette fonctionnalité dans votre complément pour :

• Améliorer le suivi des messages non sollicités.
• Fournir de meilleures instructions aux utilisateurs sur la façon de signaler les messages suspects.
• Permettre au centre d’opérations de sécurité (SOC) d’un organization ou aux administrateurs informatiques d’effectuer facilement des simulations de courrier indésirable et d’hameçonnage à des fins pédagogiques.

Clients pris en charge

Le tableau suivant identifie les clients Outlook qui prennent en charge la fonctionnalité intégrée de création de rapports de courrier indésirable.

Afficher un aperçu de la fonctionnalité intégrée de création de rapports de courrier indésirable dans Outlook sur Mac

Pour afficher un aperçu de la fonctionnalité intégrée de création de rapports de courrier indésirable dans Outlook sur Mac, vous devez installer la version 16.81.1217.0 ou ultérieure. Ensuite, rejoignez le programme Microsoft 365 Insider et sélectionnez l’option Canal bêta pour accéder aux builds bêta d’Office.

Configuration de votre environnement

Suivez le guide de démarrage rapide Outlook, qui crée un projet de complément avec le générateur Yeoman pour les compléments Office.

Configurer le manifeste

Pour implémenter la fonctionnalité intégrée de création de rapports de courrier indésirable dans votre complément, vous devez configurer les éléments suivants dans votre manifeste.

• Runtime utilisé par le complément. Dans Outlook sur Windows classique, un complément de création de rapports de courrier indésirable s’exécute dans un runtime JavaScript uniquement. Dans Outlook sur le web et sur Mac et dans le nouvel Outlook sur Windows, un complément de signalement de courrier indésirable s’exécute dans un runtime de navigateur. Pour plus d’informations, voir Runtimes dans les compléments Office.

• Bouton du complément de création de rapports de courrier indésirable qui apparaît toujours à un endroit bien visible du ruban Outlook. Voici un exemple de la façon dont le bouton d’un complément de création de rapports de courrier indésirable apparaît sur le ruban du client Outlook classique sur Windows. L’interface utilisateur du ruban peut varier en fonction de la plateforme sur laquelle le client Outlook de l’utilisateur s’exécute.

  

• Boîte de dialogue de prétraitement. Lorsqu’un utilisateur sélectionne le bouton du complément, une boîte de dialogue s’affiche avec les options Rapport et Ne pas signaler . Dans cette boîte de dialogue, vous pouvez partager des informations sur le processus de création de rapports ou implémenter des options d’entrée pour obtenir des informations sur un message signalé. Les options d’entrée incluent des cases à cocher, des cases d’option et une zone de texte. Lorsqu’un utilisateur sélectionne Rapport dans la boîte de dialogue, l’événement SpamReporting est activé, puis géré par le gestionnaire d’événements JavaScript. Voici un exemple de boîte de dialogue de prétraitement dans Outlook sur Windows. Notez que l’apparence de la boîte de dialogue peut varier en fonction de la plateforme sur laquelle le client Outlook de l’utilisateur s’exécute.

  

Sélectionnez l’onglet correspondant au type de manifeste que vous utilisez.

Mettre en œuvre le gestionnaire d’événements

Lorsque votre complément est utilisé pour signaler un message, il génère un SpamReporting événement, qui est ensuite traité par le gestionnaire d’événements dans le fichier JavaScript de votre complément. Pour mapper le nom du gestionnaire d’événements que vous avez spécifié dans votre manifeste à son équivalent JavaScript, vous devez appeler Office.actions.associate dans votre code.

1. Dans votre projet de complément, accédez au répertoire ./src . Ensuite, créez un dossier nommé spamreporting.

2. Dans le dossier ./src/spamreporting, créez un fichier nommé spamreporting.js.

3. Ouvrez le fichier spamreporting.js nouvellement créé et ajoutez le code JavaScript suivant.

   // 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. Enregistrez vos modifications.

Transférer une copie du message et obtenir les réponses du dialogue de prétraitement

Votre gestionnaire d’événements est responsable du traitement du message signalé. Vous pouvez le configurer pour transférer des informations, telles qu’une copie du message ou les options sélectionnées par l’utilisateur dans la boîte de dialogue de prétraitement, à un système interne pour une investigation plus approfondie.

Pour envoyer efficacement une copie du message signalé, appelez la méthode getAsFileAsync dans votre gestionnaire d’événements. Cela obtient le format EML codé en Base64 d’un message, que vous pouvez ensuite transférer à votre système interne.

Si vous avez besoin de suivre les réponses de l’utilisateur aux options et à la zone de texte dans la boîte de dialogue de prétraitement, extrayez les options valeurs et freeText de l’objet SpamReporting événement. Pour plus d’informations sur ces propriétés, voir Office.SpamReportingEventArgs.

Voici un exemple de gestionnaire d’événements de création de rapports de courrier indésirable qui appelle la getAsFileAsync méthode et obtient les réponses de l’utilisateur à partir de l’objet SpamReporting d’événement.

1. Dans le fichier spamreporting.js , remplacez son contenu par le code suivant.

   // 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. Enregistrez vos modifications.

Signal lorsque l’événement a été traité

Une fois que le gestionnaire d’événements a terminé le traitement du message, il doit appeler la méthode event.completed . En plus de signaler au complément que l’événement de signalement de courrier indésirable a été traité, event.completed peut également être utilisé pour effectuer les opérations suivantes :

• Personnalisez une boîte de dialogue de post-traitement à afficher à l’utilisateur.
• Effectuez des opérations supplémentaires sur le message, telles que sa suppression de la boîte de réception.
• Ouvrez un volet Office et transmettez-lui des informations.

Pour obtenir la liste des propriétés que vous pouvez inclure dans un objet JSON à passer en tant que paramètre à la event.completed méthode , voir Office.SpamReportingEventCompletedOptions.

1. Dans le fichier spamreporting.js , remplacez son contenu par le code suivant.

   // 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);
   

   Remarque

   Si vous utilisez outlook classique sur Windows version 2308 (build 16724.10000) ou ultérieure, Outlook sur Mac, Outlook sur le web ou le nouvel Outlook sur Windows, vous devez utiliser la moveItemTo propriété dans l’appel event.completed pour spécifier le dossier vers lequel un message signalé est déplacé une fois qu’il est traité par votre complément. Sur les versions antérieures d’Outlook basées sur Windows qui prennent en charge la fonctionnalité intégrée de création de rapports de courrier indésirable, vous devez utiliser la postProcessingAction propriété .

2. Enregistrez vos modifications.

Voici un exemple de boîte de dialogue de post-traitement présentée à l’utilisateur une fois que le complément a terminé le traitement d’un message signalé dans Outlook sur Windows. Notez que l’apparence de la boîte de dialogue peut varier en fonction de la plateforme sur laquelle le client Outlook de l’utilisateur s’exécute.

Mettre à jour le fichier HTML des commandes

1. Dans le dossier ./src/commands , ouvrez commands.html.

2. Juste avant la balise head fermante (</head>), ajoutez l’entrée de script suivante.

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

   Remarque

   La fonctionnalité intégrée de création de rapports de courrier indésirable est actuellement en préversion dans Outlook sur Mac. Si vous testez la fonctionnalité dans ce client, vous devez inclure une référence à la préversion de l’API JavaScript Office dans votre fichier commands.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. Enregistrez vos modifications.

Mettre à jour les paramètres de configuration webpack

1. À partir du répertoire racine de votre projet de complément, ouvrez le fichier webpack.config.js .

2. Recherchez le plugins tableau dans l’objet config et ajoutez ce nouvel objet au début du tableau.

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

3. Enregistrez vos modifications.

Tester et valider votre complément

1. Charger une version test du complément dans un client Outlook pris en charge.
2. Choisissez un message dans votre boîte de réception, puis sélectionnez le bouton du complément dans le ruban.
3. Dans la boîte de dialogue de prétraitement, choisissez un motif pour signaler le message et ajoutez des informations sur le message, si configuré. Ensuite, sélectionnez Rapport.
4. (Facultatif) Dans la boîte de dialogue de post-traitement, sélectionnez OK.

Supprimer la boîte de dialogue de prétraitement

Selon votre scénario, vous n’aurez peut-être pas besoin qu’un utilisateur fournisse des informations supplémentaires sur un message qu’il signale. Si la boîte de dialogue de prétraitement de votre complément de création de rapports de courrier indésirable fournit uniquement des informations à l’utilisateur, vous pouvez choisir d’inclure l’option « Ne plus afficher ce message » dans la boîte de dialogue.

Pour implémenter cela dans votre complément, vous devez spécifier l’élément NeverShowAgainOption dans votre manifeste et lui affecter la valeur true. Voici un exemple de code.

...
    <PreProcessingDialog>
      <Title resid="PreProcessingDialog.Label"/>
      <Description resid="PreProcessingDialog.Text"/>
      <NeverShowAgainOption>true</NeverShowAgainOption>
      <MoreInfo>
        <MoreInfoText resid="MoreInfo.Label"/>
        <MoreInfoUrl resid="MoreInfo.Url"/>
      </MoreInfo>
    </PreProcessingDialog>
...

Notez les comportements suivants lors de l’implémentation de cette option dans votre complément.

• L’option « Ne plus afficher ce message » s’affiche dans la boîte de dialogue de prétraitement uniquement si aucune option d’entrée utilisateur n’est configurée, comme les options de création de rapports ou une zone de texte. Si votre manifeste spécifie également des options d’entrée utilisateur, elles s’affichent dans la boîte de dialogue à la place.

• L’option permettant de supprimer la boîte de dialogue de prétraitement est appliquée par machine et par plateforme.

• Après avoir supprimé la boîte de dialogue de prétraitement, si un utilisateur signale un message et que le volet de lecture est activé, une notification de progression s’affiche sur le message pendant son traitement. Si le volet de lecture est désactivé, aucune notification de progression n’est affichée.

  

  Remarque

  Si vous implémentez l’option « Ne plus afficher ce message » sans configurer de boîte de dialogue de post-traitement, une boîte de dialogue avec le message générique suivant s’affiche à l’utilisateur après le traitement : « Merci d’avoir signalé ce message ». Il est recommandé de configurer une boîte de dialogue de post-traitement pour qu’elle apparaisse après le traitement d’un message signalé.

Réactiver la boîte de dialogue de prétraitement

Pour réactiver la boîte de dialogue de prétraitement dans Outlook classique sur Windows après avoir sélectionné l’option « Ne plus afficher ce message », procédez comme suit.

1. Ouvrez le Rédacteur du Registre en tant qu’administrateur.
2. Accédez à HKEY_CURRENT_USER\Software\Microsoft\Office\16.0\Outlook\Options\WebExt\SpamDialog.
3. Localisez votre complément de signalement de courrier indésirable à l’aide de son ID spécifié dans le manifeste.
4. Supprimez l’entrée de votre complément du Registre.

La boîte de dialogue de prétraitement s’affiche la prochaine fois qu’un message est signalé.

Ouvrir un volet Office après avoir signalé un message

Au lieu d’une boîte de dialogue de post-traitement, vous pouvez implémenter un volet Office à ouvrir après qu’un utilisateur a signalé un message. Par exemple, vous pouvez utiliser le volet Office pour afficher des informations supplémentaires en fonction de l’entrée de l’utilisateur dans la boîte de dialogue de prétraitement. À l’instar de la boîte de dialogue de post-traitement, le volet Office est implémenté via l’appel du event.completed complément.

Pour configurer l’ouverture d’un volet Office après le signalement d’un message, vous devez spécifier l’ID du volet Office dans l’option commandId de l’appel event.completed . L’ID doit correspondre à la valeur spécifiée dans l’attribut id de l’élément Control qui représente le volet Office dans le manifeste.

Si vous devez transmettre des informations au volet Office, spécifiez toutes les données JSON dans l’option contextData de l’appel event.completed . Pour récupérer la valeur de l’option contextData , vous devez appeler Office.context.mailbox.item.getInitializationContextAsync dans l’implémentation JavaScript de votre volet Office.

Voici un exemple de code.

...
    event.completed({
      commandId: "msgReadOpenPaneButton",
      contextData: JSON.stringify({ a: "aValue", b: "bValue" }),
      moveItemTo: Office.MailboxEnums.MoveSpamItemTo.NoMove
    });

Si un autre volet office est ouvert ou épinglé au moment où un message est signalé, le volet Office ouvert est fermé, puis le volet Office du complément de création de rapports de courrier indésirable s’affiche.

Passer en revue le comportement et les limitations des fonctionnalités

À mesure que vous développez et testez la fonctionnalité intégrée de création de rapports de courrier indésirable dans votre complément, tenez compte de ses caractéristiques et limitations.

• Dans Outlook sur le web et sur Windows (nouveau et classique), un complément de création de rapports de courrier indésirable intégré remplace le bouton Rapport natif dans le ruban Outlook. Si plusieurs compléments de création de rapports de courrier indésirable sont installés, ils apparaissent tous dans la section Rapport du ruban.

  

• Un complément de signalement de courrier indésirable peut s’exécuter pendant un maximum de cinq minutes une fois qu’il est activé. Tout traitement qui se produit au-delà de cinq minutes entraîne l’expiration du complément. Si le complément expire, une boîte de dialogue s’affiche à l’utilisateur pour l’en informer.

  

• Dans Outlook classique sur Windows, un complément de signalement de courrier indésirable peut être utilisé pour signaler un message même si le volet de lecture du client Outlook est désactivé. Dans Outlook sur le web, sur Mac et dans la nouvelle version d’Outlook sur Windows, le complément de création de rapports de courrier indésirable peut être utilisé si le volet de lecture est activé ou si le message à signaler est ouvert dans une autre fenêtre.

• Un seul message peut être signalé à la fois. Si vous sélectionnez plusieurs messages à signaler, le bouton du complément de création de rapports de courrier indésirable devient indisponible.

• Dans Outlook sur Windows classique, un seul message signalé peut être traité à la fois. Si un utilisateur tente de signaler un autre message alors que le précédent est encore en cours de traitement, une boîte de dialogue s’affiche pour l’en informer.

  

  Cela ne s’applique pas à Outlook sur le web ou sur Mac, ni à la nouvelle version d’Outlook sur Windows. Dans ces clients Outlook, un utilisateur peut signaler un message à partir du volet de lecture et signaler simultanément chaque message ouvert dans une fenêtre distincte.

• Le complément peut toujours traiter le message signalé même si l’utilisateur quitte le message sélectionné. Dans Outlook sur Mac, cette option n’est prise en charge que si un utilisateur signale un message alors qu’il est ouvert dans une fenêtre distincte. Si l’utilisateur signale un message tout en l’affichant à partir du volet de lecture, puis s’en éloigne, le processus de création de rapports est terminé.

• Dans Outlook sur le web et le nouvel Outlook sur Windows, si un message est signalé alors qu’il est ouvert dans une fenêtre distincte, une boîte de dialogue de post-traitement n’est pas affichée à l’utilisateur.

• Les boutons qui apparaissent dans les boîtes de dialogue de prétraitement et de post-traitement ne sont pas personnalisables. En outre, le texte et les boutons dans les boîtes de dialogue de délai d’expiration et de rapport en cours ne peuvent pas être modifiés.

• Les fonctionnalités intégrées de création de rapports de courrier indésirable et d’activation basée sur les événements doivent utiliser le même runtime. Les runtimes multiples ne sont actuellement pas pris en charge dans Outlook. Pour en savoir plus sur les runtimes, voir Runtimes dans les compléments Office.

• Un complément de création de rapports de courrier indésirable implémente uniquement les commandes de fonction. Une commande du volet Office ne peut pas être affectée au bouton de création de rapports de courrier indésirable sur le ruban. Si vous souhaitez implémenter un volet Office dans votre complément, vous devez le configurer dans votre manifeste comme suit :

  • Manifeste de complément uniquement : incluez l’élément Action dans le manifeste et définissez son xsi:type attribut sur ShowTaskpane.
  • Manifeste unifié pour Microsoft 365 : Configurez un objet du volet Office dans les tableaux « extensions.runtimes » et « extensions.ribbons ». Pour obtenir de l’aide, consultez la section « Ajouter une commande du volet Office » de Créer des commandes de complément avec le manifeste unifié pour Microsoft 365.

  Notez qu’un bouton distinct pour activer le volet Office sera ajouté au ruban, mais qu’il n’apparaîtra pas dans la zone dédiée de création de rapports de courrier indésirable du ruban.

Résoudre les problèmes de votre complément

À mesure que vous développez votre complément de création de rapports de courrier indésirable, vous devrez peut-être résoudre les problèmes, tels que le non-chargement de votre complément. Pour obtenir des conseils sur la façon de résoudre les problèmes d’un complément de création de rapports de courrier indésirable, consultez Résoudre les problèmes liés aux compléments basés sur les événements et la création de rapports de courrier indésirable.

Voir aussi

• Manifeste des compléments Office
• Temps d'exécution dans les compléments Office
• Résoudre les problèmes liés aux modules complémentaires de signalement d'événements et de spams
• Point d’extension ReportPhishingCommandSurface
• Office.MessageRead.getAsFileAsync
• Office.MailboxEnums.MoveSpamItemTo
• Office.SpamReportingEventArgs
• Office.SpamReportingEventCompletedOptions