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
calendar.homepageTriggerfunction (if present). This function builds and returns a homepage card to Calendar for display. If no
calendar.homepageTriggerfunction 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
eventOpenTriggerfunction (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
eventAttachmentTriggerfunction, 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
eventAttachmentTriggerfunction 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:
- 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.
- Add the appropriate
addOns.calendarfields to the add-on script project manifest, including any scopes required.
- If you are providing a Calendar-specific
calendar.homepageTriggerfunction to build this interface. You can also choose to use the
common.homepageTriggerinterface for multiple Google Workspace hosts.
- If you are providing a Calendar event interface, you must implement a
calendar.eventOpenTriggerfunction to build this interface. See Extending the Calendar event interface for details.
- Implement the associated callback functions needed to respond to the user's UI interactions, such as button clicks.
Google Calendar supports displaying Google Workspace Add-on homepages.
To show your add-on's common homepage in Google Calendar, simply make sure there
field in the add-on's manifest.
Alternatively, add a
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
objects that make up the homepage. The homepage trigger function is passed an
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
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
field in the add-on manifest.
You must implement the function named in the
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.
An event object is created and
passed to the
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
functions when an add-on is first opened, and when the user clicks or selects
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
that fires when a user opens
a Calendar event for editing, you can also define an
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
manifest field. The function is executed before the Calendar event edit is
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
manifest field to
READ_WRITE. This also
requires the add-on to have the
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.