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 werden in der Benutzeroberfläche angezeigt, 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 zu zeigen, wie sie mit Ihrem Add-on interagieren können.

Definieren Sie eine Startseite für Ihr Add-on, indem Sie sie im Projektmanifest angeben und eine oder mehrere homepageTrigger-Funktionen implementieren (siehe Startseitenkonfiguration). Wenn Ihr Add-on Google Chat erweitert, wird die zugehörige Startseite auf dem Tab Startseite einer 1:1-Direktnachricht mit der Chat-App angezeigt. Sie wird in der Google Cloud Console anstelle des Manifests konfiguriert (siehe Startseite für Chat konfigurieren).

Sie können mehrere Startseiten haben, eine für jede Hostanwendung, die durch Ihr Add-on erweitert wird. 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) oder wenn ein Nutzer den Tab Startseite in einer 1:1-Direktnachricht mit Ihrer Chat-App in Chat öffnet.
• Wenn der Nutzer von einem kontextbezogenen zu einem nicht kontextbezogenen Kontext wechselt, während das Add-on geöffnet ist. Beispiel: Sie bearbeiten einen Kalendertermin 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 gestalten. Wenn Sie keine definieren, wird eine generische Karte mit dem Namen Ihres Add-ons verwendet, wenn ein Nutzer zur Startseite navigiert.

Startseitenkonfiguration

Google Workspace-Add-ons verwenden das Feld addOns.common.homepageTrigger, um die standardmäßigen (nicht kontextbezogenen) Add-on-Inhalte für Hostanwendungen im Add-on-Manifest 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 der Standardwert ist true. Wenn Sie diesen Wert auf false festlegen, werden Startseitenkarten für alle Hosts deaktiviert, sofern sie nicht für den jeweiligen 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 gemeinsamen 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.

Im folgenden Beispiel sehen Sie ein Manifest, in dem ein gemeinsamer 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-UI für verschiedene Manifestkonfigurationen zu erstellen:

Startseite für Google Chat konfigurieren

Im Gegensatz zu anderen Google Workspace-Hostanwendungen wird für Add-ons, die Chat erweitern, keine Startseite im Schnellzugriffsfeld auf der rechten Seite angezeigt und addOns.common.homepageTrigger wird nicht im Manifest verwendet. Stattdessen wird Ihre Startseite in Google Chat als Karte auf dem Tab Startseite einer 1:1-Direktnachricht mit der Chat App angezeigt.

So aktivieren und konfigurieren Sie einen App Home-Trigger für Ihr Chat-Add-on in der Google Cloud Console:

1. Rufen Sie in der Google Cloud Console die Seite Menü > APIs & Dienste > Aktivierte APIs & Dienste > Google Chat API > Konfiguration auf.

   Zur Google Chat API-Konfiguration

2. Achten Sie darauf, dass unter Interaktive Funktionen die Option Interaktive Funktionen aktivieren aktiviert ist, und setzen Sie dann ein Häkchen bei App-Startseite unterstützen.

3. Geben Sie unter Verbindungseinstellungen > Auslöser den App Home-Handler in das Feld App Home ein. Das hängt von der Add-on-Architektur ab:

   • HTTP: Geben Sie die HTTPS-Endpunkt-URL ein, die App Home-Anfragen verarbeitet, oder lassen Sie das Feld leer, damit alle Ereignisse an Ihre gemeinsame HTTP-Endpunkt-URL gesendet werden.
   • Google Apps Script: Geben Sie den Namen der Google Apps Script-Callback-Funktion ein, mit der die Startseitenkarte erstellt und zurückgegeben wird (Standardwert: onAppHome).

4. Klicken Sie auf Speichern.

Wenn ein Nutzer den Tab Startseite einer Direktnachricht mit Ihrer Chat-App öffnet, sendet Chat ein App-Startseite-Triggerereignis an Ihren Endpunkt oder Ihre Funktion. Um die Startseite zu rendern, gib ein RenderActions-Objekt mit einer pushCard-Navigationsaktion zurück (oder verwende updateCard, wenn du die Startseite als Reaktion auf das Klicken auf einen Button auf der Startseite aktualisierst):

{
  "action": {
    "navigations": [
      {
        "pushCard": {
          "header": {
            "title": "Welcome to App Home"
          },
          "sections": [
            {
              "widgets": [
                {
                  "textParagraph": {
                    "text": "Manage your settings and view your dashboard here."
                  }
                }
              ]
            }
          ]
        }
      }
    ]
  }
}

function onAppHome(event) {
  const card = CardService.newCardBuilder()
      .setHeader(
          CardService.newCardHeader().setTitle('Welcome to App Home'))
      .addSection(
          CardService.newCardSection().addWidget(
              CardService.newTextParagraph().setText(
                  'Manage your settings and view your dashboard here.')))
      .build();

  return CardService.newActionResponseBuilder()
      .setNavigation(CardService.newNavigation().pushCard(card))
      .build();
}

Weitere Informationen zum Verarbeiten von Chat-Triggern und zum Zurückgeben von Aktionen finden Sie unter Nutzerinteraktionen empfangen und darauf reagieren.

Homepage-Ereignisobjekte

Wenn die Funktion aufgerufen wird, wird ihr das zuvor beschriebene runFunctionEreignisobjekt mit Daten aus dem Aufrufkontext übergeben.

Homepage-Ereignisobjekte enthalten keine Widget- oder Kontextinformationen. Die übergebenen Informationen umfassen die folgenden Felder des gemeinsamen Ereignisobjekts:

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

In Chat enthält das Ereignisobjekt „App Home“ auch das Feld chat mit Informationen zum Nutzer und zur Interaktionszeit:

• chat.user: Der Chat-Nutzer, der den Tab Startseite geöffnet hat.
• chat.eventTime: Der Zeitstempel, der angibt, wann der Nutzer den Tab Startseite geöffnet hat.

Weitere Informationen finden Sie unter Event-Objekt.

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.