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 nocalendar.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, theeventAttachmentTrigger
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:
- 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.common
andaddOns.calendar
fields to the add-on script project manifest, including any scopes required. - If you are providing a Calendar-specific
homepage,
implement the
calendar.homepageTrigger
function to build this interface. You can also choose to use thecommon.homepageTrigger
interface for multiple Google Workspace hosts. - 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. - 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.