Event objects

AI-generated Key Takeaways

outlined_flag

• Event objects are JSON structures that provide context and user interaction data to Google Workspace add-ons.

• They consist of a commonEventObject for general information and host-specific objects like calendarEventObject or driveEventObject.

• Developers should prioritize the new event structure and avoid deprecated Gmail add-on fields.

• Accessing event object data depends on widget type, host app, and required permissions defined in the manifest.

• Understanding the structure of formInputs, calendar event details, attendee information, and Drive item data is crucial for effective add-on functionality.

This page outlines the structure of Google Workspace add-ons event objects.

Event objects are JSON structures that are automatically constructed and passed as parameters to trigger or callback functions when a user interacts with an add-on. Event objects carry client-side information about the host app and the current context to the add-on's server-side callback function.

Google Workspace add-ons use event objects in the following places:

• Homepage triggers. Every homepageTrigger function you define is automatically passed an event object when the homepage trigger function fires. You can use this object in your homepage trigger function to identify the active host app, the client's platform, the user locale, and other information.

  The event objects created when homepage triggers fire don't contain all the fields included in the other two cases; fields pertaining to widgets and contextual information are omitted.

• Contextual triggers. Each host application provides a different set of contextual triggers that fire when the user enters a specific context. For example:

  • Gmail provides a contextual trigger for when a user opens a message and another when a user composes a message.
  • Google Calendar provides a contextual trigger for when a user opens an event.
  • Google Drive provides a contextual trigger for when a user selects Drive files.

  When a contextual trigger fires, the host application calls the corresponding runFunction listed in the add-on manifest, passing it an event object as a parameter. The event objects created when contextual triggers fire contain all the fields included in homepage trigger event objects, plus fields containing contextual information.

• Widget actions. Event objects are also used to provide widget interactivity, using the same action model that Gmail add-ons use. Google Workspace add-ons use all the same widget handler functions, Action objects, and action responses. However, in Google Workspace add-ons the action event objects include even more information a callback function can act on.

  The event objects created as the result of widget actions contain all the fields included in contextual trigger event objects, plus fields containing widget information.

• Preview link triggers. In Google Docs, Sheets, and Slides, you can configure link previews for third-party services based on specific URL patterns. When users interact with a link that meets the pattern, the linkPreviewTriggers fires and an event object that contains the link is passed to the trigger's callback function. Your add-on can use this event object to construct a smart chip and card that surfaces information about the link within the host application. You can also build widget actions to let users interact with the preview card and its contents.

• Google Chat app triggers. In Google Chat, your add-on appears to users as a Chat app, and users can interact with it by adding it to spaces, sending messages, using slash commands, and more. To build interactive features, you set up and use various Chat app triggers. Each trigger sends a different event object payload that helps you process or respond to each type of interaction.

Event object structure

The following table describes the top-level structure of Google Workspace add-ons event objects. The event object structure includes a commonEventObject top-level field for host-independent information. Each event object can also have one of the following host-specific top-level fields, determined by the active host app: gmailEventObject, calendarEventObject, or driveEventObject.

For backward compatibility, Google Workspace add-ons event objects also include all the original fields used in Gmail add-on action event objects. These fields are listed in the table below under "Original Gmail add-on fields"; the information in these fields is reproduced in new object structure.

Common event object

The common event object is the portion of the overall event object that carries general, host-independent information to the add-on from the user's client. This information includes details such as the user's locale, host app, and platform.

In addition to homepage and contextual triggers, add-ons construct and pass event objects to action callback functions when the user interacts with widgets. Your add-on's callback function can query the common event object to determine the contents of open widgets in the user's client. For example, your add-on can locate the text a user has entered into a TextInput widget in the eventObject.commentEventObject.formInputs object.

Date-time picker form inputs

Action callback functions can receive current widget values in the commonEventObject.formInputs field. This includes the user's selected date or time values in date or time picker widgets. However, the structure of the information differs depending on whether the widget was configured as a date-time picker, a date-only picker, or a time-only picker. The structural differences are described in the following table:

Chat event object

The Chat event object is the portion of the overall event object that carries information about a user's interactions with a Chat app. It's only present in an event object if the add-on extends Google Chat.

Payload

Depending on the type of Chat app interaction, the event contains a payload with one or more Chat API resources.

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

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

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