Stay organized with collections Save and categorize content based on your preferences.
Homepages are a new Google Workspace add-ons feature that provides the ability to define one or more non-contextual cards. Non-contextual cards are used to display a user interface when the user is outside a specific context, such as when the user is viewing their Gmail inbox but hasn't opened a message or draft.
Homepages let you show non-contextual content, just like the Google apps in the quick-access side panel (Keep, Calendar, and Tasks). Homepages can also provide an initial starting place for when a user first opens your add-on, and are useful for teaching new users how to interact with your add-on.
You can define a homepage for your add-on by specifying it in your project manifest and implementing one or more homepageTrigger functions (see Homepage configuration).
You can have multiple homepages, one for each host application that your add-on extends. You can also decide to define a single common default homepage that is used in hosts where you haven't specified a custom homepage.
Your add-on homepage is displayed when one of the following conditions are met:
Navigation.popToRoot() call.Designing a homepage isn't mandatory but highly recommended; if you do not define any, a generic card containing your add-on name is used whenever a user would otherwise navigate to the homepage.
Homepage configurationGoogle Workspace add-ons use the addOns.common.homepageTrigger field to configure the default homepage (non-contextual) add-on content for all host applications in the add-on manifest:
{
// ...
"addOns": {
// ...
"common": {
// ...
"homepageTrigger": {
"runFunction": "myFunction",
"enabled": true
}
}
}
}
runFunction: The name of the Apps Script function that the Google Workspace add-ons framework invokes to render homepage add-on cards. This function is the homepage trigger function. This function must build and return an array of Card objects that make up the homepage UI. If more than one card is returned, the host application shows the card headers in a list that the user can select from (see Returning multiple cards).
enabled: Whether homepage cards should be enabled for this scope. This field is optional, and defaults to true. Setting this to false causes homepage cards to be disabled for all hosts (unless overridden for that host; see below).
addOns.common.homepageTrigger and the host's top-level resource must be present in the add-on manifest. For example, if addOns.gmail isn't present in the manifest, then the add-on is disabled for Gmail and will not show a homepage (or any other functionality in that host).
In addition to the common configuration, there are also identically-structured per-host overrides available in each host application's config, at addOns.gmail.homepageTrigger, addOns.calendar.homepageTrigger, and so forth:
{
...
"addOns": {
...
"common": {
// By default, call 'buildHomePage' to render homepage content
// in all hosts. Since calendar.homepageTrigger below overrides
// this in Calendar and Drive and the homepageTrigger is disabled
// for Gmail, this homepage function never executes.
"homepageTrigger": { "runFunction": "buildHomePage" }
},
"calendar": {
// Show customized homepage content for Calendar only.
"homepageTrigger": { "runFunction": "buildCalendarHomepage" }
},
"drive": {
// Show customized homepage content for Drive only.
"homepageTrigger": { "runFunction": "buildDriveHomepage" }
}
"gmail": {
// Disable homepage add-on content in Gmail.
"homepageTrigger": { "enabled": false }
},
...
}
}
Note that this is equivalent to the following manifest excerpt:
{
...
"addOns": {
...
"common": { /* ... */ }, // Omitted a default homepageTrigger specification.
"calendar": {
// Show customized homepage content for Calendar only.
"homepageTrigger": { "runFunction": "myCalendarFunction" }
},
"drive": {
// Show customized homepage content for Drive only.
"homepageTrigger": { "runFunction": "myDriveFunction" }
}
"gmail": { /* ... */ },
...
}
}
None of the homepageTrigger sections are required. However, the UI shown for an add-on in any given host product depends on the presence of the corresponding manifest field, and whether there's an associated homepageTrigger. The following example shows which add-on trigger functions are executed (if any) to create a homepage UI for different manifest configurations:
When called, the homepage trigger function (runFunction) described above is passed an event object containing data from the invocation context.
Homepage event objects don't include widget or contextual information; the information passed is limited to the following common event object fields:
commonEventObject.clientPlatformcommonEventObject.hostAppcommonEventObject.userLocale and commonEventObject.userTimezone (but see Accessing user locale and timezone for restriction information).See Event object for more details.
Other non-contextual cardsYour add-on UI can contain additional non-contextual cards that aren't homepages. For example, your homepage might have a button that opens a "Settings" card where the user can adjust the add-on settings (such settings would, in most cases, be independent of context and therefore non-contextual).
Non-contextual cards are built like any other card; the only difference is what action or event generates and displays the card. See Navigation methods for details on how to create transitions between cards.
Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License. For details, see the Google Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2025-08-04 UTC.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Missing the information I need","missingTheInformationINeed","thumb-down"],["Too complicated / too many steps","tooComplicatedTooManySteps","thumb-down"],["Out of date","outOfDate","thumb-down"],["Samples / code issue","samplesCodeIssue","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-08-04 UTC."],[[["Homepages in Google Workspace add-ons display non-contextual content, similar to built-in apps like Keep and Calendar, offering a starting point for users."],["You can customize the homepage content by specifying a homepage trigger function in your add-on's manifest, potentially creating different homepages for each supported host application."],["Add-ons can have multiple non-contextual cards, with the homepage acting as the primary entry point and other cards serving specific functions, such as settings or help."],["Although not mandatory, designing a homepage is recommended to improve the user experience, as a generic card is used otherwise."],["Homepage triggers are invoked without contextual information, relying on limited event object fields like client platform, host application, user locale, and timezone."]]],["Google Workspace add-ons can utilize \"homepages,\" which are non-contextual cards displayed when users are outside a specific context or first open an add-on. Developers define homepages in the project manifest using `homepageTrigger` functions, which generate the UI. Multiple homepages can be specified for different host applications, or a default one can be used. Homepages are triggered when the add-on opens, transitions out of context, or navigates to the root. It's highly recommended to create a homepage, else a basic card is used.\n"]]
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4