Share via

Implementación de la activación basada en eventos en complementos móviles de Outlook

  • Artículo

Con la característica de activación basada en eventos, desarrolle un complemento para activar y completar automáticamente las operaciones cuando se produzcan determinados eventos en Outlook en Android o en iOS, como la composición de un mensaje nuevo.

En las secciones siguientes se explica cómo desarrollar un complemento móvil de Outlook que agrega automáticamente una firma a los nuevos mensajes que se componen. Esto resalta un escenario de ejemplo de cómo puede implementar la activación basada en eventos en el complemento móvil. Mejore significativamente la experiencia del usuario móvil mediante la exploración de otros escenarios en el complemento hoy en día.

Para obtener información sobre cómo implementar un complemento basado en eventos para Outlook en Windows (clásico y nuevo (versión preliminar),en Mac y en la web, vea Configurar el complemento de Outlook para la activación basada en eventos.

Nota:

Outlook en Android y en iOS solo admite hasta el conjunto de requisitos de buzón 1.5. Sin embargo, para admitir la característica de activación basada en eventos, algunas API de conjuntos de requisitos posteriores se han habilitado en clientes móviles. Para obtener más información sobre esta excepción, consulte API admitidas adicionales.

Clientes compatibles

El complemento que desarrolle en este tutorial se admite en Outlook en Android y en iOS a partir de la versión 4.2352.0. Debe tener una suscripción a Microsoft 365 para ejecutar la característica.

Configurar el entorno

Complete el inicio rápido de Outlook en el que crea un proyecto de complemento con el generador de Yeoman para complementos de Office.

Configuración del manifiesto

Los pasos para configurar el manifiesto dependen del tipo de manifiesto seleccionado en el inicio rápido.

  1. Configure la propiedad "extensions.runtimes" tal como lo haría para configurar un comando de función. Para obtener más información, consulte Configuración del tiempo de ejecución para el comando de función.

  2. En la matriz "extensions.ribbons.contexts", agregue mailRead como elemento. Cuando haya terminado, la matriz debería tener un aspecto similar al siguiente.

    "contexts": [
    "mailRead"
],

  3. En la matriz "extensions.ribbons.requirements.formFactors", agregue "mobile" como elemento. Cuando haya terminado, la matriz debería tener un aspecto similar al siguiente.

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

  4. Agregue la siguiente matriz "autoRunEvents" como propiedad del objeto en la matriz "extensiones".

    "autoRunEvents": [

]

  5. Agregue un objeto como el siguiente a la matriz "autoRunEvents". Tenga en cuenta lo siguiente en relación con este código:

    • La propiedad "events" asigna controladores a eventos.
    • El "events.type" debe ser uno de los tipos enumerados en Eventos admitidos.
    • El valor de "events.actionId" es el nombre de una función que se crea en Implementar el controlador de eventos.
    • Puede tener más de un objeto en la matriz "events".
      {
      "requirements": {
          "capabilities": [
              {
                  "name": "Mailbox",
                  "minVersion": "1.10"
              }
          ],
          "scopes": [
              "mail"
          ]
      },
      "events": [
          {
              "type": "newMessageComposeCreated",
              "actionId": "onNewMessageComposeHandler"
          },
      ]
  }

Sugerencia

Para obtener más información sobre los manifiestos para complementos de Outlook, vea Manifiesto de complementos de Office y Agregar compatibilidad con comandos de complementos en Outlook en dispositivos móviles.

Implementar el controlador de eventos

Para permitir que el complemento complete tareas cuando se produzca el OnNewMessageCompose evento, debe implementar un controlador de eventos de JavaScript. En esta sección, creará la onNewMessageComposeHandler función que agrega una firma a un nuevo mensaje que se va a componer y, a continuación, muestra un mensaje para notificar que se agregó la firma.

  1. Desde el mismo proyecto de inicio rápido, vaya al directorio ./src y cree una nueva carpeta denominada launchevent.

  2. En la carpeta ./src/launchevent , cree un nuevo archivo denominado launchevent.js.

  3. Abra el archivo launchevent.js que creó y agregue el siguiente 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. Guarde los cambios.

Agregar una referencia al archivo JavaScript de control de eventos

Asegúrese de que el archivo ./src/commands/commands.html tiene una referencia al archivo JavaScript que contiene el controlador de eventos.

  1. Vaya a la carpeta ./src/commands y abra commands.html.

  2. Inmediatamente antes de la etiqueta principal de cierre (</head>), agregue una entrada de script para el archivo JavaScript que contiene el controlador de eventos.

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

  3. Guarde los cambios.

Prueba y validación del complemento

  1. Siga las instrucciones para probar y validar el complemento.

  2. Transferir localmente el complemento en Outlook en Windows (clásico o nuevo (versión preliminar), en Mac o en la web.

  3. Abra Outlook en Android o en iOS. Si ya tiene Outlook abierto en el dispositivo, reinícielo.

  4. Create un mensaje nuevo. El complemento basado en eventos agrega la firma al mensaje. Si tiene una firma guardada en el dispositivo móvil, aparecerá brevemente en el mensaje que cree, pero se reemplazará inmediatamente por la firma agregada por el complemento.

    Una firma de ejemplo agregada a un mensaje que se va a componer en Outlook Mobile.

Comportamiento y limitaciones

A medida que desarrolle un complemento basado en eventos para Outlook mobile, tenga en cuenta los siguientes comportamientos y limitaciones de las características.

  • En este momento, solo se admite el OnNewMessageCompose evento en Outlook Mobile. Este evento se produce cuando se crea un nuevo mensaje (incluida la respuesta, responder todo y reenviar). El OnNewMessageCompose evento no se produce cuando se edita un borrador existente.
  • Dado que se espera que los complementos basados en eventos sean de ejecución corta y ligera, se permite que un complemento se ejecute durante un máximo de 60 segundos desde el momento en que se activa. Para indicar que el complemento ha completado el procesamiento de un evento, el controlador de eventos debe llamar al método event.completed . La operación del complemento también finaliza cuando el usuario cierra la ventana de redacción o envía el mensaje.
  • Solo se puede ejecutar un complemento a la vez. Si se instalan varios complementos basados en eventos en la cuenta de un usuario, se ejecutarán secuencialmente.
  • Si pulsa y mantiene presionado el icono de Outlook en el dispositivo móvil y, a continuación, selecciona Nuevo correo para crear un mensaje nuevo, el complemento basado en eventos puede tardar unos segundos en inicializarse y completar el procesamiento del evento.
  • Si no se realiza ningún cambio en un nuevo mensaje que se está redactando, no se guardará un borrador, incluso si el complemento basado en eventos agrega una firma mediante el método Office.context.mailbox.item.body.setSignatureAsync .
  • En un complemento basado en eventos que administra firmas, si selecciona Responder en la parte inferior de un mensaje, el complemento se activa y agrega la firma al mensaje. Sin embargo, la firma no estará visible en la vista actual. Para ver el mensaje con la firma agregada, expanda la ventana de redacción a pantalla completa.
  • Para mejorar la funcionalidad del complemento, puede usar las API admitidas de conjuntos de requisitos posteriores en modo de redacción. Para obtener más información, consulte API admitidas adicionales.

API admitidas adicionales

Aunque Outlook mobile admite API hasta el conjunto de requisitos de buzón 1.5, para ampliar aún más la funcionalidad del complemento basado en eventos en Outlook Mobile, ahora se admiten API adicionales de conjuntos de requisitos posteriores en modo de redacción.

Para obtener más información sobre las API que se admiten en Outlook en dispositivos móviles, consulte API de JavaScript de Outlook compatibles con Outlook en dispositivos móviles.

Implementación en usuarios

El administrador de una organización debe implementar complementos basados en eventos. Para obtener instrucciones sobre cómo implementar el complemento a través de la Centro de administración de Microsoft 365, vea la sección "Implementar en los usuarios" de Configuración del complemento de Outlook para la activación basada en eventos.

Consulte también