Partager via

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

  • Article

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.

Remarque

La création de rapports de courrier indésirable intégré a été introduite dans l’ensemble de conditions requises de boîte aux lettres 1.14. Pour plus d’informations sur la prise en charge des clients pour cette fonctionnalité, consultez Clients pris en charge.

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.

Client État
Outlook sur le Web Pris en charge
nouvel Outlook sur Windows Pris en charge
Outlook classique sur Windows
Version 2404 (build 17530.15000)		 Pris en charge
Outlook sur Mac
Version 16.81 (23121700) ou ultérieure		 Préversion (voir Aperçu de la fonctionnalité intégrée de création de rapports de courrier indésirable dans Outlook sur Mac)
Outlook sur Android Non disponible
Outlook sur iOS Non disponible

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

Conseil

Pour essayer immédiatement une solution de complément de signalement de courrier indésirable terminée, consultez l’exemple Signaler le courrier indésirable ou les e-mails d’hameçonnage dans Outlook .

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.

    Exemple de bouton de ruban d’un complément de création de rapports de courrier indésirable.

  • Boîte de dialogue de prétraitement. Cette boîte de dialogue s’affiche à l’utilisateur lorsqu’il sélectionne le bouton du complément. Dans cette boîte de dialogue, un utilisateur peut fournir des informations supplémentaires sur le message qu’il signale. 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.

    Exemple de boîte de dialogue de prétraitement d’un complément de signalement de courrier indésirable.

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

Remarque

L’implémentation de rapports de courrier indésirable intégrés avec le manifeste unifié pour Microsoft 365 est en préversion publique pour les développeurs. Il est actuellement disponible uniquement pour une utilisation dans Outlook classique sur Windows. Il ne doit pas être utilisé dans les compléments de production. Nous vous invitons à l’essayer dans des environnements de test ou de développement. Pour plus d’informations, consultez Schéma du manifeste de l’application développeur public en préversion.

  1. Dans votre éditeur de code préféré, ouvrez le projet de complément que vous avez créé.

  2. Ouvrez le fichier manifest.json .

  3. Ajoutez l’objet suivant au tableau « extensions.runtimes ». Notez les points suivants concernant ce balisage.

    • La valeur « minVersion » de l’ensemble de conditions requises pour la boîte aux lettres est configurée sur « 1.14 ». Il s’agit de la version la plus basse de l’ensemble de conditions requises qui prend en charge la fonctionnalité intégrée de création de rapports de courrier indésirable.
    • L'« id » du runtime est défini sur un nom descriptif unique, « spam_reporting_runtime ».
    • La propriété « code » a une propriété « page » enfant qui est définie sur un fichier HTML et une propriété « script » enfant qui est définie sur un fichier JavaScript. Vous allez créer ou modifier ces fichiers dans les étapes ultérieures.
    • La propriété « lifetime » est définie sur « short ». Cela signifie que le runtime démarre lorsque l’événement SpamReporting se produit et s’arrête lorsque le gestionnaire d’événements se termine.
    • L’objet « actions » spécifie la fonction de gestionnaire d’événements qui s’exécute dans le runtime. Vous allez créer cette fonction dans une étape ultérieure.
    {
    "requirements": {
        "capabilities": [
            {
                "name": "Mailbox",
                "minVersion": "1.14"
            }
        ]
    },
    "id": "spam_reporting_runtime",
    "type": "general",
    "code": {
        "page": "https://localhost:3000/commands.html",
        "script": "https://localhost:3000/spamreporting.js"
    },
    "lifetime": "short",
    "actions": [
        {
            "id": "onSpamReport",
            "type": "executeFunction"
        }
    ]
},

  4. Ajoutez l’objet suivant au tableau « extensions.ribbons ». Notez les points suivants concernant ce balisage.

    • Le tableau « contexts » contient la chaîne « spamReportingOverride ». Cela empêche le bouton du complément d’apparaître à la fin du ruban ou dans la section de dépassement.
    • Le tableau « fixedControls » contient un objet qui configure l’apparence et les fonctionnalités du bouton de complément sur le ruban. Le nom du gestionnaire d’événements spécifié dans la propriété « actionId » doit correspondre à la valeur utilisée dans la propriété « id » de l’objet dans le tableau « actions ». Bien que la propriété « enabled » soit spécifiée dans le tableau, sa valeur n’affecte pas les fonctionnalités d’un complément de création de rapports de courrier indésirable.
    • L’objet « spamPreProcessingDialog » spécifie les informations et les options affichées dans la boîte de dialogue de prétraitement. Bien que vous deviez spécifier un « titre » et une « description » pour la boîte de dialogue, vous pouvez éventuellement configurer les propriétés suivantes.
      • Objet « spamReportingOptions ». Il fournit une liste de sélections multiples pouvant contenir jusqu’à cinq choix. Cela permet à un utilisateur d’identifier le type de message qu’il signale.
      • Propriété « spamFreeTextSectionTitle ». Il fournit une zone de texte permettant à l’utilisateur d’ajouter plus d’informations sur le message qu’il signale.
      • Objet « spamMoreInfo ». Il inclut un lien dans la boîte de dialogue pour fournir des ressources d’information à l’utilisateur.
    {
    "contexts": [
        "spamReportingOverride"
    ],
    "fixedControls": [
        {
            "id": "spamReportingButton",
            "type": "button",
            "label": "Report Spam Message",
            "enabled": false,
            "icons": [
                {
                    "size": 16,
                    "url": "https://localhost:3000/assets/icon-16.png"
                },
                {
                    "size": 32,
                    "url": "https://localhost:3000/assets/icon-32.png"
                },
                {
                    "size": 80,
                    "url": "https://localhost:3000/assets/icon-80.png"
                }
            ],
            "supertip": {
                "title": "Report Spam Message",
                "description": "Report an unsolicited message."
            },
            "actionId": "onSpamReport"
        }
    ],
    "spamPreProcessingDialog": {
        "title": "Report Spam Message",
        "description": "Thank you for reporting this message.",
        "spamReportingOptions": {
            "title": "Why are you reporting this email?",
            "options": [
                "Received spam email.",
                "Received a phishing email.",
                "I'm not sure this is a legitimate email."
            ]
        },
        "spamFreeTextSectionTitle": "Provide additional information, if any:",
        "spamMoreInfo": {
            "text": "Reporting unsolicited messages",
            "url": "https://www.contoso.com/spamreporting"
        }
    }
},

  5. Enregistrez vos modifications.

Conseil

Pour en savoir plus sur les manifestes pour les compléments Outlook, voir Manifeste des compléments Office.

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.

Remarque

Pour configurer l’authentification unique (SSO) ou le partage de ressources cross-origin (CORS) dans votre complément de création de rapports de courrier indésirable, vous devez ajouter votre complément et son fichier JavaScript à un URI connu. Pour obtenir des conseils sur la configuration de cette ressource, consultez Utiliser l’authentification unique (SSO) ou le partage de ressources cross-origin (CORS) dans votre complément Outlook basé sur les événements ou la création de rapports de courrier indésirable.

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 personnaliser une boîte de dialogue de post-traitement afin de montrer à l’utilisateur ou d’effectuer des opérations supplémentaires sur le message, telles que la suppression de celui-ci de la boîte de réception. 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.

Remarque

L’exécution du code ajouté après l’appel event.completed n’est pas garantie.

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

Exemple de boîte de dialogue de post-traitement affichée une fois qu’un message indésirable signalé a été traité par le complément.

Conseil

Lorsque vous développez un complément de création de rapports de courrier indésirable qui s’exécutera dans Outlook sur Windows, gardez les points suivants à l’esprit.

  • Les importations ne sont actuellement pas prises en charge dans le fichier JavaScript qui contient le code permettant de gérer l’événement de signalement de courrier indésirable.
  • Le code inclus dans les Office.onReady() fonctions et Office.initialize ne s’exécute pas. Vous devez ajouter une logique de démarrage de complément, telle que la vérification de la version d’Outlook de l’utilisateur, à vos gestionnaires d’événements à la place.

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.

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.

    Exemple de complément de création de rapports de courrier indésirable intégré qui remplace le bouton Rapport dans le ruban Outlook.

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

    Boîte de dialogue affichée lorsqu’un complément de signalement de courrier indésirable expire.

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

    Boîte de dialogue affichée lorsque l’utilisateur tente de signaler un autre message alors que le précédent est encore en cours de traitement.

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

  • 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 :

    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

Lorsque 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