Partilhar 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 Com suporte
Outlook clássico no Windows
Versão 2404 (Compilação 17530.15000)		 Com suporte
Outlook no Mac
Versão 16.81 (23121700) 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

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.

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

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

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

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

Observação

A implementação de relatórios de spam integrados com o manifesto unificado para o Microsoft 365 está em pré-visualização do programador público. Atualmente, só está disponível para utilização no Outlook clássico no Windows. Isto não deve ser utilizado em suplementos de produção. Convidamo-lo a experimentá-lo em ambientes de teste ou de desenvolvimento. Para obter mais informações, veja o esquema de manifesto da aplicação de pré-visualização do programador público.

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

  2. Abra o ficheiro manifest.json .

  3. Adicione o seguinte objeto à matriz "extensions.runtimes". Observe o seguinte sobre esta marcação.

    • A "minVersion" do conjunto de requisitos da Caixa de Correio está configurada para "1.14". Esta é a versão mais baixa do conjunto de requisitos que suporta a funcionalidade de relatórios de spam integrada.
    • O "ID" do runtime está definido como um nome descritivo exclusivo, "spam_reporting_runtime".
    • A propriedade "code" tem uma propriedade "page" subordinada definida como um ficheiro HTML e uma propriedade "script" subordinada que está definida como um ficheiro JavaScript. Irá criar ou editar estes ficheiros em passos posteriores.
    • A propriedade "lifetime" está definida como "short". Isto significa que o runtime começa quando o SpamReporting evento ocorre e é encerrado quando o processador de eventos é concluído.
    • O objeto "actions" especifica a função do processador de eventos que é executada no runtime. Irá criar esta função num passo posterior.
    {
    "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. Adicione o seguinte objeto à matriz "extensions.ribbons". Observe o seguinte sobre esta marcação.

    • A matriz "contexts" contém a cadeia "spamReportingOverride". Isto impede que o botão de suplemento apareça no final do friso ou na secção de capacidade excedida.
    • A matriz "fixedControls" contém um objeto que configura o aspeto e a funcionalidade do botão de suplemento no friso. O nome do processador de eventos especificado na propriedade "actionId" tem de corresponder ao valor utilizado na propriedade "id" do objeto na matriz "actions". Embora a propriedade "ativada" tenha de ser especificada na matriz, o respetivo valor não afeta a funcionalidade de um suplemento de relatórios de spam.
    • O objeto "spamPreProcessingDialog" especifica as informações e opções apresentadas na caixa de diálogo de pré-processamento. Embora tenha de especificar um "título" e uma "descrição" para a caixa de diálogo, pode, opcionalmente, configurar as seguintes propriedades.
      • O objeto "spamReportingOptions". Fornece uma lista de seleção múltipla de até cinco opções. Isto ajuda um utilizador a identificar o tipo de mensagem que está a comunicar.
      • A propriedade "spamFreeTextSectionTitle". Fornece uma caixa de texto para o utilizador adicionar mais informações sobre a mensagem que está a comunicar.
      • O objeto "spamMoreInfo". Inclui uma ligação na caixa de diálogo para fornecer recursos informativos ao utilizador.
    {
    "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. Salve suas alterações.

Dica

Para saber mais sobre manifestos para suplementos do Outlook, consulte Manifesto de Suplementos do Office.

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.

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

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.

  • 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 integrado de exemplo que substitui o botão Relatório no friso do Outlook.

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

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

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

    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