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ủ ứ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 giữa người dùng và ứng dụng Chat.

Thẻ trên màn hình chính của ứng dụng với hai tiện ích.
Hình 1: Ví dụ về trang chủ xuất hiện trong tin nhắn trực tiếp bằng một ứng dụng Chat.

Bạn có thể sử dụng trang chủ ứng dụng để chia sẻ các mẹo tương tác với ứng dụng Chat hoặc cho phép người dùng truy cập và sử dụng dịch vụ hoặc công cụ bên ngoài của Chat.


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

Mở Trình tạo thẻ

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

Node.js

Ứng dụng Google Chat đã bật các tính năng tương tác. Để tạo một ứng dụng Chat tương tác bằng dịch vụ HTTP, hãy hoàn thành phần bắt đầu nhanh này.

Python

Ứng dụng Google Chat đã bật các tính năng tương tác. Để tạo một ứng dụng Chat tương tác bằng dịch vụ HTTP, hãy hoàn thành phần bắt đầu nhanh này.

Java

Ứng dụng Google Chat đã bật các tính năng tương tác. Để tạo một ứng dụng Chat tương tác bằng dịch vụ HTTP, hãy hoàn tất hướng dẫn bắt đầu nhanh này.

Apps Script

Ứng dụng Google Chat đã bật các tính năng tương tác. Để tạo một ứng dụng Chat có thể tương tác trong Apps Script, hãy hoàn thành hướng dẫn nhanh này.

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

Để hỗ trợ trang chủ ứng dụng, bạn phải định cấu hình ứng dụng Chat để nhận các sự kiện tương tác APP_HOME. Ứng dụng Chat sẽ nhận được sự kiện này mỗi khi người dùng nhấp vào thẻ Trang chủ từ một tin nhắn trực tiếp với ứng dụng Chat.

Để cập nhật chế độ cài đặt cấu hình trong bảng điều khiển Google Cloud, hãy làm như sau:

  1. Trong Google Cloud Console, hãy chuyển đến Trình đơn > Các sản phẩm khác > Google Workspace > Thư viện sản phẩm > Google Chat API.

    Chuyển đến Google Chat API

  2. Nhấp vào Quản lý, rồi nhấp vào thẻ Cấu hình.

  3. Trong phần Tính năng tương tác, hãy chuyển đến phần Chức năng để định cấu hình trang chủ ứng dụng:

    1. Đánh dấu vào hộp Nhận tin nhắn 1:1.
    2. Đánh dấu vào hộp Trang chủ ứng dụng hỗ trợ.
  4. Nếu ứng dụng Chat của bạn sử dụng dịch vụ HTTP, hãy chuyển đến phần Cài đặt kết nối rồi chỉ định một điểm cuối cho trường URL trang chủ của ứng dụng. Bạn có thể sử dụng chính URL mà bạn đã chỉ định trong trường URL điểm cuối HTTP.

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

Tạo thẻ màn hình chính của ứng dụng

Khi người dùng mở trang chủ ứng dụng, ứng dụng Chat phải xử lý sự kiện tương tác APP_HOME bằng cách trả về một thực thể của RenderActions với thành phần điều hướng pushCardCard. Để tạo một 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 dữ liệu đầu vào văn bản mà ứng dụng Chat có thể xử lý và phản hồi bằng các thẻ bổ sung hoặc hộp thoại.

Trong ví dụ sau, ứng dụng Chat hiển thị một thẻ trang chủ ứng dụng ban đầu cho biết thời gian tạo thẻ và một nút. Khi người dùng nhấp vào nút này, ứng dụng Chat sẽ trả về một thẻ đã cập nhật cho biết thời gian tạo thẻ đã cập nhật.

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

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

Java

java/app-home/src/main/java/com/google/chat/app/home/App.java
// 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

Triển khai hàm onAppHome được gọi sau tất cả các sự kiện tương tác APP_HOME:

Ví dụ này gửi thông báo 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
/**
 * 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 hoạt động tương tác với ứng dụng trên màn hình chính

Nếu thẻ trang chủ ứng dụng ban đầu chứa các tiện ích tương tác, chẳng hạn như nút hoặc dữ liệu đầu vào lựa chọn, thì ứng dụng Chat phải xử lý các sự kiện tương tác liên quan bằng cách trả về một thực thể của RenderActions bằng thao tác điều hướng updateCard. Để tìm hiểu thêm về cách xử lý các tiện ích tương tác, hãy xem phần Xử lý thông tin do người dùng nhập.

Trong ví dụ trước, thẻ trang chủ ban đầu của ứng dụng có một nút. Bất cứ khi nào người dùng nhấp vào nút, sự kiện tương tác CARD_CLICKED sẽ kích hoạt hàm updateAppHome để làm mới thẻ trang chủ của ứng dụng, như trong mã sau:

Node.js

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

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

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

Apps Script

Ví dụ này gửi thông báo 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
/**
 * Updates the home app.
 */
function updateAppHome() {
  return { renderActions: { action: { navigations: [{
    updateCard: getHomeCard()
  }]}}};
}

Mở hộp thoại

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

Một hộp thoại hiển thị nhiều tiện ích.
Hình 3: Hộp thoại nhắc người dùng thêm một người liên hệ.

Để mở hộp thoại từ trang chủ ứng dụng, hãy xử lý sự kiện tương tác liên quan bằng cách trả về renderActions với thao tác điều hướng updateCard chứa đối tượng Card. Trong ví dụ sau, ứng dụng Chat phản hồi một lượt nhấp vào nút từ thẻ trang chủ của ứng dụng bằng cách xử lý sự kiện tương tác CARD_CLICKED và mở một hộp thoại:

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

Để đóng hộp thoại, hãy xử lý các sự kiện tương tác sau:

  • CLOSE_DIALOG: Đóng hộp thoại và quay lại thẻ trang chủ ứng dụng ban đầu của ứng dụng Chat.
  • CLOSE_DIALOG_AND_EXECUTE: Đóng hộp thoại và làm mới thẻ trang chủ của ứng dụng.

Mã mẫu sau đây dùng CLOSE_DIALOG để đóng hộp thoại và quay lại thẻ trang chủ của ứng dụng:

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

Để thu thập thông tin từ người dùng, bạn cũng có thể tạo hộp thoại tuần tự. Để tìm hiểu cách tạo hộp thoại tuần tự, hãy xem phần Mở và phản hồi hộp thoại.