Compartilhar via

Implementar um suplemento integrado de relatórios de spam

  • Artigo

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.

Observação

Os relatórios de spam integrados foram introduzidos no conjunto de requisitos da Caixa de Correio 1.14. Para obter informações sobre o suporte de cliente para esta funcionalidade, veja Clientes suportados.

Clientes com suporte

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

Cliente Status
Outlook na web Com suporte
novo Outlook no Windows (pré-visualização) Com suporte
Outlook clássico no Windows
Versão 2404 (Compilação 17530.15000)		 Com suporte
Outlook no Mac
Versão 16.81.1217.0 ou posterior		 Pré-visualização (consulte Pré-visualizar a funcionalidade integrada de relatórios de spam no Outlook no Mac)
Outlook no Android Não disponível
Outlook no iOS Não disponível

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

Dica

Para experimentar imediatamente uma solução de suplemento de relatórios de spam concluída, consulte o exemplo Reportar e-mails de spam ou phishing no Outlook .

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

Observação

Os relatórios de spam integrados ainda não são suportados para o manifesto unificado do Microsoft 365.

Para implementar a funcionalidade de relatórios de spam integrada no seu suplemento, tem de configurar o nó VersionOverridesV1_1 do manifesto em conformidade.

  • No Outlook na Web e no Mac e no novo Outlook no Windows, é executado um suplemento que implementa a funcionalidade integrada de relatórios de spam num runtime do browser. Tem de especificar o ficheiro HTML que referencia ou contém o código para processar o evento spam-reporting no resid atributo do elemento Runtime .
  • No Outlook clássico no Windows, um suplemento que implementa a funcionalidade de relatórios de spam integrada é executado num runtime apenas em JavaScript. Como tal, tem de especificar o ficheiro JavaScript que contém o código para processar o evento spam-reporting no elemento subordinado Substituir do <elemento Runtime> .
  • Para ativar o suplemento no friso do Outlook e impedi-lo de aparecer no final do friso ou na secção de capacidade excedida, defina o xsi:type atributo do <elemento ExtensionPoint> como ReportPhishingCommandSurface.
  • Para personalizar o botão do friso e a caixa de diálogo de pré-processamento, tem de definir o nó ReportPhishingCustomization .

    • Um utilizador comunica uma mensagem não solicitada através do botão do suplemento no friso. Para configurar o botão do friso, defina o xsi:type atributo do elemento Controlo como Button. Em seguida, defina o xsi:type atributo do elemento subordinado Ação como ExecuteFunction e especifique o nome do processador de eventos spam-reporting no elemento <subordinado FunctionName> . Um suplemento spam-reporting só pode implementar comandos de função.

      Segue-se um exemplo de como o botão de um suplemento de relatórios de spam aparece no friso do cliente 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.

      Um botão do friso de exemplo de um suplemento spam-reporting.

    • A caixa de diálogo de pré-processamento é apresentada a um utilizador quando seleciona o botão de suplemento. É configurado através do elemento PreProcessingDialog do seu manifesto. Embora a caixa de diálogo tenha de ter um título e uma descrição, pode incluir opcionalmente os seguintes elementos.

      • Uma lista de seleções múltiplas de opções para ajudar um utilizador a identificar o tipo de mensagem que está a comunicar. Para saber como configurar estas opções de relatórios, veja ReportingOptions element (Elemento ReportingOptions).

      • Uma caixa de texto para o utilizador fornecer informações adicionais sobre a mensagem que está a comunicar. Para saber como implementar uma caixa de texto, consulte FreeTextLabel element (Elemento FreeTextLabel).

      • Texto personalizado e URL para fornecer recursos informativos ao utilizador. Para saber como personalizar estes elementos, consulte o elemento MoreInfo.

        Observação

        Dependendo do cliente do Outlook, o texto personalizado especificado no <elemento MoreInfoText> é apresentado antes do URL fornecido no <elemento MoreInfoUrl> ou como texto de ligação para o URL. Para obter mais informações, consulte MoreInfoText.

      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.

      Uma caixa de diálogo de pré-processamento de exemplo de um suplemento spam-reporting.

Segue-se um exemplo de um <nó VersionOverrides configurado para relatórios> de spam.

  1. No seu editor de código preferido, abra o projeto de suplemento que criou.

  2. Abra o ficheiro manifest.xml localizado na raiz do projeto.

  3. Selecione todo <o nó VersionOverrides> (incluindo as etiquetas abrir e fechar) e substitua-o pelo seguinte código.

    <VersionOverrides xmlns="http://schemas.microsoft.com/office/mailappversionoverrides" xsi:type="VersionOverridesV1_0">
  <VersionOverrides xmlns="http://schemas.microsoft.com/office/mailappversionoverrides/1.1" xsi:type="VersionOverridesV1_1">
    <Requirements>
      <bt:Sets DefaultMinVersion="1.14">
        <bt:Set Name="Mailbox"/>
      </bt:Sets>
    </Requirements>
    <Hosts>
      <Host xsi:type="MailHost">
        <Runtimes>
            <!-- References the HTML file that links to the spam-reporting event handler.
                 This is used by Outlook on the web and on the new Mac UI, and new Outlook on Windows (preview). -->
          <Runtime resid="WebViewRuntime.Url">
            <!-- References the JavaScript file that contains the spam-reporting event handler. This is used by classic Outlook on Windows. -->
            <Override type="javascript" resid="JSRuntime.Url"/>
          </Runtime>
        </Runtimes>
        <DesktopFormFactor>
          <FunctionFile resid="WebViewRuntime.Url"/>
          <!-- Implements the integrated spam-reporting feature in the add-in. -->
          <ExtensionPoint xsi:type="ReportPhishingCommandSurface">
            <ReportPhishingCustomization>
              <!-- Configures the ribbon button. -->
              <Control xsi:type="Button" id="spamReportingButton">
                <Label resid="spamButton.Label"/>
                <Supertip>
                  <Title resid="spamButton.Label"/>
                  <Description resid="spamSuperTip.Text"/>
                </Supertip>
                <Icon>
                  <bt:Image size="16" resid="Icon.16x16"/>
                  <bt:Image size="32" resid="Icon.32x32"/>
                  <bt:Image size="80" resid="Icon.80x80"/>
                </Icon>
                <Action xsi:type="ExecuteFunction">
                  <FunctionName>onSpamReport</FunctionName>
                </Action>
              </Control>
              <!-- Configures the preprocessing dialog. -->
              <PreProcessingDialog>
                <Title resid="PreProcessingDialog.Label"/>
                <Description resid="PreProcessingDialog.Text"/>
                <ReportingOptions>
                  <Title resid="OptionsTitle.Label"/>
                  <Option resid="Option1.Label"/>
                  <Option resid="Option2.Label"/>
                  <Option resid="Option3.Label"/>
                </ReportingOptions>
                <FreeTextLabel resid="FreeText.Label"/>
                <MoreInfo>
                  <MoreInfoText resid="MoreInfo.Label"/>
                  <MoreInfoUrl resid="MoreInfo.Url"/>
                </MoreInfo>
              </PreProcessingDialog>
             <!-- Identifies the runtime to be used. This is also referenced by the Runtime element. -->
              <SourceLocation resid="WebViewRuntime.Url"/>
            </ReportPhishingCustomization> 
          </ExtensionPoint>
        </DesktopFormFactor>
      </Host>
    </Hosts>
    <Resources>
      <bt:Images>
        <bt:Image id="Icon.16x16" DefaultValue="https://localhost:3000/assets/icon-16.png"/>
        <bt:Image id="Icon.32x32" DefaultValue="https://localhost:3000/assets/icon-32.png"/>
        <bt:Image id="Icon.80x80" DefaultValue="https://localhost:3000/assets/icon-80.png"/>
      </bt:Images>
      <bt:Urls>
        <bt:Url id="WebViewRuntime.Url" DefaultValue="https://localhost:3000/commands.html"/>
        <bt:Url id="JSRuntime.Url" DefaultValue="https://localhost:3000/spamreporting.js"/>
        <bt:Url id="MoreInfo.Url" DefaultValue="https://www.contoso.com/spamreporting"/>
      </bt:Urls>
      <bt:ShortStrings>
        <bt:String id="spamButton.Label" DefaultValue="Report Spam Message"/>
        <bt:String id="PreProcessingDialog.Label" DefaultValue="Report Spam Message"/>
        <bt:String id="OptionsTitle.Label" DefaultValue="Why are you reporting this email?"/>
        <bt:String id="FreeText.Label" DefaultValue="Provide additional information, if any:"/>
        <bt:String id="MoreInfo.Label" DefaultValue="Reporting unsolicited messages"/>
        <bt:String id="Option1.Label" DefaultValue="Received spam email."/>
        <bt:String id="Option2.Label" DefaultValue="Received a phishing email."/>
        <bt:String id="Option3.Label" DefaultValue="I'm not sure this is a legitimate email."/>
      </bt:ShortStrings>
      <bt:LongStrings>
        <bt:String id="spamSuperTip.Text" DefaultValue="Report an unsolicited message."/>
        <bt:String id="PreProcessingDialog.Text" DefaultValue="Thank you for reporting this message."/>
      </bt:LongStrings>
    </Resources>
  </VersionOverrides>
</VersionOverrides>

  4. Salve suas alterações.

Implementar o manipulador de eventos

Quando o suplemento é utilizado para comunicar uma mensagem, gera um evento SpamReporting , que é processado pelo processador de eventos no ficheiro JavaScript do seu suplemento. Para mapear o nome do processador de eventos que especificou no <elemento FunctionName> do 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 the Outlook client on Windows, remember to map the event handler name specified in the manifest to its JavaScript counterpart.
if (Office.context.platform === Office.PlatformType.PC || Office.context.platform == null) {
  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 the Outlook client on Windows, remember to map the event handler name specified in the manifest to its JavaScript counterpart.
if (Office.context.platform === Office.PlatformType.PC || Office.context.platform == null) {
  Office.actions.associate("onSpamReport", onSpamReport);
}

  2. Salve suas alterações.

Observação

Para configurar o início de sessão único (SSO) ou a partilha de recursos de várias origens (CORS) no seu suplemento de relatórios de spam, tem de adicionar o suplemento e o respetivo ficheiro JavaScript a um URI conhecido. Para obter orientações sobre como configurar este recurso, veja Utilizar o início de sessão único (SSO) ou a partilha de recursos de várias origens (CORS) no seu suplemento do Outlook baseado em eventos ou relatórios de spam.

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.

Observação

O código adicionado após a event.completed chamada não é garantido para ser executado.

  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 the Outlook client on Windows, remember to map the event handler name specified in the manifest to its JavaScript counterpart
if (Office.context.platform === Office.PlatformType.PC || Office.context.platform == null) {
  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 no Mac, o Outlook na Web ou o novo Outlook no Windows (pré-visualização), 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.

Um exemplo de uma caixa de diálogo pós-processamento apresentada depois de uma mensagem de spam reportada ter sido processada pelo suplemento.

Dica

À medida que desenvolve um suplemento de relatórios de spam que será executado no Outlook no Windows, tenha em atenção o seguinte.

  • As importações não são atualmente suportadas no ficheiro JavaScript que contém o código para processar o evento spam-reporting.
  • O código incluído nas Office.onReady() funções e Office.initialize não será executado. Tem de adicionar qualquer lógica de arranque do suplemento, como verificar a versão do Outlook do utilizador, aos processadores de eventos.

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.

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

    A caixa de diálogo apresentada quando um suplemento spam-reporting excede o tempo limite.

  • 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 entanto, isto não é suportado no Outlook para Mac. No Outlook no Mac, o Painel de Leitura tem de estar ativado para utilizar um suplemento de relatórios de spam.

  • No Outlook clássico no Windows, só pode ser comunicada uma mensagem 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.

    A caixa de diálogo apresentada quando o utilizador tenta comunicar outra mensagem enquanto a anterior ainda está a ser processada.

    Isto não se aplica ao Outlook no Mac ou na Web, nem ao novo Outlook no Windows (pré-visualização). 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.

  • 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 incluir o elemento Ação no manifesto e definir o respetivo xsi:type atributo como ShowTaskpane. 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