Compartir a través de

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 explorando otros escenarios y eventos admitidos en el complemento hoy en día.

Para obtener información sobre cómo implementar un complemento basado en eventos para Outlook en la Web, en Windows (nuevo y clásico) y en Mac, consulte Configuración del 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.

Eventos y clientes admitidos

Nombre canónico del evento y nombre de manifiesto de solo complemento Manifiesto de aplicación unificada para el nombre de Microsoft 365 Descripción Clientes compatibles
OnNewMessageCompose newMessageComposeCreated Se produce al redactar un nuevo mensaje (incluye la respuesta, responder a todos y reenviar), pero no al editar un borrador.
  • Android (versión 4.2352.0)
  • iOS (versión 4.2352.0)
OnMessageRecipientsChanged messageRecipientsChanged Se produce al agregar o quitar destinatarios al redactar un mensaje.

Objeto de datos específico del evento: RecipientsChangedEventArgs
  • Android (versión 4.2425.0)
  • iOS (versión 4.2425.0)

Configurar el entorno

Para ejecutar la característica, debe tener una versión compatible de Outlook en Android o en iOS (consulte Eventos y clientes admitidos) y una suscripción de Microsoft 365. A continuación, complete el inicio rápido de Outlook en el que creará 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.

Nota:

Al desarrollar un complemento basado en eventos para ejecutarlo en Outlook en Android y en iOS, tenga en cuenta que el manifiesto de aplicación unificado para Microsoft 365 solo se puede usar si el complemento controla determinados eventos. Para obtener información sobre qué eventos se admiten, consulte Eventos y clientes admitidos.

  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:

      {
      "requirements": {
          "capabilities": [
              {
                  "name": "Mailbox",
                  "minVersion": "1.5"
              }
          ],
          "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 (nuevo o clásico), 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. Cree un nuevo mensaje. 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.

  • 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, seleccione Nuevo correo para crear un nuevo mensaje, un complemento basado en eventos que controla el OnNewMessageCompose evento puede tardar unos segundos en inicializarse y completar el procesamiento del evento.
  • Cuando se usa un complemento basado en eventos que controla el OnNewMessageCompose evento, si no se realizan cambios en un nuevo mensaje que se está redactando, no se guardará un borrador. Esto se aplica incluso si el complemento agrega una firma mediante el método Office.context.mailbox.item.body.setSignatureAsync .
  • En un complemento basado en eventos que administra firmas cuando se produce el OnNewMessageCompose evento, 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.

Vea también