*Homepages* are an Google Workspace add-ons feature that provides the ability to define
one or more *non-contextual cards*. Non-contextual cards display a user
interface when the user is outside a specific context, such as when viewing
their Gmail inbox without an open message or draft.

Homepages let you show non-contextual content, similar to the Google apps in
the [quick-access side panel](https://workspaceupdates.googleblog.com/2018/08/use-quick-access-side-panel-to-do-more.html)
(Google Keep, Google Calendar, and Google Tasks). Homepages can also
provide an initial starting place when a user first opens your
add-on and are useful for teaching new users how to
interact with your add-on.

Define a homepage for your add-on by specifying it in
your project manifest and implementing one or more `homepageTrigger`
functions (see [Homepage configuration](https://developers.google.com/workspace/add-ons/concepts/homepages#homepage_configuration)). If your
add-on extends Google Chat, its homepage appears in
the **Home** tab of a 1:1 direct message with the
Chat app and is configured in the Google Cloud console
instead of the manifest (see
[Configure a homepage for Chat](https://developers.google.com/workspace/add-ons/concepts/homepages#chat-homepages)).

You can have multiple homepages, one for each host application that your
add-on extends. You can also 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 in these cases:

- When the add-on is first opened in the host (after authorization), or when a user opens the **Home** tab in a 1:1 direct message with your Chat app in Chat.
- When the user switches from a contextual context to a non-contextual context while the add-on is open. For example, from editing a Calendar event to the main Calendar.
- When the user clicks the back button enough times to [pop every other card
  off of the internal stacks](https://developers.google.com/workspace/add-ons/how-tos/navigation).
- When a UI interaction in a non-contextual card results in a [`Navigation.popToRoot`](https://developers.google.com/apps-script/reference/card-service/navigation#popToRoot()) call.

Designing a homepage is recommended. If you don't define any, a generic card
containing your add-on name is used whenever a user
navigates to the homepage.

## Homepage configuration

Google Workspace add-ons use the [`addOns.common.homepageTrigger`](https://developers.google.com/apps-script/manifest/addons#Common.FIELDS.homepageTrigger) field to
configure the default homepage (non-contextual)
add-on content for host applications in the
add-on [manifest](https://developers.google.com/workspace/add-ons/concepts/workspace-manifests):

    {
      "addOns": {
        "common": {
          "homepageTrigger": {
            "runFunction": "myFunction",
            "enabled": true
          }
        }
      }
    }

- `runFunction`: The name of the Google 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`](https://developers.google.com/apps-script/reference/card-service/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](https://developers.google.com/workspace/add-ons/how-tos/navigation#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 the host-specific configuration).

For a host to use the common homepage, both
[`addOns.common.homepageTrigger`](https://developers.google.com/apps-script/manifest/addons#Common.FIELDS.homepageTrigger) and the host's
top-level resource must be present in the add-on [manifest](https://developers.google.com/workspace/add-ons/concepts/workspace-manifests). For example, if
[`addOns.gmail`](https://developers.google.com/apps-script/manifest/addons#AddOns.FIELDS.gmail) isn't
present in the manifest, then the add-on is disabled
for Gmail and won't show a homepage or other functionality in
that host.

In addition to the common configuration, identically-structured per-host
overrides are available in each host application's config, at
`addOns.gmail.homepageTrigger`, `addOns.calendar.homepageTrigger`, and other
host-specific triggers.

The following example shows a manifest where a common homepage trigger is
defined but is overridden with custom functions for Calendar and
Drive, and disabled for Gmail. In this
configuration, the common `buildHomePage` function never executes because it is
either overridden or the host is disabled.

    {
      ...
      "addOns": {
        ...
        "common": {
          "homepageTrigger": { "runFunction": "buildHomePage" }
        },
        "calendar": {
          "homepageTrigger": { "runFunction": "buildCalendarHomepage" }
        },
        "drive": {
          "homepageTrigger": { "runFunction": "buildDriveHomepage" }
        },
        "gmail": {
          "homepageTrigger": { "enabled": false }
        },
        ...
      }
    }

The following manifest excerpt is equivalent to the previous example, even
though the default `homepageTrigger` and the Gmail configuration
are omitted:

    {
      "addOns": {
        "common": {},
        "calendar": {
          "homepageTrigger": { "runFunction": "myCalendarFunction" }
        },
        "drive": {
          "homepageTrigger": { "runFunction": "myDriveFunction" }
        },
        "gmail": {},
        ...
      }
    }

None of the `homepageTrigger` sections are required. The UI shown for an
add-on in a 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 to create a
homepage UI for different manifest configurations:

![Diagram showing add-on homepage trigger function execution flow](https://developers.google.com/static/workspace/add-ons/images/addon-homepage-flow.png)

### Configure a homepage for Chat

Unlike other Google Workspace host applications, add-ons that
extend Chat don't display a homepage in the right-side quick
access panel and don't use `addOns.common.homepageTrigger` in the manifest.
Instead, Chat displays your homepage as a card in the **Home**
tab of a 1:1 direct message with the Chat app.

To enable and configure an App Home trigger for your Chat
add-on in the Google Cloud console:

1. In the Google Cloud console, go to **Menu \> APIs \& Services \> Enabled APIs \&
   services \> Google Chat API \> Configuration**.

   [Go to Google Chat API Configuration](https://console.cloud.google.com/apis/api/chat.googleapis.com/hangouts-chat)
2. Under **Interactive features** , make sure **Enable interactive features** is
   turned on, and then select the **Support App Home** checkbox.

3. Under **Connection settings \> Triggers** , specify your App Home handler in
   the **App home** field based on your add-on
   architecture:

   - **HTTP**: Enter the HTTPS endpoint URL that handles App Home requests (or leave it blank so your common HTTP endpoint URL receives all events).
   - **Google Apps Script** : Enter the name of the Google Apps Script callback function that builds and returns your homepage card (defaults to `onAppHome`).
4. Click **Save**.

When a user opens the **Home** tab of a direct message with your
Chat app, Chat sends an **App Home**
trigger event to your endpoint or function. To render the homepage, return a
[`RenderActions`](https://developers.google.com/workspace/add-ons/reference/rpc/google.apps.card.v1#renderactions)
object with a `pushCard` navigation action (or use `updateCard` when updating
the homepage in response to clicking a button in the homepage card):

### HTTP

```json
{
  "action": {
    "navigations": [
      {
        "pushCard": {
          "header": {
            "title": "Welcome to App Home"
          },
          "sections": [
            {
              "widgets": [
                {
                  "textParagraph": {
                    "text": "Manage your settings and view your dashboard here."
                  }
                }
              ]
            }
          ]
        }
      }
    ]
  }
}
```

### Google Apps Script

```javascript
function onAppHome(event) {
  const card = CardService.newCardBuilder()
      .setHeader(
          CardService.newCardHeader().setTitle('Welcome to App Home'))
      .addSection(
          CardService.newCardSection().addWidget(
              CardService.newTextParagraph().setText(
                  'Manage your settings and view your dashboard here.')))
      .build();

  return CardService.newActionResponseBuilder()
      .setNavigation(CardService.newNavigation().pushCard(card))
      .build();
}
```

For more details on handling Chat triggers, returning actions,
and building an App Home card, see
[Send and update an App Home card](https://developers.google.com/workspace/chat/send-app-home-card-message)
and [Receive and respond to user interactions](https://developers.google.com/workspace/chat/receive-respond-interactions).

### Homepage event objects

When called, the homepage trigger function (`runFunction`) or App Home endpoint
described previously is passed an
[event object](https://developers.google.com/workspace/add-ons/concepts/event-objects) containing data from
the invocation context.

Homepage event objects don't include widget or contextual information. The
information passed includes the following
[common event object](https://developers.google.com/workspace/add-ons/concepts/event-objects)
fields:

- `commonEventObject.clientPlatform`
- `commonEventObject.hostApp`
- `commonEventObject.userLocale` and `commonEventObject.userTimezone` (see [Accessing user locale and timezone](https://developers.google.com/workspace/add-ons/how-tos/access-user-locale) for restriction information).

In Chat, the App Home event object also includes the `chat`
field with information about the user and interaction time:

- `chat.user`: The [Chat user](https://developers.google.com/workspace/chat/api/reference/rest/v1/User) who opened the **Home** tab.
- `chat.eventTime`: The timestamp when the user opened the **Home** tab.

See [Event object](https://developers.google.com/workspace/add-ons/concepts/event-objects) for more details.

## Other non-contextual cards

Your 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 to adjust add-on
settings (such settings are usually independent of context).

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](https://developers.google.com/workspace/add-ons/how-tos/navigation#navigation_methods)
for details on how to create transitions between cards.