首頁

首頁是 Google Workspace 外掛程式功能，可定義一或多張非情境式資訊卡。如果使用者不在特定情境中 (例如在查看 Gmail 收件匣時，沒有開啟任何郵件或草稿)，系統就會顯示非情境式資訊卡。

首頁可顯示非情境式內容，類似於快速存取側邊面板中的 Google 應用程式 (Google Keep、Google 日曆和 Google Tasks)。使用者初次開啟外掛程式時，首頁也能做為初始起點，並教導新使用者如何與外掛程式互動。

在專案資訊清單中指定外掛程式的首頁，並實作一或多個 homepageTrigger 函式 (請參閱「首頁設定」)。如果外掛程式會擴充 Google Chat，其首頁會顯示在與 Chat 應用程式的 1:1 即時訊息「首頁」分頁中，並在 Google Cloud 控制台中設定，而非資訊清單 (請參閱「設定 Chat 的首頁」)。

您可以有多個首頁，每個首頁對應一個外掛程式擴充的主機應用程式。您也可以定義單一通用預設首頁，用於未指定自訂首頁的主機。

在下列情況下，系統會顯示外掛程式首頁：

  • 在主機中首次開啟外掛程式時 (授權後)，或使用者在與 Chat 應用程式的 1:1 直接訊息中開啟「首頁」分頁時。
  • 使用者在開啟外掛程式時，從內容關聯環境切換至非內容關聯環境。例如從編輯日曆活動到主要日曆。
  • 使用者點選返回按鈕的次數足夠多，可從內部堆疊中彈出其他所有卡片。
  • 當非脈絡資訊卡中的 UI 互動導致 Navigation.popToRoot 呼叫時。

建議設計首頁。如果未定義任何卡片，使用者前往首頁時，系統會使用含有外掛程式名稱的通用資訊卡。

首頁設定

Google Workspace 外掛程式會使用 addOns.common.homepageTrigger 欄位，在附加元件資訊清單中，為主機應用程式設定預設首頁 (非情境式) 外掛程式內容：

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

  • runFunction：Google Workspace 外掛程式架構會叫用這個 Google Apps Script 函式，以算繪外掛程式首頁資訊卡。這個函式是首頁觸發函式。這個函式必須建構並傳回 Card 物件的陣列，這些物件會組成首頁 UI。如果傳回多張資訊卡，主機應用程式會將資訊卡標題顯示在清單中，供使用者選取 (請參閱「傳回多張資訊卡」)。

  • enabled：是否應為這個範圍啟用首頁資訊卡。這個欄位為選填，預設值為 true。設為 false 時，所有主機都會停用首頁資訊卡 (除非該主機已覆寫設定；請參閱主機專屬設定)。

如要讓主機使用通用首頁，外掛程式資訊清單中必須同時包含 addOns.common.homepageTrigger 和主機的頂層資源。舉例來說，如果資訊清單中沒有 addOns.gmail，外掛程式就會在 Gmail 中停用，且不會在該主機中顯示首頁或其他功能。

除了常見設定外，每個主機應用程式的設定中，都有結構相同的每個主機覆寫值，位於 addOns.gmail.homepageTrigger、addOns.calendar.homepageTrigger 和其他主機專屬觸發程序。

以下範例顯示資訊清單，其中定義了常見的首頁觸發條件，但日曆和雲端硬碟會覆寫該條件，並停用 Gmail 的觸發條件。在這個設定中，系統永遠不會執行常見的 buildHomePage 函式，因為該函式遭到覆寫或主機已停用。

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

即使省略預設 homepageTrigger 和 Gmail 設定，下列資訊清單摘錄內容仍與上一個範例等效：

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

所有homepageTrigger部分皆為選填。主機產品中顯示的附加元件使用者介面，取決於是否有對應的資訊清單欄位，以及是否有相關聯的 homepageTrigger。以下範例顯示執行哪些外掛程式觸發函式，可為不同資訊清單設定建立首頁 UI：

圖表：顯示外掛程式首頁觸發函式的執行流程

設定 Chat 的首頁

與其他 Google Workspace 主機應用程式不同，擴充 Chat 的外掛程式不會在右側快速存取面板中顯示首頁，也不會在資訊清單中使用 addOns.common.homepageTrigger。Chat 會在與 Chat 擴充應用程式的 1:1 即時訊息中，將首頁顯示為「首頁」分頁中的資訊卡。

如要在 Google Cloud 控制台中啟用及設定 Chat 外掛程式的應用程式主畫面觸發條件，請按照下列步驟操作：

  1. 在 Google Cloud 控制台中，依序前往「選單」>「API 和服務」>「已啟用的 API 和服務」>「Google Chat API」>「設定」。

    前往 Google Chat API 設定

  2. 在「互動功能」下方，確認「啟用互動功能」已開啟，然後勾選「支援應用程式首頁」核取方塊。

  3. 在「連線設定」>「觸發條件」下方，根據外掛程式架構，在「應用程式主頁面」欄位中指定應用程式主頁面處理常式：

    • HTTP：輸入處理應用程式首頁要求的 HTTPS 端點網址 (或留空，讓通用 HTTP 端點網址接收所有事件)。
    • Google Apps Script：輸入 Google Apps Script 回呼函式的名稱，該函式會建構並傳回首頁資訊卡 (預設為 onAppHome)。

  4. 按一下 [儲存]。

使用者開啟與 Chat 應用程式的即時訊息時，Chat 會將應用程式首頁觸發事件傳送至端點或函式。如要算繪首頁，請傳回具有 pushCard 導覽動作的 RenderActions 物件 (或在更新首頁時使用 updateCard，以回應點按首頁資訊卡中的按鈕)：

HTTP

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

Google Apps Script

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();
}

如要進一步瞭解如何處理 Chat 觸發條件及傳回動作，請參閱「接收及回應使用者互動」。

首頁活動物件

呼叫時，首頁觸發函式 (runFunction) 或先前所述的應用程式首頁端點會傳遞 event 物件，其中包含來自叫用環境的資料。

首頁事件物件不包含小工具或背景資訊。傳遞的資訊包括下列通用事件物件欄位：

  • commonEventObject.clientPlatform
  • commonEventObject.hostApp
  • commonEventObject.userLocale 和 commonEventObject.userTimezone (如需限制資訊，請參閱「存取使用者語言代碼和時區」)。

在 Chat 中，App 主畫面事件物件也包含 chat 欄位，其中含有使用者和互動時間的相關資訊：

  • chat.user：開啟「首頁」分頁的 Chat 使用者。
  • chat.eventTime：使用者開啟「首頁」分頁的時間戳記。

詳情請參閱「事件物件」。

其他非情境式資訊卡

外掛程式 UI 可以包含其他非脈絡卡片，這些卡片並非首頁。舉例來說，首頁可能會有一個按鈕，可開啟「設定」資訊卡來調整外掛程式設定 (這類設定通常與內容無關)。

非情境式資訊卡的建構方式與其他資訊卡相同，唯一的差異在於產生及顯示資訊卡的動作或事件。如要進一步瞭解如何建立卡片之間的轉場效果，請參閱「導覽方法」。