Implementieren der ereignisbasierten Aktivierung in mobilen Outlook-Add-Ins

Artikel
02/29/2024

Entwickeln Sie mit der ereignisbasierten Aktivierungsfunktion ein Add-In, um Vorgänge automatisch zu aktivieren und abzuschließen, wenn bestimmte Ereignisse in Outlook unter Android oder iOS auftreten, z. B. das Verfassen einer neuen Nachricht.

In den folgenden Abschnitten erfahren Sie, wie Sie ein mobiles Outlook-Add-In entwickeln, das automatisch eine Signatur zu neuen Nachrichten hinzufügt, die erstellt werden. Dies zeigt ein Beispielszenario, in dem Sie die ereignisbasierte Aktivierung in Ihrem mobilen Add-In implementieren können. Verbessern Sie die mobile Benutzererfahrung erheblich, indem Sie heute andere Szenarien in Ihrem Add-In erkunden.

Informationen zum Implementieren eines ereignisbasierten Add-Ins für Outlook unter Windows (klassisch und neu (Vorschau)), auf Mac und im Web finden Sie unter Konfigurieren Ihres Outlook-Add-Ins für die ereignisbasierte Aktivierung.

Hinweis

Outlook für Android und iOS unterstützt nur bis zum Postfachanforderungssatz 1.5. Zur Unterstützung der ereignisbasierten Aktivierungsfunktion wurden jedoch einige APIs aus späteren Anforderungssätzen auf mobilen Clients aktiviert. Weitere Informationen zu dieser Ausnahme finden Sie unter Zusätzliche unterstützte APIs.

Unterstützte Clients

Das Add-In, das Sie in dieser exemplarischen Vorgehensweise entwickeln, wird ab Version 4.2352.0 in Outlook unter Android und unter iOS unterstützt. Sie benötigen ein Microsoft 365-Abonnement, um das Feature ausführen zu können.

Einrichten der Umgebung

Schließen Sie den Outlook-Schnellstart ab, der ein Add-In-Projekt mit dem Yeoman-Generator für Office-Add-Ins erstellt.

Konfigurieren des Manifests

Hinweis

Das einheitliche Microsoft 365-Manifest (Vorschau) wird derzeit auf mobilen Geräten nicht unterstützt.

Um ein ereignisbasiertes Add-In in Outlook Mobile zu aktivieren, müssen Sie die folgenden Elemente im VersionOverridesV1_1 Knoten des Manifests konfigurieren.

Geben Sie im Runtimes-Element die HTML-Datei an, die auf die Ereignisbehandlungs-JavaScript-Datei verweist.
Fügen Sie das MobileFormFactor-Element hinzu, um Ihr Add-In in Outlook Mobile verfügbar zu machen.
Legen Sie die des xsi:typeExtensionPoint-Elements auf LaunchEvent fest. Dadurch wird die ereignisbasierte Aktivierungsfunktion in Ihrem mobilen Outlook-Add-In aktiviert.
Legen Sie im LaunchEvent-Element auf Type fest OnNewMessageCompose , und geben Sie den JavaScript-Funktionsnamen des Ereignishandlers im -Attribut an FunctionName .

Öffnen Sie in Ihrem Code-Editor das Schnellstartprojekt, das Sie erstellt haben.
Öffnen Sie die manifest.xml Datei, die sich im Stammverzeichnis Ihres Projekts befindet.

Wählen Sie den gesamten <VersionOverrides-Knoten> (einschließlich der Tags öffnen und schließen) aus, und ersetzen Sie ihn durch den folgenden XML-Code.

<VersionOverrides xmlns="http://schemas.microsoft.com/office/mailappversionoverrides" xsi:type="VersionOverridesV1_0">
    <VersionOverrides xmlns="http://schemas.microsoft.com/office/mailappversionoverrides/1.1" xsi:type="VersionOverridesV1_1">
        <Requirements>
            <bt:Sets DefaultMinVersion="1.5">
                <bt:Set Name="Mailbox"/>
            </bt:Sets>
        </Requirements>
        <Hosts>
            <Host xsi:type="MailHost">
                <!-- The HTML file that references or contains the JavaScript event handlers.
                    This is used by Outlook on mobile devices. -->
                <Runtimes>
                    <Runtime resid="WebViewRuntime.Url">
                    </Runtime>
                </Runtimes>
                <!-- Defines the add-in for Outlook on Windows (classic and new (preview)), on Mac, and on the web. -->
                <DesktopFormFactor>
                    <FunctionFile resid="Commands.Url"/>
                    <ExtensionPoint xsi:type="MessageReadCommandSurface">
                        <OfficeTab id="TabDefault">
                            <Group id="msgReadGroup">
                                <Label resid="GroupLabel"/>
                                <Control xsi:type="Button" id="msgReadOpenPaneButton">
                                    <Label resid="TaskpaneButton.Label"/>
                                    <Supertip>
                                        <Title resid="TaskpaneButton.Label"/>
                                        <Description resid="TaskpaneButton.Tooltip"/>
                                    </Supertip>
                                    <Icon>
                                        <bt:Image size="16" resid="Icon.16x16"/>
                                        <bt:Image size="32" resid="Icon.32x32"/>
                                        <bt:Image size="80" resid="Icon.80x80"/>
                                    </Icon>
                                    <Action xsi:type="ShowTaskpane">
                                        <SourceLocation resid="Taskpane.Url"/>
                                    </Action>
                                </Control>
                                <Control xsi:type="Button" id="ActionButton">
                                    <Label resid="ActionButton.Label"/>
                                    <Supertip>
                                        <Title resid="ActionButton.Label"/>
                                        <Description resid="ActionButton.Tooltip"/>
                                    </Supertip>
                                    <Icon>
                                        <bt:Image size="16" resid="Icon.16x16"/>
                                        <bt:Image size="32" resid="Icon.32x32"/>
                                        <bt:Image size="80" resid="Icon.80x80"/>
                                    </Icon>
                                    <Action xsi:type="ExecuteFunction">
                                        <FunctionName>action</FunctionName>
                                    </Action>
                                </Control>
                            </Group>
                        </OfficeTab>
                    </ExtensionPoint>
                </DesktopFormFactor>
                <!-- Defines the add-in for Outlook mobile. -->
                <MobileFormFactor>
                    <!-- Configures event-based activation. -->
                    <ExtensionPoint xsi:type="LaunchEvent">
                        <LaunchEvents>
                            <LaunchEvent Type="OnNewMessageCompose" FunctionName="onNewMessageComposeHandler"/>
                        </LaunchEvents>
                        <!-- Identifies the runtime to be used (also referenced by the Runtime element). -->
                        <SourceLocation resid="WebViewRuntime.Url"/>
                    </ExtensionPoint>
                </MobileFormFactor>
            </Host>
        </Hosts>
        <!-- This manifest uses a fictitious web server, contoso.com, to host the add-in's files.
             Replace these instances with the information of the web server that hosts your add-in's files. -->
        <Resources>
            <bt:Images>
                <bt:Image id="Icon.16x16" DefaultValue="https://contoso.com/assets/icon-16.png"/>
                <bt:Image id="Icon.32x32" DefaultValue="https://contoso.com/assets/icon-32.png"/>
                <bt:Image id="Icon.80x80" DefaultValue="https://contoso.com/assets/icon-80.png"/>
            </bt:Images>
            <bt:Urls>
                <bt:Url id="Commands.Url" DefaultValue="https://contoso.com/commands.html"/>
                <bt:Url id="Taskpane.Url" DefaultValue="https://contoso.com/taskpane.html"/>
                <bt:Url id="WebViewRuntime.Url" DefaultValue="https://contoso.com/commands.html"/>
            </bt:Urls>
            <bt:ShortStrings>
                <bt:String id="GroupLabel" DefaultValue="Event-based activation on mobile"/>
                <bt:String id="TaskpaneButton.Label" DefaultValue="Show Taskpane"/>
                <bt:String id="ActionButton.Label" DefaultValue="Perform an action"/>
            </bt:ShortStrings>
            <bt:LongStrings>
                <bt:String id="TaskpaneButton.Tooltip" DefaultValue="Opens a pane displaying all available properties."/>
                <bt:String id="ActionButton.Tooltip" DefaultValue="Perform an action when clicked."/>
            </bt:LongStrings>
        </Resources>
    </VersionOverrides>
</VersionOverrides>

Speichern Sie Ihre Änderungen.

Tipp

Weitere Informationen zu Manifesten für Outlook-Add-Ins finden Sie unter Office-Add-Ins-Manifest und Hinzufügen von Unterstützung für Add-In-Befehle in Outlook auf mobilen Geräten.

Implementieren des Ereignishandlers

Damit Ihr Add-In Aufgaben ausführen kann, wenn das OnNewMessageCompose Ereignis eintritt, müssen Sie einen JavaScript-Ereignishandler implementieren. In diesem Abschnitt erstellen Sie die Funktion, die onNewMessageComposeHandler einer neu erstellten Nachricht eine Signatur hinzufügt, und zeigt dann eine Nachricht an, die benachrichtigt, dass die Signatur hinzugefügt wurde.

Navigieren Sie aus demselben Schnellstartprojekt zum Verzeichnis ./src , und erstellen Sie dann einen neuen Ordner mit dem Namen launchevent.
Erstellen Sie im Ordner ./src/launchevent eine neue Datei mit dem Namen launchevent.js.

Öffnen Sie die launchevent.jsDatei, die Sie erstellt haben, und fügen Sie den folgenden JavaScript-Code hinzu.

/*
* 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();
                });
            });
        });
    });
}

Speichern Sie Ihre Änderungen.

Hinzufügen eines Verweises auf die Ereignisbehandlungs-JavaScript-Datei

Stellen Sie sicher, dass die HTML-Datei, die <Sie im Runtime-Element> Ihres Manifests angegeben haben, einen Verweis auf die JavaScript-Datei enthält, die Ihren Ereignishandler enthält.

Navigieren Sie zum Ordner ./src/commands , und öffnen Sie danncommands.html.
Fügen Sie unmittelbar vor dem schließenden Headtag (</head>) einen Skripteintrag für die JavaScript-Datei hinzu, die den Ereignishandler enthält.
```
<script type="text/javascript" src="../launchevent/launchevent.js"></script>
```
Speichern Sie Ihre Änderungen.

Testen und Überprüfen Ihres Add-Ins

Befolgen Sie die Anleitung, um Ihr Add-In zu testen und zu überprüfen.
Laden Sie Ihr Add-In in Outlook unter Windows (klassisch oder neu (Vorschau)), auf Mac oder im Web quer.
Öffnen Sie Outlook unter Android oder unter iOS. Wenn Outlook bereits auf Ihrem Gerät geöffnet ist, starten Sie es neu.
Erstellen Sie eine neue Nachricht. Das ereignisbasierte Add-In fügt der Nachricht die Signatur hinzu. Wenn Sie eine Signatur auf Ihrem mobilen Gerät gespeichert haben, wird sie kurz in der von Ihnen erstellten Nachricht angezeigt, aber sofort durch die signatur ersetzt, die vom Add-In hinzugefügt wurde.

Verhalten und Einschränkungen

Beachten Sie beim Entwickeln eines ereignisbasierten Add-Ins für Outlook Mobile die folgenden Featureverhalten und Einschränkungen.

Derzeit wird nur das OnNewMessageCompose -Ereignis in Outlook Mobile unterstützt. Dieses Ereignis tritt auf, wenn eine neue Nachricht (einschließlich "Antworten", "Allen antworten" und "Weiterleiten") erstellt wird. Das OnNewMessageCompose Ereignis tritt nicht auf, wenn Sie einen vorhandenen Entwurf bearbeiten.
Da ereignisbasierte Add-Ins voraussichtlich kurz ausgeführt und einfach sind, kann ein Add-In maximal 60 Sekunden ab der Aktivierung ausgeführt werden. Um zu signalisieren, dass das Add-In die Verarbeitung eines Ereignisses abgeschlossen hat, muss der Ereignishandler die event.completed-Methode aufrufen. Der Add-In-Vorgang endet auch, wenn der Benutzer das Fenster zum Verfassen schließt oder die Nachricht sendet.
Es kann jeweils nur ein Add-In ausgeführt werden. Wenn mehrere ereignisbasierte Add-Ins im Konto eines Benutzers installiert sind, werden sie sequenziell ausgeführt.
Wenn Sie auf Ihrem mobilen Gerät auf das Outlook-Symbol tippen und gedrückt halten und dann Neue E-Mail auswählen, um eine neue Nachricht zu erstellen, kann es einige Sekunden dauern, bis das ereignisbasierte Add-In initialisiert und die Verarbeitung des Ereignisses abgeschlossen ist.
Wenn keine Änderungen an einer neu erstellten Nachricht vorgenommen werden, wird kein Entwurf gespeichert, auch wenn das ereignisbasierte Add-In eine Signatur mithilfe der Office.context.mailbox.item.body.setSignatureAsync-Methode hinzufügt.
Wenn Sie in einem ereignisbasierten Add-In, das Signaturen verwaltet, antworten am Ende einer Nachricht auswählen, wird das Add-In aktiviert und fügt die Signatur der Nachricht hinzu. Die Signatur ist jedoch in der aktuellen Ansicht nicht sichtbar. Wenn Sie Ihre Nachricht mit der hinzugefügten Signatur anzeigen möchten, erweitern Sie das Fenster zum Verfassen auf den Vollbildmodus.
Um die Funktionalität Ihres Add-Ins zu verbessern, können Sie unterstützte APIs aus späteren Anforderungssätzen im Verfassenmodus verwenden. Weitere Informationen finden Sie unter Zusätzliche unterstützte APIs.

Zusätzliche unterstützte APIs

Obwohl Outlook Mobile APIs bis zum Postfachanforderungssatz 1.5 unterstützt, werden jetzt zusätzliche APIs aus späteren Anforderungssätzen im Erstellmodus unterstützt, um die Funktion Ihres ereignisbasierten Add-Ins in Outlook Mobile weiter zu erweitern.

Weitere Informationen zu APIs, die in Outlook auf mobilen Geräten unterstützt werden, finden Sie unter In Outlook auf mobilen Geräten unterstützte JavaScript-APIs.

Bereitstellen für Benutzer

Ereignisbasierte Add-Ins müssen vom Administrator eines organization bereitgestellt werden. Eine Anleitung zum Bereitstellen Ihres Add-Ins über die Microsoft 365 Admin Center finden Sie im Abschnitt "Bereitstellen für Benutzer" unter Konfigurieren Ihres Outlook-Add-Ins für die ereignisbasierte Aktivierung.