建構 Google Chat 應用程式的首頁

本頁說明如何為 Google Chat 應用程式。應用程式首頁是可自訂的資訊卡介面 Chat 應用程式傳送給使用者 傳送訊息。

顯示兩個小工具的應用程式首頁資訊卡。

舉例來說: 設定應用程式首頁資訊卡訊息,納入與 使用 Chat 擴充應用程式 斜線指令。對使用者而言,應用程式首頁是 這項功能僅適用於 Chat 應用程式的即時訊息, 這項功能是由應用程式開發人員 啟用


您可以使用 Card Builder 設計及預覽即時通訊應用程式的 JSON 資訊卡訊息:

開啟資訊卡建立工具

必要條件

Python

已啟用互動功能的 Google Chat 應用程式。如要建立 請使用 HTTP 服務互動式即時通訊應用程式,請完成快速入門導覽課程

Apps Script

已啟用互動功能的 Google Chat 應用程式。如要建立 ,請完成快速入門導覽課程

Node.js

已啟用互動功能的 Google Chat 應用程式。如要建立 請使用 HTTP 服務互動式即時通訊應用程式,請完成快速入門導覽課程

Java

已啟用互動功能的 Google Chat 應用程式。如要建立 請使用 HTTP 服務互動式即時通訊應用程式,請完成快速入門導覽課程

設定 Chat API

如要支援應用程式首頁,請更新 Chat API 設定 也能前往 Google Cloud 控制台

Python

  1. 前往 Google Cloud 控制台中的「選單」 >「更多產品」 > Google Workspace > 產品庫 > Google Chat API

    前往 Google Chat API

  2. 依序按一下「管理」和「設定」分頁標籤。

  3. 勾選「支援應用程式首頁」核取方塊。

  4. 在「應用程式首頁網址」欄位中新增網址。這個值通常會相同 設為「應用程式網址」。系統會呼叫 這個網址 APP_HOME 事件

  5. 按一下 [儲存]

Apps Script

  1. 前往 Google Cloud 控制台中的「選單」 >「更多產品」 > Google Workspace > 產品庫 > Google Chat API

    前往 Google Chat API

  2. 依序按一下「管理」和「設定」分頁標籤。

  3. 勾選「支援應用程式首頁」核取方塊。

  4. 按一下 [儲存]

Node.js

  1. 前往 Google Cloud 控制台中的「選單」 >「更多產品」 > Google Workspace > 產品庫 > Google Chat API

    前往 Google Chat API

  2. 依序按一下「管理」和「設定」分頁標籤。

  3. 勾選「支援應用程式首頁」核取方塊。

  4. 在「應用程式首頁網址」欄位中新增網址。這個值通常會相同 設為「應用程式網址」。系統會呼叫 這個網址 APP_HOME 事件

  5. 按一下 [儲存]

Java

  1. 前往 Google Cloud 控制台中的「選單」 >「更多產品」 > Google Workspace > 產品庫 > Google Chat API

    前往 Google Chat API

  2. 依序按一下「管理」和「設定」分頁標籤。

  3. 勾選「支援應用程式首頁」核取方塊。

  4. 在「應用程式首頁網址」欄位中新增網址。這個值通常會相同 設為「應用程式網址」。系統會呼叫 這個網址 APP_HOME 事件

  5. 按一下 [儲存]

建構應用程式首頁

當使用者透過 Chat 應用程式,且可以更新做為 像是按鈕點擊、表單提交或對話方塊關閉等互動事件

在以下範例中,Chat 應用程式會顯示 初始應用程式首頁資訊卡會顯示卡片建立時間 即可。使用者點選按鈕後,Chat 應用程式 會傳回更新過的資訊卡,以顯示更新卡片的時間。

建立應用程式首頁的初始資訊卡

如要建構應用程式首頁,Chat 應用程式必須處理 APP_HOME 互動事件並傳回 RenderActions (導航模式為 pushCard)。

Python

python/app-home/main.py
@app.route('/', methods=['POST'])
def post() -> Mapping[str, Any]:
  """Handle requests from Google Chat

  Returns:
      Mapping[str, Any]: the response
  """
  event = request.get_json()
  match event['chat'].get('type'):

    case 'APP_HOME':
      # App home is requested
      body = { "action": { "navigations": [{
        "pushCard": get_home_card()
      }]}}

    case 'SUBMIT_FORM':
      # The update button from app home is clicked
      event_object = event.get('commonEventObject')
      if event_object is not None:
        if 'update_app_home' == event_object.get('invokedFunction'):
          body = update_app_home()

    case _:
      # Other response types are not supported
      body = {}

  return json.jsonify(body)


def get_home_card() -> Mapping[str, Any]:
  """Create the app home card

  Returns:
      Mapping[str, Any]: the card
  """
  return { "sections": [{ "widgets": [
    { "textParagraph": {
      "text": "Here is the app home 🏠 It's " +
        datetime.datetime.now().isoformat()
    }},
    { "buttonList": { "buttons": [{
      "text": "Update app home",
      "onClick": { "action": {
        "function": "update_app_home"
      }}
    }]}}
  ]}]}

Apps Script

實作在所有 APP_HOME 事件之後呼叫的 onAppHome 函式:

此範例會透過 資訊卡 JSON。 您也可以使用 Apps Script Card 服務

apps-script/app-home/app-home.gs
/**
 * Responds to a APP_HOME event in Google Chat.
 */
function onAppHome() {
  return { action: { navigations: [{
    pushCard: getHomeCard()
  }]}};
}

/**
 * Returns the app home card.
 */
function getHomeCard() {
  return { sections: [{ widgets: [
    { textParagraph: {
      text: "Here is the app home 🏠 It's " + new Date().toTimeString()
    }},
    { buttonList: { buttons: [{
      text: "Update app home",
      onClick: { action: {
        function: "updateAppHome"
      }}
    }]}}
  ]}]};
}

Node.js

node/app-home/index.js
app.post('/', async (req, res) => {
  let event = req.body.chat;

  let body = {};
  if (event.type === 'APP_HOME') {
    // App home is requested
    body = { action: { navigations: [{
      pushCard: getHomeCard()
    }]}}
  } else if (event.type === 'SUBMIT_FORM') {
    // The update button from app home is clicked
    commonEvent = req.body.commonEventObject;
    if (commonEvent && commonEvent.invokedFunction === 'updateAppHome') {
      body = updateAppHome()
    }
  }

  return res.json(body);
});

// Create the app home card
function getHomeCard() {
  return { sections: [{ widgets: [
    { textParagraph: {
      text: "Here is the app home 🏠 It's " + new Date().toTimeString()
    }},
    { buttonList: { buttons: [{
      text: "Update app home",
      onClick: { action: {
        function: "updateAppHome"
      }}
    }]}}
  ]}]};
}

Java

java/app-home/src/main/java/com/google/chat/app/home/App.java
/**
 * Process Google Chat events
 *
 * @param event Event from chat.
 * @return GenericJson
 * @throws Exception
 */
@PostMapping("/")
@ResponseBody
public GenericJson onEvent(@RequestBody JsonNode event) throws Exception {
  switch (event.at("/chat/type").asText()) {
    case "APP_HOME":
      // App home is requested
      GenericJson navigation = new GenericJson();
      navigation.set("pushCard", getHomeCard());

      GenericJson action = new GenericJson();
      action.set("navigations", List.of(navigation));

      GenericJson response = new GenericJson();
      response.set("action", action);
      return response;
    case "SUBMIT_FORM":
      // The update button from app home is clicked
      if (event.at("/commonEventObject/invokedFunction").asText().equals("updateAppHome")) {
        return updateAppHome();
      }
  }

  return new GenericJson();
}

// Create the app home card
GoogleAppsCardV1Card getHomeCard() {
  GoogleAppsCardV1TextParagraph textParagraph = new GoogleAppsCardV1TextParagraph();
  textParagraph.setText("Here is the app home 🏠 It's " + new Date());

  GoogleAppsCardV1Widget textParagraphWidget = new GoogleAppsCardV1Widget();
  textParagraphWidget.setTextParagraph(textParagraph);

  GoogleAppsCardV1Action action = new GoogleAppsCardV1Action();
  action.setFunction("updateAppHome");

  GoogleAppsCardV1OnClick onClick = new GoogleAppsCardV1OnClick();
  onClick.setAction(action);

  GoogleAppsCardV1Button button = new GoogleAppsCardV1Button();
  button.setText("Update app home");
  button.setOnClick(onClick);

  GoogleAppsCardV1ButtonList buttonList = new GoogleAppsCardV1ButtonList();
  buttonList.setButtons(List.of(button));

  GoogleAppsCardV1Widget buttonListWidget = new GoogleAppsCardV1Widget();
  buttonListWidget.setButtonList(buttonList);

  GoogleAppsCardV1Section section = new GoogleAppsCardV1Section();
  section.setWidgets(List.of(textParagraphWidget, buttonListWidget));

  GoogleAppsCardV1Card card = new GoogleAppsCardV1Card();
  card.setSections(List.of(section));

  return card;
}

更新應用程式首頁資訊卡

如果初始的應用程式主畫面資訊卡包含按鈕 (例如按鈕) Chat 應用程式必須處理 系統會傳回 RenderActions敬上 採用 updateCard 導覽模式。進一步瞭解如何處理互動式廣告 小工具,請參閱 處理使用者輸入的資訊

Python

python/app-home/main.py
def update_app_home() -> Mapping[str, Any]:
  """Update the app home

  Returns:
      Mapping[str, Any]: the update card render action
  """
  return { "renderActions": { "action": { "navigations": [{
    "updateCard": get_home_card()
  }]}}}

Apps Script

此範例會透過 資訊卡 JSON。 您也可以使用 Apps Script Card 服務

apps-script/app-home/app-home.gs
/**
 * Updates the home app.
 */
function updateAppHome() {
  return { renderActions: { action: { navigations: [{
    updateCard: getHomeCard()
  }]}}};
}

Node.js

node/app-home/index.js
// Update the app home
function updateAppHome() {
  return { renderActions: { action: { navigations: [{
    updateCard: getHomeCard()
  }]}}}
};

Java

java/app-home/src/main/java/com/google/chat/app/home/App.java
// Update the app home
GenericJson updateAppHome() {
  GenericJson navigation = new GenericJson();
  navigation.set("updateCard", getHomeCard());

  GenericJson action = new GenericJson();
  action.set("navigations", List.of(navigation));

  GenericJson renderActions = new GenericJson();
  renderActions.set("action", action);

  GenericJson response = new GenericJson();
  response.set("renderActions", renderActions);
  return response;
}

限制

一般來說 navigation 是 也不適用於 Chat 擴充應用程式您無法傳回一疊卡片。 只有 pushCard (用於初始回應) 和 updateCard (用於更新) 如下 適用於 Chat 應用程式