Websites

Startseiten sind eine neue Funktion für Google Workspace-Add-ons, mit der Sie eine oder mehrere nicht kontextabhängige Karten definieren können. Karten ohne Kontext werden verwendet, um eine Benutzeroberfläche anzuzeigen, wenn sich der Nutzer außerhalb eines bestimmten Kontexts befindet, z. B. wenn er seinen Gmail-Posteingang aufruft, aber keine Nachricht oder einen Entwurf geöffnet hat.

Auf Startseiten können Sie nicht kontextbezogene Inhalte anzeigen lassen, wie bei den Google-Apps in der Schnellzugriff-Seitenleiste (Google Notizen, Google Kalender und Google Tasks). Sie können auch als Ausgangspunkt für die ersten ersten Aufrufe des Add-ons dienen und anderen Nutzern die Interaktion mit dem Add-on erleichtern.

Sie können eine Startseite für Ihr Add-on definieren, indem Sie sie in Ihrem Projektmanifest angeben und eine oder mehrere homepageTrigger-Funktionen implementieren (siehe Konfiguration der Startseite).

Sie können mehrere Startseiten haben, eine für jede Hostanwendung, die Ihr Add-on erweitert. Sie können auch eine einzelne Standardstartseite definieren, die auf Hosts verwendet wird, für die Sie keine benutzerdefinierte Startseite angegeben haben.

Ihre Add-on-Startseite wird angezeigt, wenn eine der folgenden Bedingungen erfüllt ist:

  • Das Add-on wird nach der Autorisierung zum ersten Mal auf dem Host geöffnet.
  • Wenn der Nutzer von einem kontextbezogenen Kontext zu einem nicht kontextbezogenen Kontext wechselt, während das Add-on geöffnet ist. Beispiel: Von einem Kalendertermin zum Hauptkalender.
  • Wenn der Nutzer so oft auf die Schaltfläche „Zurück“ klickt, damit jede andere Karte aus den internen Stacks entfernt wird.
  • Wenn eine UI-Interaktion auf einer Karte ohne Kontext zu einem Navigation.popToRoot()-Aufruf führt.

Das Entwerfen einer Startseite ist nicht obligatorisch, wird aber dringend empfohlen. Wenn du keine definiert, wird immer dann eine allgemeine Karte mit deinem Add-on-Namen verwendet, wenn ein Nutzer sonst die Startseite aufrufen würde.

Konfiguration der Startseite

Google Workspace-Add-ons verwenden das Feld addOns.common.homepageTrigger, um die Standardstartseite (nicht kontextabhängige) Add-ons für alle Hostanwendungen im Manifest des Add-ons zu konfigurieren:

    {
      // ...
      "addOns": {
        // ...
        "common": {
          // ...
          "homepageTrigger": {
            "runFunction": "myFunction",
            "enabled": true
          }
        }
      }
    }

  • runFunction: Der Name der Apps Script-Funktion, die vom Google Workspace-Add-on-Framework zum Rendern der Startseiten-Add-on-Karten aufgerufen wird. Diese Funktion ist die Triggerfunktion für die Startseite. Diese Funktion muss ein Array von Card-Objekten erstellen und zurückgeben, die die Startseiten-UI bilden. Wenn mehrere Karten zurückgegeben werden, zeigt die Hostanwendung die Kartenheader in einer Liste an, aus der der Nutzer auswählen kann (siehe Mehrere Karten zurückgeben).

  • enabled: Gibt an, ob Startseitenkarten für diesen Bereich aktiviert werden sollen. Dieses Feld ist optional und hat den Standardwert true. Wenn Sie diese Option auf false festlegen, werden Startseitenkarten für alle Hosts deaktiviert, sofern sie für diesen Host nicht überschrieben werden (siehe unten).

Neben der allgemeinen Konfiguration sind in der Konfiguration jeder Hostanwendung auch identische strukturierte Überschreibungen pro Host unter addOns.gmail.homepageTrigger, addOns.calendar.homepageTrigger usw. verfügbar:

    {
      ...
      "addOns": {
        ...
        "common": {
          // By default, call 'buildHomePage' to render homepage content
          // in all hosts. Since calendar.homepageTrigger below overrides
          // this in Calendar and Drive and the homepageTrigger is disabled
          // for Gmail, this homepage function never executes.
          "homepageTrigger": { "runFunction": "buildHomePage" }
        },
        "calendar": {
          // Show customized homepage content for Calendar only.
          "homepageTrigger": { "runFunction": "buildCalendarHomepage" }
        },
        "drive": {
          // Show customized homepage content for Drive only.
          "homepageTrigger": { "runFunction": "buildDriveHomepage" }
        }
        "gmail": {
          // Disable homepage add-on content in Gmail.
          "homepageTrigger": { "enabled": false }
        },
        ...
      }
    }

Dies entspricht dem folgenden Manifestauszug:

    {
      ...
      "addOns": {
        ...
        "common": { /* ... */ }, // Omitted a default homepageTrigger specification.
        "calendar": {
          // Show customized homepage content for Calendar only.
          "homepageTrigger": { "runFunction": "myCalendarFunction" }
        },
        "drive": {
          // Show customized homepage content for Drive only.
          "homepageTrigger": { "runFunction": "myDriveFunction" }
        }
        "gmail": { /* ... */ },
        ...
      }
    }

Keiner der homepageTrigger-Abschnitt ist erforderlich. Die für ein Add-on in einem bestimmten Hostprodukt angezeigte UI hängt jedoch davon ab, ob das entsprechende Manifestfeld vorhanden ist und ob ein zugehöriges homepageTrigger vorhanden ist. Das folgende Beispiel zeigt, welche Add-on-Triggerfunktionen (falls vorhanden) ausgeführt werden, um eine Startseiten-UI für verschiedene Manifestkonfigurationen zu erstellen:

Ablauf auf der Startseite

Ereignisobjekte auf der Startseite

Beim Aufrufen der oben beschriebenen Trigger-Funktion (runFunction) wird ein Ereignisobjekt übergeben, das Daten aus dem Aufrufkontext enthält.

Ereignisobjekte auf der Startseite enthalten keine Widget- oder Kontextinformationen. Die übergebenen Informationen sind auf die folgenden Felder für allgemeine Ereignisobjekte beschränkt:

  • commonEventObject.clientPlatform
  • commonEventObject.hostApp
  • commonEventObject.userLocale und commonEventObject.userTimezone (Informationen zu Einschränkungen finden Sie unter Nutzersprache und Zeitzone abrufen).

Weitere Informationen finden Sie unter Ereignisobjekt.

Andere Karten ohne Kontext

Ihre Add-on-UI kann zusätzliche Karten ohne Kontext enthalten, die keine Startseiten sind. Ihre Startseite kann beispielsweise eine Schaltfläche haben, über die eine Karte „Einstellungen“ geöffnet wird, auf der der Nutzer die Add-on-Einstellungen anpassen kann. Diese Einstellungen sind in den meisten Fällen unabhängig vom Kontext und daher nicht kontextbezogen.

Nicht kontextbasierte Karten werden wie alle anderen Karten erstellt. Der einzige Unterschied besteht darin, welche Aktion oder welches Ereignis die Karte generiert und anzeigt. Weitere Informationen zum Erstellen von Übergängen zwischen Karten finden Sie unter Navigationsmethoden.