Implementar um suplemento integrado de relatórios de spam

Com o número de e-mails não solicitados a aumentar, a segurança está na vanguarda da utilização do suplemento. Atualmente, os suplementos de relatórios de spam de parceiros são adicionados ao friso do Outlook, mas normalmente aparecem no final do friso ou no menu de capacidade excedida. Isto torna mais difícil para os utilizadores localizar o suplemento para comunicar e-mails não solicitados. Além de configurar a forma como as mensagens são processadas quando são reportadas, os programadores também precisam de concluir tarefas adicionais para mostrar caixas de diálogo de processamento ou informações suplementares ao utilizador.

A funcionalidade integrada de relatórios de spam facilita a tarefa de desenvolver componentes de suplementos individuais do zero. Mais importante ainda, apresenta o seu suplemento num local proeminente no friso do Outlook, tornando mais fácil para os utilizadores localizá-lo e comunicar mensagens de spam. Implemente esta funcionalidade no seu suplemento para:

• Melhore a forma como as mensagens não solicitadas são controladas.
• Forneça melhores orientações aos utilizadores sobre como comunicar mensagens suspeitas.
• Ative o centro de operações de segurança (SOC) ou os administradores de TI de uma organização para realizar facilmente simulações de spam e phishing para fins educativos.

Clientes com suporte

A tabela seguinte identifica quais os clientes do Outlook que suportam a funcionalidade de relatórios de spam integrada.

Pré-visualizar a funcionalidade integrada de relatórios de spam no Outlook para Mac

Para pré-visualizar a funcionalidade integrada de relatórios de spam no Outlook para Mac, tem de instalar a Versão 16.81.1217.0 ou posterior. Em seguida, adira ao programa Microsoft 365 Insider e selecione a opção Canal Beta para aceder às compilações beta do Office.

Configurar seu ambiente

Conclua o guia de introdução do Outlook, que cria um projeto de suplemento com o gerador Yeoman para Suplementos do Office.

Configurar o manifesto

Para implementar a funcionalidade de spam-reporting integrada no seu suplemento, tem de configurar o seguinte no seu manifesto.

• O runtime utilizado pelo suplemento. No Outlook clássico no Windows, um suplemento de relatórios de spam é executado num runtime apenas javaScript. No Outlook na Web e no Mac e no novo Outlook no Windows, é executado um suplemento de relatórios de spam num runtime do browser. Para obter mais informações, consulte Runtimes nos Suplementos do Office.

• O botão do suplemento spam-reporting que aparece sempre num local proeminente no friso do Outlook. Segue-se um exemplo de como o botão de um suplemento de relatórios de spam aparece no friso do cliente clássico do Outlook no Windows. A IU do friso pode variar consoante a plataforma na qual o cliente do Outlook do utilizador está a ser executado.

  

• A caixa de diálogo de pré-processamento. Esta caixa de diálogo é apresentada ao utilizador quando seleciona o botão de suplemento. Nesta caixa de diálogo, um utilizador pode fornecer informações adicionais sobre a mensagem que está a comunicar. Quando um utilizador seleciona Relatório na caixa de diálogo, o evento SpamReporting é ativado e, em seguida, processado pelo processador de eventos JavaScript. Segue-se um exemplo de uma caixa de diálogo de pré-processamento no Outlook no Windows. Tenha em atenção que o aspeto da caixa de diálogo pode variar consoante a plataforma em que o cliente do Outlook do utilizador está a ser executado.

  

Selecione o separador para o tipo de manifesto que está a utilizar.

Implementar o manipulador de eventos

Quando o suplemento é utilizado para comunicar uma mensagem, gera um SpamReporting evento, que é processado pelo processador de eventos no ficheiro JavaScript do seu suplemento. Para mapear o nome do processador de eventos que especificou no seu manifesto para o seu homólogo JavaScript, tem de chamar Office.actions.associate no seu código.

1. No seu projeto de suplemento, navegue para o diretório ./src . Em seguida, crie uma nova pasta com o nome spamreporting.

2. Na pasta ./src/spamreporting , crie um novo ficheiro com o nome spamreporting.js.

3. Abra o ficheiro despamreporting.js recentemente criado e adicione o seguinte 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. Salve suas alterações.

Reencaminhar uma cópia da mensagem e obter as respostas da caixa de diálogo de pré-processamento

O processador de eventos é responsável pelo processamento da mensagem reportada. Pode configurá-la para reencaminhar informações, como uma cópia da mensagem ou as opções selecionadas pelo utilizador na caixa de diálogo de pré-processamento, para um sistema interno para uma investigação mais aprofundada.

Para enviar eficientemente uma cópia da mensagem reportada, chame o método getAsFileAsync no processador de eventos. Esta ação obtém o formato EML codificado em Base64 de uma mensagem, que pode reencaminhar para o seu sistema interno.

Se precisar de controlar as respostas do utilizador às opções e à caixa de texto na caixa de diálogo de pré-processamento, extraia os options valores e freeText do SpamReporting objeto de evento. Para obter mais informações sobre estas propriedades, consulte Office.SpamReportingEventArgs.

Segue-se um exemplo de um processador de eventos de relatórios de spam que chama o getAsFileAsync método e obtém as respostas do utilizador a SpamReporting partir do objeto de evento.

1. No ficheiro spamreporting.js , substitua o respetivo conteúdo pelo seguinte código.

   // 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. Salve suas alterações.

Sinalizar quando o evento tiver sido processado

Assim que o processador de eventos concluir o processamento da mensagem, tem de chamar o método event.completed . Além de sinalizar para o suplemento que o evento spam-reporting foi processado, event.completed também pode ser utilizado para personalizar uma caixa de diálogo pós-processamento para mostrar ao utilizador ou efetuar operações adicionais na mensagem, como eliminá-lo da caixa de entrada. Para obter uma lista de propriedades que pode incluir num objeto JSON para transmitir como um parâmetro para o event.completed método, consulte Office.SpamReportingEventCompletedOptions.

1. No ficheiro spamreporting.js , substitua o respetivo conteúdo pelo seguinte código.

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

   Observação

   Se estiver a utilizar o Outlook clássico no Windows Versão 2308 (Compilação 16724.10000) ou posterior, o Outlook para Mac, Outlook na Web ou o novo Outlook no Windows, tem de utilizar a moveItemTo propriedade na event.completed chamada para especificar a pasta para a qual uma mensagem reportada é movida assim que for processada pelo seu suplemento. Nas compilações anteriores do Outlook no Windows que suportam a funcionalidade integrada de relatórios de spam, tem de utilizar a postProcessingAction propriedade .

2. Salve suas alterações.

Segue-se uma caixa de diálogo de pós-processamento de exemplo apresentada ao utilizador assim que o suplemento concluir o processamento de uma mensagem reportada no Outlook no Windows. Tenha em atenção que o aspeto da caixa de diálogo pode variar consoante a plataforma em que o cliente do Outlook do utilizador está a ser executado.

Atualizar o ficheiro HTML dos comandos

1. Na pasta ./src/commands , abra commands.html.

2. Imediatamente antes da etiqueta principal de fecho (</head>), adicione a seguinte entrada de script .

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

   Observação

   A funcionalidade de relatórios de spam integrada está atualmente em pré-visualização no Outlook para Mac. Se estiver a testar a funcionalidade neste cliente, tem de incluir uma referência à versão de pré-visualização da API JavaScript do Office no seu ficheiro 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. Salve suas alterações.

Atualizar as definições de configuração do webpack

1. No diretório de raiz do projeto de suplemento, abra o ficheiro webpack.config.js .

2. Localize a plugins matriz no config objeto e adicione este novo objeto ao início da matriz.

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

3. Salve suas alterações.

Testar e validar o suplemento

1. Faça sideload do suplemento num cliente do Outlook suportado.
2. Selecione uma mensagem a partir da sua caixa de entrada e, em seguida, selecione o botão do suplemento no friso.
3. Na caixa de diálogo de pré-processamento, escolha um motivo para comunicar a mensagem e adicione informações sobre a mensagem, se estiver configurada. Em seguida, selecione Relatório.
4. (Opcional) Na caixa de diálogo pós-processamento, selecione OK.

Rever o comportamento e as limitações das funcionalidades

À medida que desenvolve e testa a funcionalidade integrada de spam-reporting no seu suplemento, tenha em atenção as suas características e limitações.

• No Outlook na Web e no Windows (novo e clássico), um suplemento integrado de relatórios de spam substitui o botão relatório nativo no friso do Outlook. Se estiverem instalados vários suplementos de relatórios de spam, todos serão apresentados na secção Relatório do friso.

  

• Um suplemento de relatórios de spam pode ser executado durante um máximo de cinco minutos depois de ser ativado. Qualquer processamento que ocorra após cinco minutos fará com que o suplemento exceda o tempo limite. Se o suplemento exceder o limite de tempo, será apresentada uma caixa de diálogo ao utilizador para notificá-lo.

  

• No Outlook clássico no Windows, um suplemento de relatórios de spam pode ser utilizado para comunicar uma mensagem, mesmo que o Painel de Leitura do cliente do Outlook esteja desativado. No Outlook na Web, no Mac e no novo Outlook no Windows, o suplemento de relatórios de spam pode ser utilizado se o Painel de Leitura estiver ativado ou a mensagem a ser comunicada estiver aberta noutra janela.

• Só é possível reportar uma mensagem de cada vez. Se selecionar várias mensagens a reportar, o botão do suplemento spam-reporting fica indisponível.

• No Outlook clássico no Windows, apenas uma mensagem comunicada pode ser processada de cada vez. Se um utilizador tentar comunicar outra mensagem enquanto a anterior ainda está a ser processada, será apresentada uma caixa de diálogo para notificá-la.

  

  Isto não se aplica ao Outlook na Web, ao Mac ou ao novo Outlook no Windows. Nestes clientes do Outlook, um utilizador pode comunicar uma mensagem a partir do Painel de Leitura e pode comunicar simultaneamente cada mensagem aberta numa janela separada.

• O suplemento ainda pode processar a mensagem reportada mesmo que o utilizador navegue para fora da mensagem selecionada. No Outlook para Mac, isto só é suportado se um utilizador comunicar uma mensagem enquanto está aberta numa janela separada. Se o utilizador comunicar uma mensagem ao vê-la a partir do Painel de Leitura e, em seguida, navegar para fora da mesma, o processo de relatório é terminado.

• Os botões que aparecem nas caixas de diálogo de pré-processamento e pós-processamento não são personalizáveis. Além disso, o texto e os botões nas caixas de diálogo de relatórios em curso e tempo limite não podem ser modificados.

• As funcionalidades integradas de relatórios de spam e ativação baseada em eventos têm de utilizar o mesmo runtime. Atualmente, não são suportados vários runtimes no Outlook. Para saber mais sobre runtimes, consulte Runtimes nos Suplementos do Office.

• Um suplemento spam-reporting implementa apenas comandos de função. Não é possível atribuir um comando do painel de tarefas ao botão spam-reporting no friso. Se quiser implementar um painel de tarefas no seu suplemento, tem de configurá-lo no seu manifesto da seguinte forma:

  • Manifesto apenas de suplemento: inclua o elemento Ação no manifesto e defina o respetivo xsi:type atributo como ShowTaskpane.
  • Manifesto unificado para o Microsoft 365: configure um objeto do painel de tarefas nas matrizes "extensions.runtimes" e "extensions.ribbons". Para obter orientações, consulte a secção "Adicionar um comando do painel de tarefas" de Criar comandos de suplementos com o manifesto unificado para o Microsoft 365.

  Tenha em atenção que um botão separado para ativar o painel de tarefas será adicionado ao friso, mas não será apresentado na área dedicada de relatórios de spam do friso.

Resolver problemas do suplemento

À medida que desenvolve o seu suplemento de relatórios de spam, poderá ter de resolver problemas, como o suplemento não estar a carregar. Para obter orientações sobre como resolver problemas de um suplemento de relatórios de spam, veja Resolver problemas de suplementos baseados em eventos e relatórios de spam.

Confira também

• Manifesto de Suplementos do Office
• Runtimes nos Suplementos do Office
• Resolver problemas de suplementos baseados em eventos e relatórios de spam
• ReportPhishingCommandSurface extension point (Ponto de extensão ReportPhishingCommandSurface)
• Office.MessageRead.getAsFileAsync
• Office.MailboxEnums.MoveSpamItemTo
• Office.SpamReportingEventArgs
• Office.SpamReportingEventCompletedOptions