Websites

Startseiten sind eine Funktion von Google Workspace-Add‑ons, mit der Sie eine oder mehrere nicht kontextbezogene Karten definieren können. Nicht kontextbezogene Karten zeigen eine Benutzeroberfläche an, wenn sich der Nutzer außerhalb eines bestimmten Kontexts befindet, z. B. wenn er seinen Gmail-Posteingang ohne eine geöffnete Nachricht oder einen Entwurf aufruft.

Auf Startseiten können Sie nicht kontextbezogene Inhalte anzeigen, ähnlich wie bei den Google-Apps in der Seitenleiste für den Schnellzugriff (Google Notizen, Google Kalender und Google Tasks). Startseiten können auch einen ersten Ausgangspunkt bieten, wenn ein Nutzer Ihr Add-on zum ersten Mal öffnet. Sie sind nützlich, um neuen Nutzern die Interaktion mit Ihrem Add-on zu erklären.

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

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

Die Add‑on-Startseite wird in folgenden Fällen angezeigt:

  • Wenn das Add‑on zum ersten Mal im Host geöffnet wird (nach der Autorisierung).
  • Wenn der Nutzer während des Öffnens des Add-ons von einem kontextbezogenen zu einem nicht kontextbezogenen Kontext wechselt. Zum Beispiel durch Bearbeiten eines Kalendertermins im Hauptkalender.
  • Wenn der Nutzer so oft auf den Button „Zurück“ klickt, dass jede zweite Karte aus den internen Stapeln entfernt wird.
  • Wenn eine UI-Interaktion auf einer nicht kontextbezogenen Karte zu einem Navigation.popToRoot-Aufruf führt.

Es wird empfohlen, eine Startseite zu erstellen. Wenn Sie keine definieren, wird eine generische Karte mit dem Namen Ihres Add-ons verwendet, wenn ein Nutzer zur Startseite navigiert.

Konfiguration der Startseite

Google Workspace-Add‑ons verwenden das Feld addOns.common.homepageTrigger, um die Standardinhalte der Startseite (nicht kontextbezogen) für Hostanwendungen im Manifest des Add‑ons zu konfigurieren:

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

  • runFunction: Der Name der Google Apps Script-Funktion, die vom Google Workspace-Add-on-Framework aufgerufen wird, um Add-on-Karten auf der Startseite zu rendern. Diese Funktion ist die Homepage-Triggerfunktion. Diese Funktion muss ein Array von Card-Objekten erstellen und zurückgeben, aus denen die Benutzeroberfläche der Startseite besteht. Wenn mehr als eine Karte zurückgegeben wird, zeigt die Hostanwendung die Kartenüberschriften 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 wird standardmäßig auf true gesetzt. Wenn Sie diese Option auf false festlegen, werden Startseitenkarten für alle Hosts deaktiviert, sofern sie nicht für diesen Host überschrieben werden (siehe hostspezifische Konfiguration).

Damit ein Host die gemeinsame Startseite verwenden kann, müssen sowohl addOns.common.homepageTrigger als auch die Ressource der obersten Ebene des Hosts im Manifest des Add-ons vorhanden sein. Wenn addOns.gmail beispielsweise nicht im Manifest vorhanden ist, wird das Add-on für Gmail deaktiviert und es wird keine Startseite oder andere Funktion in diesem Host angezeigt.

Zusätzlich zur allgemeinen Konfiguration sind in der Konfiguration jeder Hostanwendung unter addOns.gmail.homepageTrigger, addOns.calendar.homepageTrigger und anderen hostspezifischen Triggern identisch strukturierte Überschreibungen pro Host verfügbar.

Das folgende Beispiel zeigt ein Manifest, in dem ein allgemeiner Homepage-Trigger definiert ist, der jedoch mit benutzerdefinierten Funktionen für Kalender und Drive überschrieben und für Gmail deaktiviert wird. In dieser Konfiguration wird die gemeinsame buildHomePage-Funktion nie ausgeführt, da sie entweder überschrieben wird oder der Host deaktiviert ist.

{
  ...
  "addOns": {
    ...
    "common": {
      "homepageTrigger": { "runFunction": "buildHomePage" }
    },
    "calendar": {
      "homepageTrigger": { "runFunction": "buildCalendarHomepage" }
    },
    "drive": {
      "homepageTrigger": { "runFunction": "buildDriveHomepage" }
    },
    "gmail": {
      "homepageTrigger": { "enabled": false }
    },
    ...
  }
}

Der folgende Manifestauszug entspricht dem vorherigen Beispiel, obwohl die Standard-homepageTrigger und die Gmail-Konfiguration weggelassen wurden:

{
  "addOns": {
    "common": {},
    "calendar": {
      "homepageTrigger": { "runFunction": "myCalendarFunction" }
    },
    "drive": {
      "homepageTrigger": { "runFunction": "myDriveFunction" }
    },
    "gmail": {},
    ...
  }
}

Keiner der homepageTrigger-Abschnitte ist erforderlich. Die Benutzeroberfläche, die für ein Add-on in einem Hostprodukt angezeigt wird, hängt davon ab, ob das entsprechende Manifestfeld vorhanden ist und ob ein zugehöriges homepageTrigger vorhanden ist. Das folgende Beispiel zeigt, welche Add-on-Triggerfunktionen ausgeführt werden, um eine Startseiten-Benutzeroberfläche für verschiedene Manifestkonfigurationen zu erstellen:

Diagramm zum Ausführungsablauf der Triggerfunktion für die Add-on-Startseite

Homepage-Ereignisobjekte

Wenn die oben beschriebene Homepage-Triggerfunktion (runFunction) aufgerufen wird, wird ihr ein Ereignisobjekt übergeben, das Daten aus dem Aufrufkontext enthält.

Homepage-Ereignisobjekte enthalten keine Widget- oder Kontextinformationen. Die übergebenen Informationen sind auf die folgenden Felder des allgemeinen Ereignisobjekts beschränkt:

  • commonEventObject.clientPlatform
  • commonEventObject.hostApp
  • commonEventObject.userLocale und commonEventObject.userTimezone (Informationen zu Einschränkungen finden Sie unter Auf Nutzer-Locale und ‑Zeitzone zugreifen).

Weitere Informationen finden Sie unter Ereignisobjekt.

Andere nicht kontextbezogene Karten

Die Benutzeroberfläche Ihres Add-ons kann zusätzliche nicht kontextbezogene Karten enthalten, die keine Startseiten sind. Auf Ihrer Startseite könnte sich beispielsweise eine Schaltfläche befinden, über die eine Karte mit den Add-on-Einstellungen geöffnet wird. Diese Einstellungen sind in der Regel kontextunabhängig.

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