Tạo trang chủ cho ứng dụng Google Chat

Trang này giải thích cách tạo trang chủ cho tin nhắn trực tiếp bằng ứng dụng Google Chat. Trang chủ (được gọi là Trang chủ của ứng dụng trong API Google Chat) là một giao diện thẻ có thể tuỳ chỉnh xuất hiện trong thẻ Trang chủ của không gian tin nhắn trực tiếp 1:1 giữa người dùng và ứng dụng Chat.

Hình 1: Ví dụ về trang chủ xuất hiện trong tin nhắn trực tiếp với một ứng dụng nhắn tin.

Không giống như các ứng dụng lưu trữ khác của Google Workspace, những tiện ích bổ sung mở rộng Chat không hiển thị trang chủ trong bảng điều khiển truy cập nhanh ở bên phải và không sử dụng addOns.common.homepageTrigger trong tệp kê khai. Thay vào đó, Chat sẽ hiển thị trang chủ của bạn dưới dạng một thẻ trong thẻ Trang chủ của tin nhắn trực tiếp 1:1 với ứng dụng Chat và được định cấu hình trong Cloud Console.

Bạn có thể dùng Trang chủ ứng dụng để chia sẻ các mẹo tương tác với ứng dụng Chat, hiển thị trang tổng quan được cá nhân hoá cho người dùng hoặc cho phép người dùng truy cập và định cấu hình một dịch vụ hoặc công cụ bên ngoài từ Chat.

---

Sử dụng Trình tạo thẻ để thiết kế và xem trước giao diện người dùng và tin nhắn cho các ứng dụng Chat:

Mở Trình tạo thẻ

---

Điều kiện tiên quyết

HTTP

Một ứng dụng Google Chat nhận và phản hồi tương tác của người dùng. Để tạo một ứng dụng, hãy hoàn tất hướng dẫn bắt đầu nhanh về HTTP.

Lưu ý: Các mã mẫu trong hướng dẫn này được viết để chạy dưới dạng hàm Google Cloud Run cho Node.js.

Apps Script

Một ứng dụng Google Chat nhận và phản hồi tương tác của người dùng. Để tạo một ứng dụng, hãy hoàn tất hướng dẫn bắt đầu nhanh về Apps Script.

Định cấu hình Trang chủ ứng dụng cho ứng dụng Chat

Để hỗ trợ Trang chủ của ứng dụng, hãy bật Hỗ trợ Trang chủ của ứng dụng và định cấu hình Trang chủ của ứng dụng trình kích hoạt trong Google Cloud Console. Ứng dụng Chat của bạn sẽ nhận được sự kiện kích hoạt Trang chủ của ứng dụng bất cứ khi nào người dùng mở thẻ Trang chủ trong tin nhắn trực tiếp 1:1 với ứng dụng Chat.

Cách định cấu hình Trang chủ của ứng dụng trong Google Cloud Console:

1. Trong Google Cloud Console, hãy chuyển đến Trình đơn > API và Dịch vụ > API và Dịch vụ đã bật > Google Chat API > Cấu hình.

   Chuyển đến phần Cấu hình Chat API

2. Trong phần Tính năng tương tác, hãy đảm bảo rằng bạn đã bật Bật tính năng tương tác, sau đó trong phần Chức năng, hãy chọn hộp đánh dấu Hỗ trợ Trang chủ của ứng dụng.

3. Trong mục Connection settings (Chế độ cài đặt kết nối) > Triggers (Trình kích hoạt), hãy chỉ định trình xử lý Trang chủ ứng dụng trong trường App home (Trang chủ ứng dụng) dựa trên cấu trúc ứng dụng Chat của bạn:

   • HTTP: Nhập URL điểm cuối HTTPS xử lý các yêu cầu Trang chủ của ứng dụng (hoặc chọn Sử dụng URL điểm cuối HTTP chung cho tất cả các điều kiện kích hoạt để URL điểm cuối HTTP chung của bạn nhận được tất cả các sự kiện).
   • Google Apps Script: Nhập tên của hàm callback Google Apps Script tạo và trả về thẻ trang chủ của bạn (mặc định là onAppHome).

4. Nhấp vào Lưu.

Xử lý đối tượng sự kiện Trang chủ của ứng dụng

Khi người dùng mở thẻ Trang chủ của một tin nhắn trực tiếp 1:1 với ứng dụng Chat của bạn, Chat sẽ gửi một đối tượng sự kiện đến điểm cuối Trang chủ của ứng dụng hoặc hàm callback.

Không giống như các sự kiện tương tác trong không gian hoặc tin nhắn, đối tượng sự kiện App Home ban đầu không bao gồm tải trọng tương tác hợp nhất (chẳng hạn như messagePayload). Đối tượng này chứa các trường sau:

• commonEventObject: Bao gồm clientPlatform, hostApp ("CHAT"), userLocale và userTimezone.
• chat.user: Người dùng Chat đã mở thẻ Trang chủ.
• chat.eventTime: Dấu thời gian khi người dùng mở thẻ Trang chủ.

Tạo thẻ Trang chủ của ứng dụng

Khi người dùng mở thẻ Trang chủ, hãy xử lý sự kiện kích hoạt Trang chủ của ứng dụng bằng cách trả về một đối tượng RenderActions có thao tác điều hướng pushCard và Card. Để tạo trải nghiệm tương tác, thẻ có thể chứa các tiện ích tương tác như nút hoặc đầu vào văn bản.

HTTP

{
  "action": {
    "navigations": [
      {
        "pushCard": {
          "header": {
            "title": "Welcome to App Home"
          },
          "sections": [
            {
              "widgets": [
                {
                  "textParagraph": {
                    "text": "Manage your settings and view your dashboard here."
                  }
                },
                {
                  "buttonList": {
                    "buttons": [
                      {
                        "text": "Refresh",
                        "onClick": {
                          "action": {
                            "function": "https://example.com/updateAppHome"
                          }
                        }
                      }
                    ]
                  }
                }
              ]
            }
          ]
        }
      }
    ]
  }
}

Apps Script

/**
 * Builds and returns the App Home card when a user opens the Home tab.
 *
 * @param {Object} event The event object from Google Chat.
 * @return {ActionResponse} The RenderActions response pushing the homepage card.
 */
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.'))
              .addWidget(
                  CardService.newButtonSet().addButton(
                      CardService.newTextButton()
                          .setText('Refresh')
                          .setOnClickAction(
                              CardService.newAction().setFunctionName(
                                  'updateAppHome')))))
      .build();

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

Phản hồi các lượt tương tác trên Trang chủ của ứng dụng

Nếu thẻ Trang chủ của ứng dụng có chứa các tiện ích mang tính tương tác, chẳng hạn như nút hoặc đầu vào biểu mẫu, thì việc nhấp vào một nút sẽ gửi một đối tượng sự kiện chứa chat.buttonClickedPayload (cùng với commonEventObject.parameters và commonEventObject.formInputs) đến hàm hành động hoặc điểm cuối được định cấu hình của nút.

Để cập nhật thẻ Trang chủ của ứng dụng nhằm phản hồi một lượt tương tác của người dùng, hãy trả về một đối tượng RenderActions có thao tác điều hướng updateCard. Để tìm hiểu thêm về cách đọc dữ liệu đầu vào của biểu mẫu từ các tiện ích tương tác, hãy xem phần Đọc dữ liệu đầu vào của biểu mẫu do người dùng nhập trên thẻ.

HTTP

{
  "action": {
    "navigations": [
      {
        "updateCard": {
          "header": {
            "title": "Welcome to App Home"
          },
          "sections": [
            {
              "widgets": [
                {
                  "textParagraph": {
                    "text": "Last updated: 2026-10-02T23:00:00Z"
                  }
                }
              ]
            }
          ]
        }
      }
    ]
  }
}

Apps Script

/**
 * Updates the App Home card when a user clicks the Refresh button.
 *
 * @param {Object} event The event object from Google Chat.
 * @return {ActionResponse} The RenderActions response updating the homepage card.
 */
function updateAppHome(event) {
  const updatedCard = CardService.newCardBuilder()
      .setHeader(
          CardService.newCardHeader().setTitle('Welcome to App Home'))
      .addSection(
          CardService.newCardSection().addWidget(
              CardService.newTextParagraph().setText(
                  'Last updated: ' + new Date().toTimeString())))
      .build();

  return CardService.newActionResponseBuilder()
      .setNavigation(CardService.newNavigation().updateCard(updatedCard))
      .build();
}

Mở hộp thoại trên Trang chủ của ứng dụng

Ứng dụng Chat cũng có thể phản hồi các hoạt động tương tác trong Trang chủ của ứng dụng bằng cách mở hộp thoại.

Hình 2: Hộp thoại nhắc người dùng thêm một người liên hệ.

Để tìm hiểu cách mở, cập nhật và đóng hộp thoại bằng RenderActions (pushCard, updateCard và endNavigation: "CLOSE_DIALOG"), hãy xem phần Mở hộp thoại tương tác.

Chủ đề có liên quan

• Nhận và phản hồi các hoạt động tương tác của người dùng
• Mở hộp thoại tương tác
• Đọc dữ liệu biểu mẫu do người dùng nhập trên thẻ
• Xem các mẫu ứng dụng Chat

Các ứng dụng Chat không phải là tiện ích bổ sung: Tạo trang chủ cho ứng dụng Chat

Nếu bạn duy trì một ứng dụng Chat không phải là tiện ích bổ sung của Google Workspace, thì Chat sẽ gửi một sự kiện tương tác APP_HOME khi người dùng mở thẻ Trang chủ và gửi các sự kiện tương tác CARD_CLICKED hoặc SUBMIT_FORM khi người dùng tương tác với các tiện ích trên thẻ Trang chủ của ứng dụng.

Để nâng cấp một ứng dụng Chat không phải là tiện ích bổ sung lên khung tiện ích bổ sung của Google Workspace, hãy xem phần Chuyển đổi ứng dụng Google Chat thành tiện ích bổ sung của Google Workspace.

Tạo thẻ Màn hình chính của ứng dụng trong một ứng dụng Chat không phải là tiện ích bổ sung

Trong một ứng dụng Chat không phải là tiện ích bổ sung, hãy xử lý sự kiện tương tác APP_HOME bằng cách trả về một phản hồi chứa trường renderActions cấp cao nhất có chế độ điều hướng pushCard:

Node.js

node/app-home/index.js

Xem trên 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

Xem trên 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

Xem trên GitHub

// Process Google Chat events
@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() {
  return new GoogleAppsCardV1Card()
    .setSections(List.of(new GoogleAppsCardV1Section()
      .setWidgets(List.of(
        new GoogleAppsCardV1Widget()
          .setTextParagraph(new GoogleAppsCardV1TextParagraph()
            .setText("Here is the app home 🏠 It's " + new Date())),
        new GoogleAppsCardV1Widget()
          .setButtonList(new GoogleAppsCardV1ButtonList().setButtons(List.of(new GoogleAppsCardV1Button()
            .setText("Update app home")
            .setOnClick(new GoogleAppsCardV1OnClick()
              .setAction(new GoogleAppsCardV1Action()
                .setFunction("updateAppHome"))))))))));
}

Apps Script

Ví dụ này gửi một thông báo dạng thẻ bằng cách trả về JSON thẻ. Bạn cũng có thể sử dụng dịch vụ thẻ Apps Script.

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

Xem trên 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"
      }}
    }]}}
  ]}]};
}

Phản hồi các lượt tương tác trên Trang chủ của ứng dụng trong một ứng dụng Chat không phải là tiện ích bổ sung

Trong một ứng dụng Chat không phải là tiện ích bổ sung, hãy xử lý các sự kiện tương tác CARD_CLICKED hoặc SUBMIT_FORM từ thẻ Trang chủ của ứng dụng bằng cách trả về một phản hồi chứa trường renderActions cấp cao nhất có thao tác updateCard:

Node.js

node/app-home/index.js

Xem trên GitHub

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

Python

python/app-home/main.py

Xem trên 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

Xem trên 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

Ví dụ này gửi một thông báo dạng thẻ bằng cách trả về JSON thẻ. Bạn cũng có thể sử dụng dịch vụ thẻ Apps Script.

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

Xem trên GitHub

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