Building Google Calendar interfaces

Google Workspace Add-ons can provide customized interfaces when the user is viewing or editing calendars and Calendar events. This lets you provide the user with additional relevant information, automate tasks, and connect third-party systems to Google Calendar.

When building an add-on interface for Google Calendar, you can provide a homepage. You can use the same homepage for multiple hosts, or design a specific one for Google Calendar.

Your add-on can also define an interface that appears when the user has a Calendar event open.

Accessing the add-on UI

Depending on how it's opened, a Google Workspace Add-on can define a homepage interface, a Google Calendar event interface, an attachment selection interface, or all three:

  • If a user clicks the add-on icon while in a calendar view, the add-on executes the corresponding calendar.homepageTrigger function (if present). This function builds and returns a homepage card to Calendar for display. If no calendar.homepageTrigger function is defined, a generic homepage card is displayed instead.
  • If the user opens a Calendar event and then clicks the add-on icon, or the add-on is open when the user opens an event, the add-on executes the corresponding eventOpenTrigger function (if present). This function builds the add-on's Calendar event interface and returns to Google Calendar for display.
  • If the add-on defines an eventAttachmentTrigger function, the add-on appears as an attachment provider when the user clicks Add attachment while editing a Calendar event. When the add-on is selected, the eventAttachmentTrigger function builds the add-on's attachment selection interface and returns it to Google Calendar for display.

Building the add-on Calendar interface

You can extend Google Calendar with a Google Workspace Add-on by following these steps:

  1. Decide whether you want your add-on to have a Calendar-specific homepage. Also decide if you want to provide a custom interface while the user is editing Calendar events.
  2. Add the appropriate addOns.common and addOns.calendar fields to the add-on script project manifest, including any scopes required.
  3. If you are providing a Calendar-specific homepage, implement the calendar.homepageTrigger function to build this interface. You can also choose to use the common.homepageTrigger interface for multiple Google Workspace hosts.
  4. If you are providing a Calendar event interface, you must implement a calendar.eventOpenTrigger function to build this interface. See Extending the Calendar event interface for details.
  5. Implement the associated callback functions needed to respond to the user's UI interactions, such as button clicks.

Calendar homepages

Google Calendar supports displaying Google Workspace Add-on homepages. To show your add-on's common homepage in Google Calendar, simply make sure there is an addOns.calendar field in the add-on's manifest.

Alternatively, add a calendar.homepageTrigger to the add-on manifest to provide a Calendar-specific homepage.

In either case, you must provide the name of a homepage trigger function in your add-on's script project. This function is automatically called to build the Google Calendar homepage when it is needed. You must implement this function to build and return a single Card or an array of Card objects that make up the homepage. The homepage trigger function is passed an event object as a parameter that contains some general information such as the client's platform. You can use the event object data to tailor the construction of the homepage.

Extending the Calendar event interface

Google Calendar relies on a contextual trigger to determine what interface (if any) to display when the user edits a Calendar event. When the trigger fires, it executes the contextual trigger function specified by the calendar.eventOpenTrigger field in the add-on manifest.

You must implement the function named in the calendar.eventOpenTrigger field. This function accepts an event object as an argument and must return either a single Card object or an array of Card objects for Calendar to display while the user has the event open.

Event objects

An event object is created and passed to the calendar.eventOpenTrigger contextual trigger function when a user opens a Calendar event. The trigger function can use the information in this event object to determine how to construct add-on cards or control the add-on behavior. Event objects are also created and passed to homepageTrigger functions when an add-on is first opened, and when the user clicks or selects interactive widgets.

The full structure of event objects is described in Event objects. When Calendar is the acting host app of the add-on, contextual trigger and widget interaction event objects include the Calendar event object field that carries Calendar-specific client information.

Updating Calendar events

In addition to the contextual calendar.eventOpenTrigger that fires when a user opens a Calendar event for editing, you can also define an calendar.eventUpdateTrigger that fires when the user updates and saves a Calendar event. This trigger only fires if the user makes one or more of the following edits:

  • Adds one or more attendees.
  • Removes one or more attendees.
  • Adds or switches to a different conferencing solution.

When this trigger fires, it executes the trigger function specified by the calendar.eventUpdateTrigger manifest field. The function is executed before the Calendar event edit is saved.

The calendar.eventUpdateTrigger is typically used to do one or more of the following:

  • Update the add-on's Calendar event interface in response to user changes to the Calendar event.
  • Sync Calendar event data with a third-party system, such as a conferencing system that is connected to Google Calendar.

If you need your add-on to make adjustments to a Calendar event's data (such as its attendee list), you must set the add-on calendar.currentEventAccess manifest field to WRITE or READ_WRITE. This also requires the add-on to have the https://www.googleapis.com/auth/calendar.addons.current.event.write scope.

Adding conferencing solutions

Conferencing solutions represent a third-party conference options that users can attach to Google Calendar events. The Third-party conferencing overview documentation provides details on how to build an add-on that adds new conferencing solutions. It isn't necessary to build a UI for this type of extension; added solutions simply appear as options in the drop-down menu of the Google Calendar event UI.