Partager via

Implémenter l’activation basée sur les événements dans les compléments mobiles Outlook

  • Article

Avec la fonctionnalité d’activation basée sur les événements , développez un complément pour activer et terminer automatiquement les opérations lorsque certains événements se produisent dans Outlook sur Android ou sur iOS, comme la composition d’un nouveau message.

Les sections suivantes vous guident tout au long du développement d’un complément outlook mobile qui ajoute automatiquement une signature aux nouveaux messages en cours de composition. Cela met en évidence un exemple de scénario de la façon dont vous pouvez implémenter l’activation basée sur les événements dans votre complément mobile. Améliorez considérablement l’expérience utilisateur mobile en explorant d’autres scénarios et événements pris en charge dans votre complément aujourd’hui.

Pour savoir comment implémenter un complément basé sur des événements pour Outlook sur le web, sur Windows (nouveau et classique) et sur Mac, voir Configurer votre complément Outlook pour l’activation basée sur les événements.

Remarque

Outlook sur Android et sur iOS prennent uniquement en charge jusqu’à l’ensemble de conditions requises de boîte aux lettres 1.5. Toutefois, pour prendre en charge la fonctionnalité d’activation basée sur les événements, certaines API des ensembles de conditions requises ultérieurs ont été activées sur les clients mobiles. Pour plus d’informations sur cette exception, consultez API supplémentaires prises en charge.

Événements et clients pris en charge

Nom canonique de l’événement et nom du manifeste du complément uniquement Manifeste d’application unifié pour nom Microsoft 365 Description Clients pris en charge
OnNewMessageCompose newMessageComposeCreated Se produit lors de la composition d’un nouveau message (y compris la réponse, la réponse et le transfert), mais pas lors de la modification d’un brouillon.
  • Android (version 4.2352.0)
  • iOS (version 4.2352.0)
OnMessageRecipientsChanged messageRecipientsChanged Se produit lors de l’ajout ou de la suppression de destinataires lors de la composition d’un message.

Objet de données spécifique à l’événement : RecipientsChangedEventArgs
  • Android (version 4.2425.0)
  • iOS (version 4.2425.0)

Configuration de votre environnement

Pour exécuter la fonctionnalité, vous devez disposer d’une version prise en charge d’Outlook sur Android ou sur iOS (voir Événements et clients pris en charge) et d’un abonnement Microsoft 365. Ensuite, suivez le guide de démarrage rapide Outlook dans lequel vous créez un projet de complément avec le générateur Yeoman pour les compléments Office.

Configurer le manifeste

Les étapes de configuration du manifeste dépendent du type de manifeste que vous avez sélectionné dans le guide de démarrage rapide.

Remarque

Lors du développement d’un complément basé sur des événements à exécuter dans Outlook sur Android et iOS, notez que le manifeste d’application unifié pour Microsoft 365 ne peut être utilisé que si le complément gère certains événements. Pour savoir quels événements sont pris en charge, consultez Événements et clients pris en charge.

  1. Configurez la propriété « extensions.runtimes » comme vous le feriez pour configurer une commande de fonction. Pour plus d’informations, consultez Configurer le runtime pour la commande de fonction.

  2. Dans le tableau « extensions.ribbons.contexts », ajoutez mailRead en tant qu’élément. Lorsque vous avez terminé, le tableau doit ressembler à ce qui suit.

    "contexts": [
    "mailRead"
],

  3. Dans le tableau « extensions.ribbons.requirements.formFactors », ajoutez « mobile » comme élément. Lorsque vous avez terminé, le tableau doit ressembler à ce qui suit.

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

  4. Ajoutez le tableau « autoRunEvents » suivant en tant que propriété de l’objet dans le tableau « extensions ».

    "autoRunEvents": [

]

  5. Ajoutez un objet comme le suivant au tableau « autoRunEvents ». Tenez compte des informations suivantes à propos de ce code :

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

Conseil

Pour en savoir plus sur les manifestes pour les compléments Outlook, voir Manifeste des compléments Office et Ajouter la prise en charge des commandes de complément dans Outlook sur les appareils mobiles.

Mettre en œuvre le gestionnaire d’événements

Pour permettre à votre complément d’effectuer des tâches lorsque l’événement OnNewMessageCompose se produit, vous devez implémenter un gestionnaire d’événements JavaScript. Dans cette section, vous allez créer la onNewMessageComposeHandler fonction qui ajoute une signature à un nouveau message en cours de composition, puis affiche un message pour avertir que la signature a été ajoutée.

  1. À partir du même projet de démarrage rapide, accédez au répertoire ./src , puis créez un dossier nommé launchevent.

  2. Dans le dossier ./src/launchevent , créez un fichier nommé launchevent.js.

  3. Ouvrez le fichier launchevent.js que vous avez créé et ajoutez le code JavaScript suivant.

    /*
* 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. Enregistrez vos modifications.

Ajouter une référence au fichier JavaScript de gestion des événements

Vérifiez que le fichier ./src/commands/commands.html contient une référence au fichier JavaScript qui contient votre gestionnaire d’événements.

  1. Accédez au dossier ./src/commands , puis ouvrez commands.html.

  2. Juste avant la balise head fermante (</head>), ajoutez une entrée de script pour le fichier JavaScript qui contient le gestionnaire d’événements.

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

  3. Enregistrez vos modifications.

Tester et valider votre complément

  1. Suivez les instructions pour tester et valider votre complément.

  2. Charger une version test de votre complément dans Outlook sur Windows (nouveau ou classique), sur Mac ou sur le web.

  3. Ouvrez Outlook sur Android ou sur iOS. Si Outlook est déjà ouvert sur votre appareil, redémarrez-le.

  4. Créez un message. Le complément basé sur les événements ajoute la signature au message. Si vous avez enregistré une signature sur votre appareil mobile, elle apparaît brièvement dans le message que vous créez, mais elle est immédiatement remplacée par la signature ajoutée par le complément.

    Exemple de signature ajouté à un message en cours de composition dans Outlook Mobile.

Comportement et limitations

Lorsque vous développez un complément basé sur les événements pour Outlook Mobile, tenez compte des comportements et limitations des fonctionnalités suivantes.

  • Étant donné que les compléments basés sur les événements sont censés être courts et légers, un complément est autorisé à s’exécuter pendant un maximum de 60 secondes à partir du moment où il s’active. Pour signaler que votre complément a terminé le traitement d’un événement, votre gestionnaire d’événements doit appeler la méthode event.completed . L’opération de complément se termine également lorsque l’utilisateur ferme la fenêtre de composition ou envoie le message.
  • Un seul complément peut s’exécuter à la fois. Si plusieurs compléments basés sur les événements sont installés sur le compte d’un utilisateur, ils s’exécutent de manière séquentielle.
  • Si vous appuyez longuement sur l’icône Outlook sur votre appareil mobile, puis sélectionnez Nouveau message pour créer un message, un complément basé sur un événement qui gère l’événement OnNewMessageCompose peut prendre quelques secondes pour initialiser et terminer le traitement de l’événement.
  • Lors de l’utilisation d’un complément basé sur des événements qui gère l’événement OnNewMessageCompose , si aucune modification n’est apportée à un nouveau message en cours de composition, un brouillon n’est pas enregistré. Cela s’applique même si le complément ajoute une signature à l’aide de la méthode Office.context.mailbox.item.body.setSignatureAsync .
  • Dans un complément basé sur des événements qui gère les signatures lorsque l’événement OnNewMessageCompose se produit, si vous sélectionnez Répondre en bas d’un message, le complément active et ajoute la signature au message. Toutefois, la signature ne sera pas visible dans l’affichage actuel. Pour afficher votre message avec la signature ajoutée, développez la fenêtre de composition en plein écran.
  • Pour améliorer les fonctionnalités de votre complément, vous pouvez utiliser les API prises en charge à partir d’ensembles de conditions requises ultérieurs en mode composition. Pour plus d’informations, consultez API supplémentaires prises en charge.

API supplémentaires prises en charge

Bien qu’Outlook Mobile prenne en charge les API jusqu’à l’ensemble de conditions requises de boîte aux lettres 1.5, pour étendre davantage la fonctionnalité de votre complément basé sur les événements dans Outlook Mobile, les API supplémentaires des ensembles de conditions requises ultérieurs sont désormais prises en charge en mode composition.

Pour en savoir plus sur les API prises en charge dans Outlook sur les appareils mobiles, consultez API JavaScript Outlook prises en charge dans Outlook sur les appareils mobiles.

Déployer sur les utilisateurs

Les compléments basés sur les événements doivent être déployés par l’administrateur d’un organization. Pour obtenir des conseils sur le déploiement de votre complément via le Centre d’administration Microsoft 365, consultez la section « Déployer sur les utilisateurs » de Configurer votre complément Outlook pour l’activation basée sur les événements.

Voir aussi