Ereignisobjekte

Auf dieser Seite wird die Struktur von Ereignisobjekten für Google Workspace-Add-ons beschrieben.

Ereignisobjekte sind JSON-Strukturen, die automatisch erstellt und als Parameter an Trigger- oder Callback-Funktionen übergeben werden, wenn ein Nutzer mit einem Add-on interagiert. Ereignisobjekte enthalten clientseitige Informationen zur Hostanwendung und zum aktuellen Kontext für die serverseitige Callback-Funktion des Add-ons.

Google Workspace-Add-ons verwenden Ereignisobjekte an folgenden Stellen:

• Startseitentrigger: Jeder homepageTrigger-Funktion, die Sie definieren, wird automatisch ein Ereignisobjekt übergeben, wenn die Homepage-Triggerfunktion ausgelöst wird. Sie können dieses Objekt in Ihrer Homepage-Triggerfunktion verwenden, um die aktive Host-App, die Plattform des Clients, das Gebietsschema des Nutzers und andere Informationen zu ermitteln.

  Die Ereignisobjekte, die beim Auslösen von Startseiten-Triggern erstellt werden, enthalten nicht alle Felder der anderen beiden Fälle. Felder für Widgets und Kontextinformationen werden ausgelassen.

• Kontextbezogene Trigger: Jede Hostanwendung bietet eine andere Reihe von Kontext-Triggern, die ausgelöst werden, wenn der Nutzer einen bestimmten Kontext aufruft. Beispiel:

  • Gmail bietet einen kontextbezogenen Trigger, wenn ein Nutzer eine Nachricht öffnet, und einen weiteren, wenn ein Nutzer eine Nachricht verfasst.
  • Google Kalender bietet einen kontextbezogenen Trigger, wenn ein Nutzer einen Termin öffnet.
  • Google Drive bietet einen kontextbezogenen Auslöser, wenn ein Nutzer Drive-Dateien auswählt.

  Wenn ein kontextbezogener Trigger ausgelöst wird, ruft die Hostanwendung die entsprechende runFunction auf, die im Add-on-Manifest aufgeführt ist, und übergibt ihr ein Ereignisobjekt als Parameter. Die Ereignisobjekte, die beim Auslösen kontextbezogener Trigger erstellt werden, enthalten alle Felder, die in Ereignisobjekten für Homepage-Trigger enthalten sind, sowie Felder mit Kontextinformationen.

• Widget-Aktionen: Ereignisobjekte werden auch verwendet, um Widgets interaktiv zu gestalten. Dabei wird dasselbe Aktionsmodell wie bei Gmail-Add-ons verwendet. Google Workspace-Add-ons verwenden dieselben Widget-Handler-Funktionen, Action-Objekte und Aktionsantworten. In Google Workspace-Add-ons enthalten die Aktionsereignisobjekte jedoch noch mehr Informationen, auf die eine Callback-Funktion reagieren kann.

  Die Ereignisobjekte, die als Ergebnis von Widget-Aktionen erstellt werden, enthalten alle Felder, die in kontextbezogenen Trigger-Ereignisobjekten enthalten sind, sowie Felder mit Widget-Informationen.

• Vorschaulink-Trigger: In Google Docs, Sheets und Präsentationen können Sie Linkvorschauen für Drittanbieterdienste basierend auf bestimmten URL-Mustern konfigurieren. Wenn Nutzer mit einem Link interagieren, der dem Muster entspricht, wird linkPreviewTriggers ausgelöst und ein Ereignisobjekt, das den Link enthält, wird an die Callback-Funktion des Triggers übergeben. Ihr Add-on kann dieses Ereignisobjekt verwenden, um einen Smart-Chip und eine Karte zu erstellen, auf denen Informationen zum Link in der Hostanwendung angezeigt werden. Sie können auch Widget-Aktionen erstellen, damit Nutzer mit der Vorschaukarte und ihren Inhalten interagieren können.

• Google Chat App-Trigger In Google Chat wird Ihr Add‑on für Nutzer als Chat-App angezeigt. Nutzer können damit interagieren, indem sie es Gruppenbereichen hinzufügen, Nachrichten senden, Slash-Befehle verwenden usw. Um interaktive Funktionen zu erstellen, richten Sie verschiedene Chat-App-Trigger ein und verwenden sie. Jeder Trigger sendet eine andere Nutzlast des Ereignisobjekts, mit der Sie jede Art von Interaktion verarbeiten oder darauf reagieren können.

Struktur von Ereignisobjekten

In der folgenden Tabelle wird die Struktur der Google Workspace-Add-ons-Ereignisobjekte auf oberster Ebene beschrieben. Die Struktur des Ereignisobjekts enthält ein commonEventObject-Feld der obersten Ebene für hostunabhängige Informationen. Jedes Ereignisobjekt kann auch eines der folgenden hostspezifischen Felder der obersten Ebene haben, die von der aktiven Host-App bestimmt werden: gmailEventObject, calendarEventObject oder driveEventObject.

Zur Abwärtskompatibilität enthalten Google Workspace-Add-ons-Ereignisobjekte auch alle ursprünglichen Felder, die in Gmail-Add-ons-Aktionsereignisobjekten verwendet werden. Diese Felder sind in der Tabelle unten unter „Originalfelder für Gmail-Add-on“ aufgeführt. Die Informationen in diesen Feldern werden in der neuen Objektstruktur wiedergegeben.

Häufiges Ereignisobjekt

Das allgemeine Ereignisobjekt ist der Teil des gesamten Ereignisobjekts, der allgemeine, hostunabhängige Informationen vom Client des Nutzers an das Add-on überträgt. Dazu gehören Details wie das Gebietsschema, die Host-App und die Plattform des Nutzers.

Zusätzlich zu Startseiten- und Kontext-Triggern erstellen Add-ons Ereignisobjekte und übergeben sie an Aktions-Callback-Funktionen, wenn der Nutzer mit Widgets interagiert. Die Callback-Funktion Ihres Add-ons kann das gemeinsame Ereignisobjekt abfragen, um den Inhalt offener Widgets im Client des Nutzers zu ermitteln. Ihr Add-on kann beispielsweise den Text, den ein Nutzer in ein TextInput-Widget eingegeben hat, im eventObject.commentEventObject.formInputs-Objekt finden.

Formulareingaben für die Datums-/Uhrzeitauswahl

Aktions-Callback-Funktionen können aktuelle Widget-Werte im Feld commonEventObject.formInputs empfangen. Dazu gehören die vom Nutzer ausgewählten Datums- oder Zeitwerte in Widgets für die Datums- oder Zeitauswahl. Die Struktur der Informationen hängt jedoch davon ab, ob das Widget als Datum/Uhrzeit-Auswahl, nur als Datumsauswahl oder nur als Uhrzeitauswahl konfiguriert wurde. Die strukturellen Unterschiede werden in der folgenden Tabelle beschrieben:

Chat-Ereignisobjekt

Das Chat-Ereignisobjekt ist der Teil des gesamten Ereignisobjekts, der Informationen zu den Interaktionen eines Nutzers mit einer Chat-App enthält. Es ist nur in einem Ereignisobjekt vorhanden, wenn das Add-on Google Chat erweitert.

Nutzlast

Je nach Art der Chat-App-Interaktion enthält das Ereignis eine Nutzlast mit einer oder mehreren Chat API-Ressourcen.

"docs" : {
  "matchedUrl" : {
      "url" : "https://www.example.com/12345"
  }
}
        

"sheets" : {
  "matchedUrl" : {
      "url" : "https://www.example.com/12345"
  }
}
        

"slides" : {
  "matchedUrl" : {
      "url" : "https://www.example.com/12345"
  }
}