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 übertragen clientseitige Informationen zur Host-App und zum aktuellen Kontext an die serverseitige Rückruffunktion des Add-ons.

In Google Workspace-Add-ons werden Ereignisobjekte an den folgenden Stellen verwendet:

• Startseitentrigger Jede von Ihnen definierte homepageTrigger-Funktion erhält automatisch ein Ereignisobjekt, wenn die Triggerfunktion für die Startseite ausgelöst wird. Sie können dieses Objekt in Ihrer Startseiten-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 Startseitenauslösern erstellt werden, enthalten nicht alle Felder, die in den anderen beiden Fällen enthalten sind. Felder zu Widgets und Kontextinformationen werden weggelassen.

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

  • Gmail bietet einen kontextbezogenen Trigger, wenn ein Nutzer eine Nachricht öffnet, und einen weiteren, wenn er eine Nachricht verfasst.
  • Google Kalender bietet einen kontextbezogenen Trigger, wenn ein Nutzer einen Termin öffnet.
  • Google Drive bietet einen kontextbezogenen Trigger, 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 von Kontexttriggern erstellt werden, enthalten alle Felder, die in Ereignisobjekten für Startseitentrigger enthalten sind, sowie Felder mit Kontextinformationen.

• Widget-Aktionen Ereignisobjekte werden auch verwendet, um Widgets interaktiv zu gestalten. Dabei wird dasselbe Aktionsmodell verwendet, das auch in Gmail-Add-ons verwendet wird. Für Google Workspace-Add-ons werden dieselben Widget-Handlerfunktionen, Action-Objekte und Aktionsantworten verwendet. In Google Workspace-Add-ons enthalten die Ereignisobjekte für Aktionen jedoch noch mehr Informationen, auf die eine Rückruffunktion reagieren kann.

  Die Ereignisobjekte, die durch Widget-Aktionen erstellt werden, enthalten alle Felder, die in Ereignisobjekten für kontextbezogene Trigger enthalten sind, sowie Felder mit Widget-Informationen.

• Auslöser für Vorschaulinks In Google Docs, Google Tabellen und Google Präsentationen können Sie Linkvorschaubilder für Drittanbieterdienste basierend auf bestimmten URL-Mustern konfigurieren. Wenn Nutzer mit einem Link interagieren, der dem Muster entspricht, wird das Ereignis linkPreviewTriggers ausgelöst und ein Ereignisobjekt mit dem Link wird an die Rückruffunktion des Trigger übergeben. Ihr Add-on kann dieses Ereignisobjekt verwenden, um einen Smartchip und eine Karte zu erstellen, die Informationen zum Link in der Hostanwendung anzeigen. Sie können auch Widget-Aktionen erstellen, damit Nutzer mit der Vorschaukarte und ihren Inhalten interagieren können.

• Trigger für die Google Chat App (Entwicklervorabversion) In Google Chat wird Ihr Add-on Nutzern als Chat-App angezeigt. Sie können damit interagieren, indem sie es Gruppenbereichen hinzufügen, Nachrichten senden und Slash-Befehle verwenden. Um interaktive Funktionen zu erstellen, richten Sie verschiedene Trigger für Chat-Apps ein und verwenden diese. 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 Ereignisobjekte von Google Workspace-Add-ons auf oberster Ebene beschrieben. Die Ereignisobjektstruktur enthält ein übergeordnetes Feld vom Typ commonEventObject für hostunabhängige Informationen. Jedes Ereignisobjekt kann auch eines der folgenden hostspezifischen Felder der obersten Ebene haben, das von der aktiven Host-App bestimmt wird: gmailEventObject, calendarEventObject oder driveEventObject.

Aus Gründen der Abwärtskompatibilität enthalten Ereignisobjekte für Google Workspace-Add-ons auch alle ursprünglichen Felder, die in Ereignisobjekten für Gmail-Add-on-Aktionen verwendet wurden. Diese Felder sind in der Tabelle unten unter „Originale Gmail-Add-on-Felder“ aufgeführt. Die Informationen in diesen Feldern werden in der neuen Objektstruktur reproduziert.

Gemeinsames Ereignisobjekt

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

Zusätzlich zu Startseiten- und Kontexttriggern 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 der geöffneten Widgets im Client des Nutzers zu ermitteln. Ihr Add-on kann beispielsweise den Text finden, den ein Nutzer in ein TextInput-Widget im eventObject.commentEventObject.formInputs-Objekt eingegeben hat.

Eingaben für die Datums-/Zeitauswahl

Aktion-Callback-Funktionen können aktuelle Widget-Werte im Feld commonEventObject.formInputs empfangen. Dazu gehören auch die vom Nutzer ausgewählten Datums- oder Uhrzeitwerte in Widgets für Datumsauswahl oder Uhrzeitauswahl. Die Struktur der Informationen unterscheidet sich jedoch je nachdem, ob das Widget als Datumsauswahl, Datumsauswahl oder Uhrzeitauswahl konfiguriert wurde. Die strukturellen Unterschiede werden in der folgenden Tabelle beschrieben:

Kalenderterminobjekt

Das Kalenderereignisobjekt ist der Teil des gesamten Ereignisobjekts, der Informationen zum Kalender und zu den Kalenderterminen eines Nutzers enthält. Es ist nur in einem Ereignisobjekt vorhanden, wenn die Hostanwendung Google Kalender ist.

In der folgenden Tabelle sind die Felder aufgeführt, die im Feld calendarEventObject eines Ereignisobjekts enthalten sind. Felder, die als Nutzergenerierte Daten gekennzeichnet sind, sind nur dann im Ereignisobjekt vorhanden, wenn die Daten im Kalenderereignis vorhanden sind und das Add-on das Feld addOns.calendar.currentEventAccess manifest auf READ oder READ_WRITE festlegt.

Teilnehmer

Teilnehmerobjekte enthalten Informationen zu einzelnen Teilnehmern an Google Kalender-Terminen. Diese Informationen sind nur dann im Ereignisobjekt vorhanden, wenn die Daten im Kalenderereignis vorhanden sind und das Add-on das Feld addOns.calendar.currentEventAccess manifest auf READ oder READ_WRITE festlegt.

Konferenzdaten

Konferenzdatenobjekte enthalten Informationen zu Konferenzen, die an Google Kalender-Termine angehängt sind. Das können Konferenzlösungen von Google wie Google Meet oder Konferenzen von Drittanbietern sein. Diese Informationen sind nur dann im Ereignisobjekt vorhanden, wenn die Daten im Kalenderereignis vorhanden sind und das Add-on das Feld addOns.calendar.currentEventAccess manifest auf READ oder READ_WRITE festlegt.

Einstiegspunkt

Einstiegspunktobjekte enthalten Informationen zu den festgelegten Zugriffsmethoden für eine bestimmte Konferenz, z. B. per Telefon oder Video. Diese Informationen sind nur dann im Ereignisobjekt vorhanden, wenn die Daten im Kalenderereignis vorhanden sind und das Add-on das Feld addOns.calendar.currentEventAccess manifest auf READ oder READ_WRITE festlegt.

Drive-Ereignisobjekt

Das Drive-Ereignisobjekt ist der Teil des gesamten Ereignisobjekts, der Informationen zu Google Drive und den Inhalten eines Nutzers enthält. Es ist nur in einem Ereignisobjekt vorhanden, wenn die Hostanwendung Google Drive ist.

Drive-Element

Drive-Elementobjekte enthalten Informationen zu bestimmten Drive-Elementen, z. B. Dateien oder Ordnern.

Gmail-Ereignisobjekt

Das Gmail-Ereignisobjekt ist der Teil des gesamten Ereignisobjekts, der Informationen zu den Gmail-Nachrichten eines Nutzers enthält. Es ist nur in einem Ereignisobjekt vorhanden, wenn die Hostanwendung Gmail ist.

Google Docs-Ereignisobjekt

Das Docs-Ereignisobjekt ist der Teil des gesamten Ereignisobjekts, der Informationen zum Dokument eines Nutzers und seinem Inhalt enthält. Sie ist nur in einem Ereignisobjekt vorhanden, wenn die Hostanwendung Google Docs ist.

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

Google Tabellen-Ereignisobjekt

Das Google Tabellen-Ereignisobjekt ist der Teil des gesamten Ereignisobjekts, der Informationen zum Dokument eines Nutzers und seinem Inhalt enthält. Sie ist nur in einem Ereignisobjekt vorhanden, wenn die Hostanwendung Google Tabellen ist.

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

Ereignisobjekt für Google Präsentationen

Das Ereignisobjekt „Präsentationen“ ist der Teil des gesamten Ereignisobjekts, der Informationen zum Dokument eines Nutzers und seinem Inhalt enthält. Es ist nur in einem Ereignisobjekt vorhanden, wenn die Hostanwendung Google Präsentationen ist.

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