Compartilhar via

Implementar a ativação baseada em eventos nos suplementos móveis do Outlook

  • Artigo

Com a funcionalidade de ativação baseada em eventos , desenvolva um suplemento para ativar e concluir automaticamente operações quando determinados eventos ocorrem no Outlook no Android ou no iOS, como compor uma nova mensagem.

As secções seguintes explicam como desenvolver um suplemento móvel do Outlook que adiciona automaticamente uma assinatura às novas mensagens que estão a ser compostas. Isto realça um cenário de exemplo de como pode implementar a ativação baseada em eventos no seu suplemento móvel. Melhore significativamente a experiência do utilizador móvel ao explorar outros cenários e eventos suportados no seu suplemento atualmente.

Para saber como implementar um suplemento baseado em eventos para Outlook na Web, no Windows (novo e clássico) e no Mac, consulte Configurar o seu suplemento do Outlook para ativação baseada em eventos.

Observação

O Outlook no Android e no iOS só suporta o requisito de Caixa de Correio definido como 1.5. No entanto, para suportar a funcionalidade de ativação baseada em eventos, algumas APIs de conjuntos de requisitos posteriores foram ativadas em clientes móveis. Para obter mais informações sobre esta exceção, veja APIs suportadas adicionais.

Eventos e clientes suportados

Nome canónico do evento e nome de manifesto apenas do suplemento Manifesto de aplicação unificada para o nome do Microsoft 365 Descrição Clientes com suporte
OnNewMessageCompose newMessageComposeCreated Ocorre ao compor uma nova mensagem (inclui responder, responder a todos e reencaminhar), mas não ao editar um rascunho.
  • Android (Versão 4.2352.0)
  • iOS (Versão 4.2352.0)
OnMessageRecipientsChanged messageRecipientsChanged Ocorre ao adicionar ou remover destinatários ao compor uma mensagem.

Objeto de dados específico do evento: DestinatáriosChangedEventArgs
  • Android (Versão 4.2425.0)
  • iOS (Versão 4.2425.0)

Configurar seu ambiente

Para executar a funcionalidade, tem de ter uma versão suportada do Outlook no Android ou no iOS (consulte Eventos e clientes suportados) e uma subscrição do Microsoft 365. Em seguida, conclua o guia de introdução do Outlook no qual cria um projeto de suplemento com o gerador Yeoman para Suplementos do Office.

Configurar o manifesto

Os passos para configurar o manifesto dependem do tipo de manifesto que selecionou no início rápido.

Observação

Ao desenvolver um suplemento baseado em eventos para ser executado no Outlook no Android e no iOS, tenha em atenção que o manifesto de aplicação unificada para o Microsoft 365 só pode ser utilizado se o suplemento processar determinados eventos. Para saber que eventos são suportados, veja Eventos e clientes suportados.

  1. Configure a propriedade "extensions.runtimes", tal como faria para configurar um comando de função. Para obter detalhes, veja Configurar o runtime para o comando de função.

  2. Na matriz "extensions.ribbons.contexts", adicione mailRead como um item. Quando tiver terminado, a matriz deverá ter o seguinte aspeto.

    "contexts": [
    "mailRead"
],

  3. Na matriz "extensions.ribbons.requirements.formFactors", adicione "mobile" como um item. Quando tiver terminado, a matriz deverá ter o seguinte aspeto.

    "formFactors": [
    "mobile",
    <!-- Typically there will be other form factors listed. -->
]

  4. Adicione a seguinte matriz "autoRunEvents" como uma propriedade do objeto na matriz "extensions".

    "autoRunEvents": [

]

  5. Adicione um objeto como o seguinte à matriz "autoRunEvents". Observe o seguinte sobre este código:

      {
      "requirements": {
          "capabilities": [
              {
                  "name": "Mailbox",
                  "minVersion": "1.5"
              }
          ],
          "scopes": [
              "mail"
          ]
      },
      "events": [
          {
              "type": "newMessageComposeCreated",
              "actionId": "onNewMessageComposeHandler"
          },
      ]
  }

Dica

Para saber mais sobre manifestos para suplementos do Outlook, consulte Manifesto de Suplementos do Office e Adicionar suporte para comandos de suplementos no Outlook em dispositivos móveis.

Implementar o manipulador de eventos

Para permitir que o suplemento conclua tarefas quando o OnNewMessageCompose evento ocorre, tem de implementar um processador de eventos JavaScript. Nesta secção, irá criar a onNewMessageComposeHandler função que adiciona uma assinatura a uma nova mensagem que está a ser composta e, em seguida, mostra uma mensagem para notificar que a assinatura foi adicionada.

  1. A partir do mesmo projeto de início rápido, navegue para o diretório ./src e, em seguida, crie uma nova pasta com o nome launchevent.

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

  3. Abra o ficheirolaunchevent.js que criou e adicione o seguinte código JavaScript.

    /*
* Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
* See LICENSE in the project root for license information.
*/

// Add start-up logic code here, if any.
Office.onReady();

function onNewMessageComposeHandler(event) {
    const item = Office.context.mailbox.item;
    const signatureIcon = "iVBORw0KGgoAAAANSUhEUgAAACcAAAAnCAMAAAC7faEHAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAAAAzUExURQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAKMFRskAAAAQdFJOUwAQIDBAUGBwgI+fr7/P3+8jGoKKAAAACXBIWXMAAA7DAAAOwwHHb6hkAAABT0lEQVQ4T7XT2ZalIAwF0DAJhMH+/6+tJOQqot6X6joPiouNBo3w9/Hd6+hrYnUt6vhLcjEAJevVW0zJxABSlcunhERpjY+UKoNN5+ZgDGu2onNz0OngjP2FM1VdyBW1LtvGeYrBLs7U5I1PTXZt+zifcS3Icw2GcS3vxRY3Vn/iqx31hUyTnV515kdTfbaNhZLI30AceqDiIo4tyKEmJpKdP5M4um+nUwfDWxAXdzqMNKQ14jLdL5ntXzxcRF440mhS6yu882Kxa30RZcUIjTCJg7lscsR4VsMjfX9Q0Vuv/Wd3YosD1J4LuSRtaL7bzXGN1wx2cytUdncDuhA3fu6HPTiCvpQUIjZ3sCcHVbvLtbNTHlysx2w9/s27m9gEb+7CTri6hR1wcTf2gVf3wBRe3CMbcHYvTODkXhnD0+178K/pZ9+n/C1ru/2HAPwAo7YM1X4+tLMAAAAASUVORK5CYII=";

    // Get the sender's account information.
    item.from.getAsync((result) => {
        if (result.status === Office.AsyncResultStatus.Failed) {
            console.log(result.error.message);
            event.completed();
            return;
        }

        // Create a signature based on the sender's information.
        const name = result.value.displayName;
        const options = { asyncContext: name, isInline: true };
        item.addFileAttachmentFromBase64Async(signatureIcon, "signatureIcon.png", options, (result) => {
            if (result.status === Office.AsyncResultStatus.Failed) {
                console.log(result.error.message);
                event.completed();
                return;
            }

            // Add the created signature to the message.
            const signature = "<img src='cid:signatureIcon.png'>" + result.asyncContext;
            item.body.setSignatureAsync(signature, { coercionType: Office.CoercionType.Html }, (result) => {
                if (result.status === Office.AsyncResultStatus.Failed) {
                    console.log(result.error.message);
                    event.completed();
                    return;
                }

                // Show a notification when the signature is added to the message.
                // Important: Only the InformationalMessage type is supported in Outlook mobile at this time.
                const notification = {
                    type: Office.MailboxEnums.ItemNotificationMessageType.InformationalMessage,
                    message: "Company signature added.",
                    icon: "none",
                    persistent: false                        
                };
                item.notificationMessages.addAsync("signature_notification", notification, (result) => {
                    if (result.status === Office.AsyncResultStatus.Failed) {
                        console.log(result.error.message);
                        event.completed();
                        return;
                    }

                    event.completed();
                });
            });
        });
    });
}

  4. Salve suas alterações.

Adicionar uma referência ao ficheiro JavaScript de processamento de eventos

Certifique-se de que o ficheiro ./src/commands/commands.html tem uma referência ao ficheiro JavaScript que contém o processador de eventos.

  1. Navegue para a pasta ./src/commands e, em seguida, abra commands.html.

  2. Imediatamente antes da etiqueta principal de fecho (</head>), adicione uma entrada de script para o ficheiro JavaScript que contém o processador de eventos.

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

  3. Guarde as alterações.

Testar e validar o suplemento

  1. Siga a documentação de orientação para testar e validar o seu suplemento.

  2. Faça sideload do seu suplemento no Outlook no Windows (novo ou clássico), no Mac ou na Web.

  3. Abra o Outlook no Android ou no iOS. Se já tiver o Outlook aberto no seu dispositivo, reinicie-o.

  4. Criar uma nova mensagem. O suplemento baseado em eventos adiciona a assinatura à mensagem. Se tiver uma assinatura guardada no seu dispositivo móvel, esta será apresentada brevemente na mensagem que criar, mas será imediatamente substituída pela assinatura adicionada pelo suplemento.

    Uma assinatura de exemplo adicionada a uma mensagem que está a ser composta no Outlook Mobile.

Comportamento e limitações

À medida que desenvolve um suplemento baseado em eventos para o Outlook Mobile, tenha em atenção os seguintes comportamentos e limitações de funcionalidades.

  • Uma vez que se espera que os suplementos baseados em eventos sejam de execução curta e leves, é permitido executar um suplemento durante um máximo de 60 segundos a partir do momento em que é ativado. Para sinalizar que o suplemento concluiu o processamento de um evento, o processador de eventos tem de chamar o método event.completed . A operação de suplemento também termina quando o utilizador fecha a janela de composição ou envia a mensagem.
  • Apenas um suplemento pode ser executado de cada vez. Se forem instalados vários suplementos baseados em eventos na conta de um utilizador, serão executados sequencialmente.
  • Se tocar sem soltar no ícone do Outlook no seu dispositivo móvel, selecione Novo e-mail para criar uma nova mensagem, um suplemento baseado em eventos que processa o OnNewMessageCompose evento pode demorar alguns segundos a inicializar e concluir o processamento do evento.
  • Ao utilizar um suplemento baseado em eventos que processa o OnNewMessageCompose evento, se não forem efetuadas alterações a uma nova mensagem a ser composta, um rascunho não será guardado. Isto aplica-se mesmo que o suplemento adicione uma assinatura através do método Office.context.mailbox.item.body.setSignatureAsync .
  • Num suplemento baseado em eventos que gere assinaturas quando o OnNewMessageCompose evento ocorre, se selecionar Responder na parte inferior de uma mensagem, o suplemento é ativado e adiciona a assinatura à mensagem. No entanto, a assinatura não estará visível na vista atual. Para ver a sua mensagem com a assinatura adicionada, expanda a janela de composição para ecrã inteiro.
  • Para melhorar a funcionalidade do suplemento, pode utilizar APIs suportadas de conjuntos de requisitos posteriores no modo de composição. Para obter mais informações, veja APIs suportadas adicionais.

APIs suportadas adicionais

Embora o Outlook mobile suporte APIs até ao conjunto de requisitos da Caixa de Correio 1.5, para expandir ainda mais a capacidade do seu suplemento baseado em eventos no Outlook mobile, as APIs adicionais de conjuntos de requisitos posteriores são agora suportadas no modo de composição.

Para saber mais sobre as APIs suportadas no Outlook em dispositivos móveis, consulte ApIs JavaScript do Outlook suportadas no Outlook em dispositivos móveis.

Implementar em utilizadores

Os suplementos baseados em eventos têm de ser implementados pelo administrador de uma organização. Para obter orientações sobre como implementar o suplemento através do Centro de administração do Microsoft 365, consulte a secção "Implementar para utilizadores" em Configurar o suplemento do Outlook para ativação baseada em eventos.

Confira também