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

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

As seções a seguir orientam você sobre como desenvolver um suplemento móvel do Outlook que adiciona automaticamente uma assinatura às novas mensagens que estão sendo redigidas. Isso destaca um cenário de exemplo de como você pode implementar a ativação baseada em eventos em seu suplemento móvel. Melhore significativamente a experiência do usuário móvel explorando outros cenários e eventos com suporte em seu suplemento hoje.

Para saber como implementar um suplemento baseado em eventos para o Outlook na Web, no Windows (novo e clássico) e no Mac, confira Ativar suplementos com eventos.

Eventos e clientes com suporte

Configurar seu ambiente

Para executar o recurso, você deve ter uma versão compatível do Outlook no Android ou no iOS (consulte Eventos e clientes compatíveis) e uma assinatura do Microsoft 365. Em seguida, conclua o início rápido do Outlook , no qual você cria um projeto de suplemento com o gerador Yeoman para Suplementos do Office.

Configurar o manifesto

As etapas para configurar o manifesto dependem do tipo de manifesto selecionado no início rápido.

Implementar o manipulador de eventos

Para permitir que seu suplemento conclua tarefas quando o OnNewMessageCompose evento ocorrer, você deve implementar um manipulador de eventos JavaScript. Nesta seção, você criará a onNewMessageComposeHandler função que adiciona uma assinatura a uma nova mensagem que está sendo redigida e, em seguida, mostra uma mensagem para notificar que a assinatura foi adicionada.

1. No mesmo projeto de início rápido, navegue até o diretório ./src e crie uma nova pasta chamada launchevent.

2. Na pasta ./src/launchevent , crie um novo arquivo chamado launchevent.js.

3. Abra o arquivo launchevent.js que você 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.
                   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 arquivo JavaScript de manipulação de eventos

Certifique-se de que o arquivo ./src/commands/commands.html tenha uma referência ao arquivo JavaScript que contém o manipulador de eventos.

1. Navegue até a pasta ./src/commands e abra commands.html.

2. Imediatamente antes da tag head de fechamento (</head>), adicione uma entrada de script para o arquivo JavaScript que contém o manipulador de eventos.

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

3. Salve suas alterações.

Testar e validar seu suplemento

1. Siga as diretrizes para testar e validar seu suplemento.

2. Sideload 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 você já tiver o Outlook aberto em seu dispositivo, reinicie-o.

4. Crie uma nova mensagem. O suplemento baseado em evento adiciona a assinatura à mensagem. Se você tiver uma assinatura salva em seu dispositivo móvel, ela aparecerá brevemente na mensagem que você criar, mas será imediatamente substituída pela assinatura adicionada pelo suplemento.

   

Comportamento e limitações

Ao desenvolver um suplemento baseado em eventos para o Outlook mobile, lembre-se dos seguintes comportamentos e limitações de recursos.

• Como se espera que os suplementos baseados em eventos sejam de curta execução e leves, um suplemento pode ser executado por no máximo 60 segundos a partir do momento em que é ativado. Para sinalizar que o suplemento concluiu o processamento de um evento, o manipulador de eventos deve chamar o método event.completed . A operação do suplemento também termina quando o usuário fecha a janela de redação ou envia a mensagem.
• Somente um suplemento pode ser executado por vez. Se vários suplementos baseados em eventos estiverem instalados na conta de um usuário, eles serão executados sequencialmente.
• Se você tocar e segurar o ícone do Outlook em seu dispositivo móvel e selecionar Novo email para criar uma nova mensagem, um suplemento baseado em evento que lida com o OnNewMessageCompose evento pode levar alguns segundos para inicializar e concluir o processamento do evento.
• O OnNewMessageCompose evento não ocorre quando uma nova mensagem é criada usando a opção Compartilhar no iOS.
• Ao usar um suplemento baseado em evento que manipula o OnNewMessageCompose evento, se não houver alterações feitas em uma nova mensagem sendo composta, um rascunho não será salvo. Isso se aplica mesmo se o suplemento adicionar uma assinatura usando o método Office.context.mailbox.item.body.setSignatureAsync .
• Em um suplemento baseado em evento que gerencia assinaturas quando o OnNewMessageCompose evento ocorre, se você selecionar Responder na parte inferior de uma mensagem, o suplemento será ativado e adicionará a assinatura à mensagem. No entanto, a assinatura não será visível no modo de exibição atual. Para exibir sua mensagem com a assinatura adicionada, expanda a janela de redação para tela inteira.
• Para aprimorar a funcionalidade do suplemento, você pode usar APIs com suporte de conjuntos de requisitos posteriores no modo de redação. Para obter mais informações, consulte APIs adicionais com suporte.

APIs adicionais com suporte

Embora o Outlook Mobile dê suporte a APIs até o conjunto de requisitos de Caixa de correio 1.5, para estender ainda mais a funcionalidade do seu suplemento baseado em eventos no Outlook mobile, APIs adicionais de conjuntos de requisitos posteriores agora têm suporte no modo de redação.

• Office.context.mailbox.item.addFileAttachmentFromBase64Async
• Office.context.mailbox.item.disableClientSignatureAsync
• Office.context.mailbox.item.from.getAsync
• Office.context.mailbox.item.getComposeTypeAsync
• Office.context.mailbox.item.body.setSignatureAsync
• Office.context.mailbox.item.sessionData

Para saber mais sobre as APIs com suporte no Outlook em dispositivos móveis, confira APIs JavaScript com suporte no Outlook em dispositivos móveis.

Implantar para usuários

Para obter diretrizes sobre como implantar seu suplemento baseado em eventos, consulte a seção "Implantar seu suplemento" de Ativar suplementos com eventos.

Confira também

• Ativar suplementos com eventos
• Suplementos para o Outlook em dispositivos móveis
• Adicionar suporte móvel a um suplemento do Outlook
• APIs JavaScript do Outlook com suporte no Outlook em dispositivos móveis