Implementar um suplemento integrado de relatório de spam (versão prévia)

Artigo
05/03/2024

Com o número de emails não solicitados em ascensão, a segurança está na vanguarda do uso do suplemento. Atualmente, os suplementos de relatório de spam do parceiro são adicionados à faixa de opções do Outlook, mas geralmente aparecem no final da faixa de opções ou no menu de estouro. Isso torna mais difícil para os usuários localizarem o suplemento para relatar emails não solicitados. Além de configurar como as mensagens são processadas quando são relatadas, os desenvolvedores também precisam concluir tarefas adicionais para mostrar diálogos de processamento ou informações complementares ao usuário.

O recurso de relatório de spam integrado facilita a tarefa de desenvolver componentes de suplemento individuais do zero. Mais importante, ele exibe seu suplemento em um local proeminente na faixa de opções do Outlook, facilitando a localização dos usuários e o relatório de mensagens de spam. Implemente esse recurso no suplemento para:

Melhore a forma como as mensagens não solicitadas são rastreadas.
Forneça melhores diretrizes aos usuários sobre como relatar mensagens suspeitas.
Habilite o SOC (centro de operações de segurança) ou administradores de TI de uma organização para executar facilmente simulações de spam e phishing para fins educacionais.

Importante

O recurso de relatório de spam integrado está atualmente em versão prévia no Outlook clássico no Windows e no Outlook no Mac. O suporte de visualização para o recurso em Outlook na Web e novo Outlook no Windows (versão prévia) está sendo implantado no momento.

Os recursos na versão prévia não devem ser usados em suplementos de produção. Convidamos você a experimentar esse recurso em ambientes de teste ou desenvolvimento e receber comentários sobre sua experiência por meio do GitHub (confira a seção Comentários no final desta página).

Visualizar o recurso de relatório de spam integrado

Para visualizar o recurso de relatório de spam integrado, você deve ter um dos seguintes clientes com suporte.

Outlook clássico no Windows Versão 2307 (Build 16626.10000) ou posterior. Você deve ingressar no programa Do Microsoft 365 Insider e selecionar a opção Canal Beta para acessar builds beta do Office.
Outlook no Mac Versão 16.81.1217.0 ou posterior. Você deve ingressar no programa Do Microsoft 365 Insider e selecionar a opção Canal Beta para acessar builds beta do Office.

Observação

O suporte de visualização para o recurso integrado de relatório de spam no Outlook na Web e novo Outlook no Windows (versão prévia) está sendo implantado no momento. Depois de estar disponível para visualização, você deve configurar a versão direcionada no locatário do Microsoft 365 para acessar builds beta do Office.

Dica

Se você não conseguir escolher um canal no cliente do Outlook no Windows, consulte Permitir que os usuários escolham qual canal do Microsoft 365 Insider instalar em dispositivos Windows.

Configurar seu ambiente

Dica

Para experimentar imediatamente uma solução completa de suplemento de relatório de spam, consulte o exemplo De relatório de spam ou phishing no Outlook (versão prévia ).

Conclua o início rápido do Outlook, que cria um projeto de suplemento com o gerador Yeoman para suplementos do Office.

Configurar o manifesto

Observação

Ainda não há suporte para relatórios de spam integrados para o manifesto unificado do Microsoft 365.

Para implementar o recurso de relatório de spam integrado em seu suplemento, você deve configurar o nó VersionOverridesV1_1 do manifesto de acordo.

No Outlook na Web e no Mac e no novo Outlook no Windows, um suplemento que implementa o recurso integrado de relatório de spam é executado em um runtime do navegador. Você deve especificar o arquivo HTML que faz referência ou contém o código para lidar com o evento de relatório de spam no resid atributo do elemento Runtime .
No Outlook clássico no Windows, um suplemento que implementa o recurso de relatório de spam integrado é executado em um runtime somente JavaScript. Como tal, você deve especificar o arquivo JavaScript que contém o código para lidar com o evento de relatório de spam no elemento Substituir filho do <elemento Runtime> .
Para ativar o suplemento na faixa de opções do Outlook e impedir que ele apareça no final da faixa de opções ou na seção de estouro, defina o xsi:type atributo do <elemento ExtensionPoint> como ReportPhishingCommandSurface.
Para personalizar o botão de faixa de opções e a caixa de diálogo de pré-processamento, você deve definir o nó ReportPhishingCustomization .
- Um usuário relata uma mensagem não solicitada por meio do botão do suplemento na faixa de opções. Para configurar o botão faixa de opções, defina o xsi:type atributo do elemento Control como Button. Em seguida, defina o xsi:type atributo do elemento Action child como ExecuteFunction e especifique o nome do manipulador de eventos de relatório de spam em seu <elemento filho FunctionName> . Um suplemento de relatório de spam só pode implementar comandos de função.
  
  Veja a seguir um exemplo de como o botão de um suplemento de relatório de spam aparece na faixa de opções do cliente do Outlook no Windows. A interface do usuário da faixa de opções pode variar dependendo da plataforma em que o cliente do Outlook do usuário está em execução.
- A caixa de diálogo de pré-processamento é mostrada a um usuário quando ele seleciona o botão de suplemento. Ele é configurado por meio do elemento PreProcessingDialog do manifesto. Embora a caixa de diálogo precise ter um título e uma descrição, você pode incluir opcionalmente os seguintes elementos.
  - Uma lista de várias opções de seleção para ajudar um usuário a identificar o tipo de mensagem que está relatando. Para saber como configurar essas opções de relatório, consulte Elemento ReportingOptions.
  - Uma caixa de texto para o usuário fornecer informações adicionais sobre a mensagem que está relatando. Para saber como implementar uma caixa de texto, consulte Elemento FreeTextLabel.
  - Texto e URL personalizados para fornecer recursos informativos ao usuário. Para saber como personalizar esses elementos, confira Elemento MoreInfo.
  Quando um usuário seleciona Relatório na caixa de diálogo, o evento SpamReporting é ativado e, em seguida, é manipulado pelo manipulador de eventos JavaScript.
  
  A seguir está um exemplo de uma caixa de diálogo de pré-processamento no Outlook no Windows. Observe que a aparência da caixa de diálogo pode variar dependendo da plataforma em que o cliente do Outlook do usuário está em execução.

A seguir está um exemplo de um <nó VersionOverrides> configurado para relatórios de spam.

No editor de código preferencial, abra o projeto de suplemento que você criou.
Abra o arquivo manifest.xml localizado na raiz do projeto.

Selecione o nó VersionOverrides> inteiro< (incluindo as marcas abertas e fechadas) e substitua-o pelo código a seguir.

<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.13">
        <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="To learn more about reporting unsolicited messages, see "/>
        <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>

Salve suas alterações.

Implementar o manipulador de eventos

Quando o suplemento é usado para relatar uma mensagem, ele gera um evento SpamReporting , que é processado pelo manipulador de eventos no arquivo JavaScript do suplemento. Para mapear o nome do manipulador de eventos especificado no <elemento FunctionName> do manifesto para seu equivalente JavaScript, você deve chamar Office.actions.associate em seu código.

Em seu projeto de suplemento, navegue até o diretório ./src . Em seguida, crie uma nova pasta chamada spamreporting.
Na pasta ./src/spamreporting , crie um novo arquivo chamado spamreporting.js.

Abra o arquivo spamreporting.js recém-criado e adicione o código JavaScript a seguir.

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

Salve suas alterações.

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

O manipulador de eventos é responsável por processar a mensagem relatada. Você pode configurá-la para encaminhar informações, como uma cópia da mensagem ou as opções selecionadas pelo usuário na caixa de diálogo de pré-processamento, para um sistema interno para investigação posterior.

Para enviar eficientemente uma cópia da mensagem relatada, chame o método getAsFileAsync no manipulador de eventos. Isso obtém o formato EML codificado por Base64 de uma mensagem, que você pode encaminhar para o sistema interno.

Importante

Para testar o getAsFileAsync método enquanto ele ainda está em versão prévia no Outlook no Windows, você deve configurar o registro do computador.

O Outlook no Windows inclui uma cópia local das versões beta e de produção de Office.js em vez de carregar da CDN (rede de entrega de conteúdo). Por padrão, a cópia de produção local da API é referenciada. Para fazer referência à cópia beta local da API, você deve configurar o registro do computador da seguinte maneira:

No registro, navegue até HKEY_CURRENT_USER\SOFTWARE\Microsoft\Office\16.0\Outlook\Options\WebExt\Developer. Se a chave não existir, crie-a.
Create uma entrada nomeada EnableBetaAPIsInJavaScript e defina seu valor como 1.

Se você precisar acompanhar as respostas do usuário para as opções e a 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 essas propriedades, consulte Office.SpamReportingEventArgs.

A seguir está um exemplo de um manipulador de eventos de relatório de spam que chama o getAsFileAsync método e obtém as respostas do usuário do SpamReporting objeto de evento.

No arquivospamreporting.js , substitua seu conteúdo pelo código a seguir.

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

Salve suas alterações.

Observação

Para configurar o SSO (logon único) ou o CORS (compartilhamento de recursos de origem cruzada) no suplemento de relatório de spam, você deve adicionar seu suplemento e seu arquivo JavaScript a um URI bem conhecido. Para obter diretrizes sobre como configurar esse recurso, consulte Usar o SSO (logon único) ou o CORS (compartilhamento de recursos de origem cruzada) no suplemento do Outlook baseado em eventos ou spam.

Sinalizar quando o evento tiver sido processado

Depois que o manipulador de eventos concluir o processamento da mensagem, ele deve chamar o método event.completed . Além de sinalizar para o suplemento que o evento de relatório de spam foi processado, event.completed também pode ser usado para personalizar uma caixa de diálogo pós-processamento para mostrar ao usuário ou executar operações adicionais na mensagem, como excluí-la da caixa de entrada. Para obter uma lista de propriedades que você pode incluir em um objeto JSON para passar 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.

No arquivospamreporting.js , substitua seu conteúdo pelo código a seguir.

// 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 você estiver no Outlook clássico no Windows Versão 2308 (Build 16724.10000) ou posterior, Outlook no Mac, Outlook na Web ou novo Outlook no Windows (versão prévia), você deve usar a moveItemTo propriedade na event.completed chamada para especificar a pasta para a qual uma mensagem relatada é movida depois de processada pelo suplemento. Em builds anteriores do Outlook no Windows que dão suporte ao recurso de relatório de spam integrado, você deve usar a postProcessingAction propriedade.

Salve suas alterações.

A seguir está uma caixa de diálogo pós-processamento de exemplo mostrada ao usuário depois que o suplemento concluir o processamento de uma mensagem relatada no Outlook no Windows. Observe que a aparência da caixa de diálogo pode variar dependendo da plataforma em que o cliente do Outlook do usuário está em execução.

Um exemplo de uma caixa de diálogo pós-processamento mostrada depois que uma mensagem de spam relatada foi processada pelo suplemento.

Dica

À medida que você desenvolve um suplemento de relatório de spam que será executado no Outlook no Windows, tenha o seguinte em mente.

No momento, não há suporte para importações no arquivo JavaScript que contém o código para lidar com o evento de relatório de spam.
O código incluído nas Office.onReady() funções e Office.initialize não será executado. Você deve adicionar qualquer lógica de inicialização de suplemento, como verificar a versão do Outlook do usuário, aos manipuladores de eventos.

Atualizar o arquivo HTML de comandos

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

Imediatamente antes da marca de cabeça de fechamento (</head>), substitua a entrada de script existente pelo código a seguir.

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

Salve suas alterações.

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

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

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

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

Salve suas alterações.

Testar e validar seu suplemento

Carregar de lado o suplemento em um cliente do Outlook com suporte.
Escolha uma mensagem na caixa de entrada e selecione o botão do suplemento na faixa de opções.
Na caixa de diálogo de pré-processamento, escolha um motivo para relatar a mensagem e adicione informações sobre a mensagem, se configurada. Em seguida, selecione Relatório.
(Opcional) Na caixa de diálogo pós-processamento, selecione OK.

Examinar o comportamento e as limitações do recurso

À medida que você desenvolve e testa o recurso integrado de relatório de spam em seu suplemento, esteja atento às suas características e limitações.

Um suplemento de relatório de spam pode ser executado por no máximo cinco minutos depois de ativado. Qualquer processamento que ocorra além de cinco minutos fará com que o suplemento tenha um tempo limite. Se o suplemento sair, uma caixa de diálogo será mostrada ao usuário para notificá-los disso.
Um suplemento de relatório de spam pode ser usado para relatar uma mensagem mesmo que o Painel de Leitura do cliente do Outlook esteja desativado. No entanto, isso não tem suporte no Outlook no Mac. No Outlook no Mac, o Painel de Leitura deve ser ativado para usar um suplemento de relatório de spam.
No Outlook clássico no Windows, apenas uma mensagem pode ser relatada por vez. Se um usuário tentar relatar outra mensagem enquanto a anterior ainda estiver sendo processada, uma caixa de diálogo será mostrada a eles para notificá-las disso.

Isso não se aplica ao Outlook no Mac ou na Web ou ao novo Outlook no Windows (versão prévia). Nesses clientes do Outlook, um usuário pode relatar uma mensagem do Painel de Leitura e pode relatar simultaneamente cada mensagem aberta em uma janela separada.
O suplemento ainda pode processar a mensagem relatada mesmo que o usuário navegue para longe da mensagem selecionada. No Outlook no Mac, isso só terá suporte se um usuário relatar uma mensagem enquanto ela estiver aberta em uma janela separada. Se o usuário relatar uma mensagem ao exibi-la do Painel de Leitura e, em seguida, navegar para longe dela, o processo de relatório será encerrado.
Os botões que aparecem nas caixas de diálogo pré-processamento e pós-processamento não são personalizáveis. Além disso, os botões e texto nas caixas de diálogo de relatório de tempo limite e em andamento não podem ser modificados.
Os recursos integrados de relatório de spam e ativação baseados em eventos devem usar o mesmo runtime. No momento, não há suporte para vários runtimes no Outlook. Para saber mais sobre runtimes, confira Runtimes em Suplementos do Office.
Um comando do painel de tarefas não pode ser atribuído ao botão de relatório de spam na faixa de opções. Se você quiser implementar um painel de tarefas no suplemento, deverá incluir o elemento Action no manifesto e definir seu xsi:type atributo como ShowTaskpane. Observe que um botão separado para ativar o painel de tarefas será adicionado à faixa de opções, mas ele não aparecerá na área dedicada de relatório de spam da faixa de opções.

Solucionar problemas do suplemento

À medida que você desenvolve seu suplemento de relatório de spam, talvez seja necessário solucionar problemas, como o suplemento que não está carregando. Para obter diretrizes sobre como solucionar problemas de um suplemento de relatório de spam, consulte Solucionar problemas de suplementos baseados em eventos e de relatório de spam.

Share via

Implementar um suplemento integrado de relatório de spam (versão prévia)

Visualizar o recurso de relatório de spam integrado

Configurar seu ambiente

Configurar o manifesto

Implementar o manipulador de eventos

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

Sinalizar quando o evento tiver sido processado

Atualizar o arquivo HTML de comandos

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

Testar e validar seu suplemento

Examinar o comportamento e as limitações do recurso

Solucionar problemas do suplemento

Confira também

Comentários

Recursos adicionais