Websites

Startseiten sind eine neue Funktion für Google Workspace-Add-ons, mit der Sie eine oder mehrere nicht kontextbezogene Karten definieren können. Nicht kontextbezogene Karten 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 noch keine Nachricht oder keinen Entwurf geöffnet hat.

Auf Startseiten können Sie nicht kontextbezogene Inhalte anzeigen, genau wie die 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 gemeinsame Standardstartseite definieren, die auf Hosts verwendet wird, für die Sie keine benutzerdefinierte Startseite angegeben haben.

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

  • 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 vom Bearbeiten eines Kalendertermins zum Hauptkalender.
  • Wenn der Nutzer so oft auf die Schaltfläche „Zurück“ klickt, dass jede zweite Karte aus den internen Stapeln entfernt wird.
  • Wenn eine UI-Interaktion in einer nicht kontextbezogenen Karte zu einem Navigation.popToRoot()-Aufruf führt.

Das Erstellen einer Startseite ist nicht obligatorisch, wird aber dringend empfohlen. Wenn Sie keine Startseite definieren, wird eine generische Karte mit dem Namen Ihres Add-ons verwendet, wenn ein Nutzer ansonsten zur Startseite navigieren würde.

Startseitenkonfiguration

Google Workspace-Add-ons verwenden das Feld addOns.common.homepageTrigger, um die standardmäßigen (nicht kontextbezogenen) Add-on-Inhalte 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 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 den jeweiligen Host überschrieben werden (siehe unten).

Zusätzlich zur gemeinsamen Konfiguration sind in der Konfiguration jeder Hostanwendung unter addOns.gmail.homepageTrigger, addOns.calendar.homepageTrigger usw. auch identisch strukturierte Überschreibungen pro Host 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-Abschnitte ist erforderlich. Die Benutzeroberfläche, die für ein Add-on in einem bestimmten Hostprodukt angezeigt wird, hängt jedoch davon ab, ob das entsprechende Manifestfeld vorhanden ist und ob eine zugehörige 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

Homepage-Ereignisobjekte

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

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

Weitere Informationen finden Sie unter Ereignisobjekt.

Andere nicht kontextbezogene Karten

Die Add-on-Benutzeroberfläche kann zusätzliche nicht kontextbezogene Karten enthalten, die keine Startseiten sind. Auf Ihrer Startseite befindet sich beispielsweise eine Schaltfläche, über die eine Karte mit den Add-on-Einstellungen geöffnet wird. Diese Einstellungen sind in den meisten Fällen kontextunabhängig.

Nicht kontextbezogene 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.