本頁面由 Cloud Translation API 翻譯而成。

建構 Google Chat 應用程式的首頁

本頁說明如何建立首頁，以便與 Google Chat 應用程式。在應用程式的首頁中稱為「應用程式首頁」 Google Chat API 是「首頁」分頁中的可自訂資訊卡介面 / 即時訊息聊天室使用者與 Chat 擴充應用程式之間的連線

顯示兩個小工具的應用程式首頁資訊卡。 — **圖 1**：在 Chat 應用程式中透過即時訊息顯示的首頁範例。

您可以使用應用程式首頁，分享與 Chat 應用程式互動或讓使用者透過 Chat 存取及使用外部服務或工具的訣竅。

使用 Card Builder 設計及預覽即時通訊應用程式的訊息和使用者介面：

開啟資訊卡建立工具

必要條件

Node.js

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

Python

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

Java

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

Apps Script

已啟用互動功能的 Google Chat 應用程式。如要在 Apps Script 中建立互動式 Chat 應用程式，請完成這個快速入門。

設定 Chat 應用程式首頁

如要支援應用程式首頁，您必須設定 Chat 應用程式，以便接收 APP_HOME 互動事件。每當使用者透過 Chat 應用程式傳送即時訊息，點選「首頁」分頁時，Chat 應用程式就會收到這項事件。

如要在 Google Cloud 控制台中更新配置設定，請按照下列步驟操作：

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

前往 Google Chat API
依序按一下「管理」和「設定」分頁標籤。
在「互動功能」下方，前往「功能」專區設定應用程式首頁：
1. 勾選「接收 1:1 訊息」核取方塊。
2. 勾選「支援應用程式首頁」核取方塊。
如果 Chat 應用程式使用 HTTP 服務，請前往「連線設定」，然後在「應用程式首頁網址」欄位中指定端點。您可以使用在「HTTP 端點網址」欄位中指定的網址。
按一下 [儲存]。

建構應用程式主畫面資訊卡

當使用者開啟應用程式主畫面時，Chat 應用程式必須透過傳回 pushCard 導覽和 Card 的 RenderActions 例項，處理 APP_HOME 互動事件。如要建立就可以加入互動式小工具，例如按鈕 Chat 應用程式可處理的輸入內容或文字輸入內容以其他資訊卡或對話方塊做出回應。

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

Node.js

node/app-home/index.js

前往 GitHub 查看

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"
      }}
    }]}}
  ]}]};
}

Python

python/app-home/main.py

前往 GitHub 查看

@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"
      }}
    }]}}
  ]}]}

Java

java/app-home/src/main/java/com/google/chat/app/home/App.java

前往 GitHub 查看

/**
 * 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;
}

Apps Script

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

這個範例會傳回卡片 JSON，藉此傳送資訊卡訊息。你也可以使用 Apps Script 資訊卡服務。

apps-script/app-home/app-home.gs

前往 GitHub 查看

/**
 * 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"
      }}
    }]}}
  ]}]};
}

回應應用程式主畫面互動

如果您的初始應用程式首頁資訊卡包含互動式小工具 (例如按鈕或選取輸入內容)，Chat 應用程式必須透過 updateCard 導覽，傳回 RenderActions 的例項，以處理相關互動事件。進一步瞭解如何處理互動式廣告小工具，請參閱處理使用者輸入的資訊。

在上例中，初始的應用程式首頁資訊卡包含按鈕。只要使用者點選按鈕、CARD_CLICKED 互動事件會觸發 updateAppHome 函式來重新整理應用程式首頁資訊卡，如所示下列程式碼：

Node.js

node/app-home/index.js

前往 GitHub 查看

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

Python

python/app-home/main.py

前往 GitHub 查看

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

Java

java/app-home/src/main/java/com/google/chat/app/home/App.java

前往 GitHub 查看

// 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;
}

Apps Script

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

apps-script/app-home/app-home.gs

前往 GitHub 查看

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

開啟對話方塊

Chat 應用程式也可以開啟對話框，回應應用程式首頁中的互動內容。

顯示各種不同小工具的對話方塊。 — **圖 3**：提示使用者新增聯絡人的對話方塊。

如要從應用程式首頁開啟對話方塊，請依下列方式處理相關互動事件：使用包含 Card 的 updateCard 導覽傳回 renderActions 物件。在以下範例中，Chat 應用程式會處理 CARD_CLICKED 互動事件並開啟對話方塊，以回應應用程式首頁資訊卡的按鈕點選動作：

{ renderActions: { action: { navigations: [{ updateCard: { sections: [{
  header: "Add new contact",
  widgets: [{ "textInput": {
    label: "Name",
    type: "SINGLE_LINE",
    name: "contactName"
  }}, { textInput: {
    label: "Address",
    type: "MULTIPLE_LINE",
    name: "address"
  }}, { decoratedText: {
    text: "Add to favorites",
    switchControl: {
      controlType: "SWITCH",
      name: "saveFavorite"
    }
  }}, { decoratedText: {
    text: "Merge with existing contacts",
    switchControl: {
      controlType: "SWITCH",
      name: "mergeContact",
      selected: true
    }
  }}, { buttonList: { buttons: [{
    text: "Next",
    onClick: { action: { function: "openSequentialDialog" }}
  }]}}]
}]}}]}}}

如要關閉對話方塊，請處理下列互動事件：

CLOSE_DIALOG：關閉對話方塊並返回 Chat 應用程式的初始應用程式首頁資訊卡。
CLOSE_DIALOG_AND_EXECUTE：關閉對話方塊並重新整理應用程式首頁資訊卡

以下程式碼範例會使用 CLOSE_DIALOG 關閉對話方塊，並返回應用程式主畫面資訊卡：

{ renderActions: { action: {
  navigations: [{ endNavigation: { action: "CLOSE_DIALOG" }}]
}}}

如要向使用者收集資訊，您也可以建構連續對話方塊。如要瞭解如何建構連續對話方塊，請參閱「開啟對話方塊並回應」。

建構 Google Chat 應用程式的首頁

必要條件

Node.js

Python

Java

Apps Script

設定 Chat 應用程式首頁

建構應用程式主畫面資訊卡

Node.js

Python

Java

Apps Script

回應應用程式主畫面互動

Node.js

Python

Java

Apps Script

開啟對話方塊

相關主題